Работа с параметрами панели мониторинга

Статья
02/06/2025

В этой статье объясняется, как использовать параметры на панелях мониторинга ИИ/BI. Если вы хотите узнать о фильтрах полей, см. раздел "Фильтрация по полям".

Параметры панели мониторинга AI/BI позволяют заменить различные значения в запросы набора данных во время выполнения. Это позволяет фильтровать данные по таким критериям, как даты и категории продуктов, прежде чем данные агрегируются в SQL-запросе, что приводит к более эффективному запросу и точному анализу. Параметры можно использовать с мини-приложениями фильтра, чтобы сделать панели мониторинга интерактивными или с мини-приложениями визуализации, чтобы упростить повторное использование наборов данных.

Авторы панели мониторинга или редакторы добавляют параметры в наборы данных и подключают их к одному или нескольким мини-приложениям на холсте панели мониторинга. Для статических параметров, заданных в мини-приложениях визуализации, значения задаются авторами или редакторами. Для параметров, используемых в мини-приложениях фильтра, средства просмотра панелей мониторинга могут взаимодействовать с данными, выбрав значения в мини-приложениях фильтра во время выполнения. Это взаимодействие повторно запускает связанные запросы и отображает визуализации на основе отфильтрованных данных.

Параметры напрямую изменяют запрос, который может быть мощным. Фильтры полей набора данных также могут предлагать интерактивность панели мониторинга, больше возможностей и более высокую производительность с большими наборами данных, чем параметры. См. раздел "Использование фильтров".

Добавление параметра в запрос

Чтобы добавить параметр в набор данных панели мониторинга, необходимо иметь по крайней мере разрешения CAN EDIT на черновике. Параметры можно добавить непосредственно в запросы набора данных на вкладке Данные.

Gif показывает пример следующих шагов.

Чтобы добавить параметр в запрос, выполните приведенные действия.

Поставьте курсор там, где хотите разместить параметр в вашем запросе.
Щелкните Добавить параметр, чтобы вставить новый параметр.

При этом создается новый параметр с именем parameterпо умолчанию. Чтобы изменить имя по умолчанию, замените его в редакторе запросов. Вы также можете добавить параметры, введя этот синтаксис в редакторе запросов.

Изменение параметра запроса

Чтобы изменить параметр, выполните приведенные действия.

Щелкните рядом с именем параметра. Откроется диалоговое окно сведений о параметрах и включает следующие параметры конфигурации:
- Ключевое слово: ключевое слово, представляющее параметр в запросе. Это можно изменить только путем непосредственного обновления текста в запросе.
- Отображаемое имя: имя в редакторе фильтров. По умолчанию заголовок совпадает с ключевым словом.
- Тип: поддерживаемые типы включают String, Date, Date и Time, Numeric.
  - Тип по умолчанию — String.
  - Числовый тип данных позволяет указать между десятичным и целым числом. Числовой тип по умолчанию — Десятичный.
- Разрешить несколько вариантов выбора. Установите флажок, чтобы разрешить пользователям выбирать несколько параметров во время выполнения.
  
  Примечание.
  
  Для этого выбора может потребоваться дополнительное изменение запроса. См. раздел "Разрешить несколько выборок".
Щелкните другую часть пользовательского интерфейса, чтобы закрыть диалоговое окно.

Установка значения параметра по умолчанию

Чтобы выполнить запрос, выберите значение по умолчанию для параметра, введя его в текстовое поле под именем параметра. Запустите запрос, чтобы просмотреть результаты запроса с примененным значением параметра. При выполнении запроса также сохраняется значение по умолчанию. При установке этого параметра с помощью мини-приложения фильтра на холсте используется значение по умолчанию, если в мини-приложении фильтра не указано новое значение по умолчанию. См. раздел "Использование фильтров".

Разрешить несколько выборок

Запросы, разрешающие несколько выборов, должны включать ARRAY_CONTAINS функцию в запрос.

В следующем примере показан SQL-запрос, позволяющий выбрать несколько значений для вставки в запрос во время выполнения. Предложение WHERE использует функцию ARRAY_CONTAINS . Эта функция принимает ключевое слово параметра и имя столбца в качестве аргументов. Параметр должен быть задан для хранения нескольких значений, чтобы его можно было вставить в запрос в виде массива. При выполнении запроса каждая строка вычисляется, а все строки, в которых l_quantity совпадают по крайней мере с одним значением в :parameter, включаются в результирующий набор.

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

Чтобы задать значения по умолчанию, выполните следующие действия.

Напишите запрос набора данных, использующий функцию ARRAY_CONTAINS для фильтрации строк на основе списка значений.
Щелкните рядом с именем параметра. Выберите Разрешить несколько вариантов выбора.

Примечание.

Этот шаг позволяет вставить параметр в запрос в виде массива. Если функция ARRAY_CONTAINS используется без включения нескольких выделений, возникает ошибка.
Введите значение в текстовое поле под отображаемым именем. Можно ввести несколько значений. Выберите текущее значение перед вводом следующего.

значения по умолчанию задаются в редакторе. Несколько значений выбираются и разделяются пробелом.

Применить параметры диапазона дат

Параметры можно использовать для определения диапазона и возврата только результатов в этом диапазоне. При выборе одного из следующих типов параметров создаются два параметра с суффиксами .min и .max.

Диапазон дат
Диапазон даты и времени

В следующем примере показан SQL-запрос, который создает параметр диапазона дат с именем date_param.

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

Чтобы создать параметр диапазона дат, выполните приведенные действия.

Нажмите кнопку "Добавить параметр".
Щелкните рядом с именем параметра. Введите ключевое слово и отображаемое имя. Не включать .min или .max суффиксы.
Выберите диапазон дат или диапазон даты и времени в качестве типа.
Вставьте предложение WHERE, определяющее диапазон в запрос. Чтобы определить диапазон, используйте предложение BETWEEN со значениями .min и .max. Например:
```
 WHERE date_col BETWEEN :date_param.min AND :date_param.max
```
Введите значения даты по умолчанию и запустите запрос для его тестирования. Используйте значок календаря, чтобы выбрать предварительные параметры, такие как на прошлой неделе или в прошлом месяце.

Параметры на основе запросов

Параметры на основе запросов позволяют авторам определять динамический или статический список значений, которые зрители могут выбирать при задании параметров при изучении данных на панели мониторинга. Они определяются путем объединения фильтра полей и фильтра параметров в одном мини-приложении фильтра.

Чтобы создать параметр на основе запросов, автор панели мониторинга выполняет следующие действия:

Создайте набор данных, результирующий набор которого ограничен списком возможных значений параметров.
Создайте запрос набора данных, использующий параметр.
Настройте мини-приложение фильтра на холсте, который фильтрует поле и использует параметр.
- Конфигурации полей следует настроить, чтобы использовать поле с нужным списком допустимых значений параметров.
- Для выбора значения параметра следует задать параметры конфигурации.

Примечание.

Если набор данных, используемый в параметрах на основе запросов, также используется в других визуализациях на панели мониторинга, выбор фильтра средства просмотра изменяет все подключенные запросы. Чтобы избежать этого, авторы должны создать выделенный набор данных для параметров на основе запросов, которые не используются в других визуализациях на панели мониторинга.

Пошаговое руководство см. в разделе "Использование параметров на основе запросов" для демонстрации добавления параметра и визуализации на основе запросов.

Создание динамического списка параметров

Чтобы создать динамический набор данных, заполняющий раскрывающийся список, который используется для выбора значений параметров, напишите SQL-запрос, возвращающий одно поле и включающий все значения в этом поле. Любое новое значение в этом поле автоматически добавляется в качестве выбора параметров. Ниже приведен пример SQL-запроса.

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Создание списка статических параметров

Вы можете создать статический набор данных, содержащий только значения, которые вы жестко задаете в своем наборе данных. Пример запроса выглядит следующим образом:

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

Удаление параметра запроса

Чтобы удалить параметр, удалите его из запроса.

Статические параметры мини-приложения настраиваются непосредственно в мини-приложении визуализации, что позволяет авторам отдельно параметризовать мини-приложения визуализации, которые используют один набор данных. Это позволяет одному набору данных представлять различные представления на холсте.

Пример в этом разделе основан на наборе данных, который запрашивает таблицу samples.nyctaxi.trips. Предоставленный запрос возвращает расстояние каждой поездки и классифицирует день сбора как Weekday или Weekend. Параметр запроса фильтрует результаты на основе того, произошло ли получение в будний день или выходные дни.

Текст запроса представлен в следующем блоке кода, но инструкции в этом разделе ограничены настройкой связанных визуализаций, настроенных со статическими параметрами мини-приложения. Инструкции по настройке набора данных с параметрами см. в статье Добавление параметра в запрос.


  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

Чтобы добавить статический параметр мини-приложения в визуализацию:

Добавьте мини-приложение визуализации на черновик панели мониторинга.
Выбрав новое мини-приложение, выберите параметризованный набор данных в раскрывающемся списке набора данных на панели конфигурации.
Нажмите кнопку "Показать фильтры". Для наборов данных, включающих параметры, в панели конфигурации появится раздел Параметры.
Щелкните знак плюса справа от надписи Параметры и выберите параметр в выпадающем списке.
По умолчанию значение параметра отражает то, что задано в запросе на вкладке Данных. Его можно сохранить или выбрать новое значение для замены в набор данных. Перейдите от текстового поля, чтобы отобразить визуализацию с примененным новым параметром.
Просмотрите панель мониторинга.

На следующем рисунке показаны два мини-приложения визуализации. Каждая из них настраивается как гистограмма со статическим параметром мини-приложения. Диаграмма слева показывает распределение расстояний поездки для поездок, начиная с будних дней, в то время как диаграмма справа показывает те же данные для выходных. Оба визуализации основаны на одном наборе данных.

Сравнение данных с помощью условия фильтра

Можно добавить условие фильтра, позволяющее сравнивать агрегаты части данных с агрегатами, применяемыми ко всему набору данных.

Следующий пример расширяет предыдущий запрос, чтобы включить условие фильтра, в котором указанное значение параметра All, которое не отображается в данных. Первая часть условия фильтра работает так же, как в предыдущем примере, фильтруя результаты, в которых day_type - это Weekday или Weekend. Вторая часть условия фильтра проверяет, задан ли сам параметр определенным значением, в данном случае All, который не отображается в данных. При установке значения по умолчанию для этого параметра в редакторе наборов данных вы эффективно обходят фильтр, если ни Weekday, ни Weekend передаются в качестве значений.


WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

Этот набор данных можно использовать для настройки трех виджетов визуализации, при этом day_type_param настраивается на All, а затем на Weekday и Weekend соответственно. Затем средства просмотра панелей мониторинга могут сравнить каждый набор данных, отфильтрованный по типу дня, со всем набором данных.

В следующем GIF-файле показано, как быстро создавать три диаграммы из набора данных, созданного с помощью этого запроса.

Первая диаграмма настроена для отображения расстояний поездки по типу дня с набором данных и значением параметра будний день.
Клонируйте диаграмму для поддержания всех примененных конфигураций.
Чтобы отобразить данные для поездок, выполненных в выходные дни, настройте статический параметр на Выходные.
Клонируйте новую диаграмму для поддержания всех ранее примененных конфигураций.
Задайте для параметра в новой диаграмме значение Все, чтобы отобразить общее количество поездок по расстоянию для поездок в выходные и будние дни.

Gif, как описано в предыдущем тексте.

Отображение параметров на панели мониторинга

Добавление фильтра на холст панели мониторинга позволяет зрителям выбирать и изменять значения параметров для интерактивного изучения и анализа данных. Если не предоставить параметр на панели мониторинга, пользователи увидят только результаты, которые используют значение параметра по умолчанию, указанное в запросе.

Чтобы добавить параметр на панель мониторинга, выполните приведенные действия.

Нажмите кнопку "Добавить фильтр" (поле или параметр).
Щелкните значок рядом с параметрами на панели конфигурации.
Щелкните имя параметра, которое будет использоваться средством просмотра с этим мини-приложением.

Работа с мини-приложениями фильтра и статическими параметрами

Параметры являются фиксированными значениями, замененными в запрос во время выполнения. Если два или более ссылок на один и тот же параметр задаются с разными значениями при обновлении панели мониторинга, мини-приложения визуализации отображают ошибку, указывающую, какой параметр имеет конфликтующие значения. Это может произойти, если несколько мини-приложений фильтра используют один и тот же параметр или когда статический параметр конфликтует с мини-приложением фильтра, которое позволяет выбрать средство просмотра.

Вы можете использовать такой шаблон, как в следующем примере, для задания резервных значений для разных параметров в одном запросе.


CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

В этом примере :static_param относится к статическому параметру, который должен иметь значение All в мини-приложении визуализации и редакторе наборов данных. Параметр :dash_param — это динамическое значение, управляемое мини-приложением фильтра на холсте панели мониторинга. Эта инструкция проверяет значение, предоставленное как статический параметр. Если параметр панели мониторинга не задан, он возвращается к значению параметра панели мониторинга, выбранного средством просмотра.

Включение параметров в URL-адрес

Настройки параметров хранятся в URL-адресе, позволяя пользователям сохранять его в закладках, чтобы поддерживать состояние панели управления, включая предварительно заданные фильтры и параметры, или поделиться им с другими, чтобы применить те же фильтры и параметры последовательно.

Параметры панели мониторинга vs. параметры запроса Mustache

Параметры панели мониторинга используют тот же синтаксис, что и именованные маркеры параметров. См . метки именованных параметров. Панели не поддерживают параметры стиля Mustache.

Примеры синтаксиса

Распространенные способы использования параметров включают вставку дат, чисел, текста, объектов базы данных и значений из строк JSON. Примеры, демонстрирующие использование параметров в этих случаях, смотрите в разделе примеры синтаксиса именованных параметров.

Внимание

Предоставление возможности пользователям доступа к данным через выбор параметров, таких как имена таблиц или каталогов, может случайно привести к разглашению конфиденциальной информации. Если вы публикуете панель мониторинга с этими параметрами, Azure Databricks рекомендует не внедрять учетные данные в опубликованную панель мониторинга.

Поделиться через