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

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

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

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

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

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

Имя параметра должно совпадать с названием поля в датасете, по которому фильтруются данные.

Примечание

В некоторых случаях в качестве имени параметра следует использовать ID поля:

  • если название поля задано на русском или состоит из двух слов;
  • если вы хотите использовать значение параметра в селекторе на основе датасета.

При изменении ID поля имя параметра также надо актуализировать. Подробнее см. инструкцию.

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

Примечание

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

Первый параметр в ссылке отделяется от пути до дашборда символом ?, а остальные параметры — символом &. Например, в ссылке https://datalens.yandex.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.

image

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

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

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

  • __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

Примечание

Если не указаны приведения, то для единиц измерения от дня и выше время приводится к началу дня,
т.е. 00:00:00.000, а для единиц измерения меньше дня используется текущее время.

Интервал

Параметр позволяет указать временной интервал и задается в формате __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. Параметры дашборда.
  3. Значения селекторов на дашборде.
  4. Параметры, указанные в ссылке на дашборд, например, https://datalens.yandex.ru/test-dashboard?OrderID=123456789.
  5. Значения из параметра state в ссылке на дашборд. DataLens запоминает настройки селекторов и записывает их в специальный параметр state, который фиксируется в адресной строке браузера. Чтобы поделиться текущим состоянием дашборда, достаточно скопировать получившуюся ссылку. Таким образом можно сразу показать дашборд с нужными данными вместо описания настроек фильтрации.

Ограничения для параметров

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

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

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

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

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

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

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

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

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