Параметры дашборда в Yandex DataLens

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

• Вы хотите где-то разместить ссылку на дашборд с примененным фильтром: в таблице на другом дашборде, на странице в Yandex Wiki или в другом месте.
• Вы хотите разместить один и тот же чарт с разными фильтрами на одной вкладке дашборда.

Можно добавлять параметры как для всего дашборда, так и для отдельного чарта на дашборде. Параметры дашборда применяются ко всем чартам, которые на нем расположены, а параметры чарта — к отдельному виджету.

Примеры использования параметров можно посмотреть в записи на YouTube-канале Yandex Cloud.

Параметры для дашбордаПараметры для дашборда

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

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

Передача параметров в ссылке на дашбордПередача параметров в ссылке на дашборд

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

Первый параметр в ссылке отделяется от пути до дашборда символом ?, а остальные параметры — символом &. Например, в ссылке https://datalens.ru/test-dashboard?tab=test&OrderID=123456789 указаны значения для параметров tab и OrderID.

Значения параметров в ссылке будут приоритетными. Например, если в настройках дашборда для параметра region задано значение RU, а в ссылке на дашборд указано ?region=KZ, то в виджеты будет подставлено значение KZ.

Параметры для чартаПараметры для чарта

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

Передать значение параметра в визардный чарт можно с помощью ID поля (см. инструкцию).

Пример использования параметров в чарте

На дашборд Статистика SLA тикетов добавлен три раза один чарт:

• Всего тикетов заведено — чарт добавлен без параметра. Отображаются данные по всем тикетам.
• Закрыто без нарушения SLA — в настройках чарта на дашборде добавлен параметр sla_failed со значением not_failed. Отображаются данные только по тикетам, закрытым без нарушения SLA.
• Закрыто с нарушениями — в настройках чарта на дашборде добавлен параметр sla_failed со значением failed. Отображаются данные только по тикетам, закрытым с нарушением SLA.

Специальные параметрыСпециальные параметры

Относительная датаОтносительная дата

Параметр позволяет указать смещение относительно текущего момента времени и задается в одном из форматов:

• __relative_<знак><количество><единица_измерения>
• __relative_<знак><количество><единица_измерения>_<тип_приведения><единица_измерения>

Где:

• <знак>: + или -
• <единица_измерения>:
  • y — год
  • Q — квартал
  • M — месяц
  • w — неделя
  • d — день
  • h — час
  • m — минута
  • s — секунда
  • ms — миллисекунда
• <тип_приведения>:
  • s — к началу
  • e — к концу

Например, если время на данный момент 2020-03-24T23:30:39.874Z, то:

• __relative_-7d— семь дней назад — 2020-03-17T00:00:00.000Z
• __relative_+30m — через 30 минут — 2020-03-25T00:00:39.874Z
• __relative_-0d — сегодня — 2020-03-24T00:00:00.000Z
• __relative_-0h — сейчас — 2020-03-24T23:30:39.874Z
• __relative_-3M_sQ — минус 3 месяца (2019-12-24T00:00:00.000Z), приведенные к началу квартала — 2019-10-01T00:00:00.000Z
• __relative_+15s_em — плюс 15 секунд (2020-03-24T23:30:54.874Z), приведенные к концу минуты — 2020-03-24T23:30:59.999Z

ИнтервалИнтервал

Параметр позволяет указать временной интервал и задается в формате __interval_<начало>_<конец>, где начало/конец — относительная дата или ISO дата.

Например, если время на данный момент 2020-03-24T23:30:39.874Z, то:

• __interval_2019-03-11T09:35:48_2019-12-28T09:35:48 — с 2019-03-11T09:35:48 по 2019-12-28T09:35:48
• __interval_2019-01-17T09:35:48___relative_+0d — с 2019-01-17T09:35:48 по сегодня (2020-03-24T23:59:59.999Z)
• __interval___relative_-2w_sM___relative_+1d — от двух недель назад (2020-03-10T00:00:00.000Z), приведенных к началу месяца — 2020-03-01T00:00:00.000Z до завтра (2020-03-25T23:59:59.999Z)

Порядок применения параметровПорядок применения параметров

Параметры применяются к виджетам дашборда в следующем порядке (значения из последующих пунктов переопределяют предыдущие):

1. Параметры датасета для чартов, созданных на основе этого датасета.

2. Для чартов:

   • в визарде — параметры датасета с переопределенными значениями на уровне чарта и фильтры;
   • QL-чарты — параметры;
   • в Editor — параметры, указанные на вкладке Params.

3. Параметры чартов из настроек дашборда.

4. Параметры дашборда.

5. Значения селекторов на дашборде.

6. Параметры, указанные в ссылке на дашборд, например, https://datalens.ru/test-dashboard?OrderID=123456789.

7. Значения из параметра state в ссылке на дашборд. DataLens запоминает настройки селекторов и записывает их в специальный параметр state, который фиксируется в адресной строке браузера. Чтобы поделиться текущим состоянием дашборда, достаточно скопировать получившуюся ссылку. Таким образом можно сразу показать дашборд с нужными данными вместо описания настроек фильтрации.

   Примечание

   При изменении настроек дашборда параметр state в ссылке не обновляется — записанные в нем настройки теряют актуальность. Чтобы получить ссылку с актуальными настройками, скопируйте ее заново из адресной строки браузера.

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

ОграниченияОграничения

При использовании параметров существуют следующие ограничения:

• Зарезервированные ключи, которые нельзя использовать:

  • tab
  • state
  • mode
  • focus
  • grid
  • scale
  • tz
  • timezone
  • date
  • datetime
  • _action_params
  • _autoupdate
  • _opened_info
  • report_page
  • preview_mode

  Параметры с такими ключами будут проигнорированы и не будут сохранены.

• В ссылках могут быть использованы только те параметры, которые заданы в настройках дашборда. В противном случае они будут проигнорированы. Например, если в ссылке будет указано ?product=Furniture, но в настройках дашборда не будет задан параметр product (даже с пустым значением), то такой параметр будет проигнорирован.

• Параметры дашборда в любом случае будут применены к виджетам, что может привести к ошибкам в запросах данных.

• Параметры не могут быть использованы при создании связей. Для создания связи вы можете добавить ручной селектор с нужным ключом параметра, сделать связи с ним по нужным параметрам, а потом удалить его. Например, для параметра дашборда parameter:

  1. Добавьте на дашборд ручной селектор, указав в Имя поля или параметра parameter.
  2. Установите исходящую связь нового селектора с необходимыми виджетами на дашборде.
  3. Удалите добавленный селектор с дашборда.

  Теперь значение параметра дашборда parameter будет применено ко всем виджетам, с которыми была установлена связь удаленного селектора.