Dashboard parameters

A dashboard parameter is a variable used to filter widgets on the dashboard when you open it or use it in the calculated field formulas. Parameters allow you to use visualization features more flexibly and customize the same charts and widgets for different purposes. You may find parameters useful in situations like these:

• You want to post a link to a dashboard with a filter applied: in a table on another dashboard, on a Yandex Wiki page, or somewhere else.
• You want to post the same chart with different filters on the same dashboard tab.

You can add parameters either for the whole dashboard or an individual chart on the dashboard. Dashboard parameters apply to all its charts, whereas chart parameters apply to an individual widget.

You can see the examples of how to use the parameters in this Yandex Cloud YouTube channel video.

Dashboard parametersDashboard parameters

You can use dashboard parameters to supply values to all charts while they are loading. When opening such a dashboard, its data will be filtered based on the specified values and parameter application order. By default, dashboard parameter values are not supplied to selectors, but if you specify a selector parameter, you will be able to override its value in the dashboard link.

You can add parameters in the dashboard settings. For each parameter, specify a name (key) and value. The parameter name must be the same as the name of the dataset field or parameter used to filter the data.

Providing parameters in a dashboard linkProviding parameters in a dashboard link

If the parameters are added in the dashboard settings, you can also specify the parameter values in a dashboard link. In which case clicking a link will open the dashboard with a filter applied.

The first parameter of the link is separated from the dashboard path with ?, and the remaining parameters with &. For example, the https://datalens.yandex.cloud/test-dashboard?tab=test&OrderID=123456789 link contains the values for tab and OrderID.

The values in the link will take priority. For example, if the dashboard settings have region set to RU, and the dashboard link states ?region=KZ, the KZ value will be fed to the widgets.

Chart parametersChart parameters

Chart parameters apply only to the chart itself. Thus, you can view the same chart with different filters on the same dashboard tab. You can add parameters for the chart in its settings on the dashboard.

You can transmit a parameter value to a wizard chart using field ID (see the guide).

Example of using parameters in a chart

One chart is added three times to the SLA Ticket Statistics dashboard:

• Total of tickets created: The chart is added with no parameter. Data is displayed for all tickets.
• Closed without SLA violation: The settings of the chart on the dashboard have the sla_failed parameter added with the not_failed value. Data is only displayed for the tickets closed with no SLA violations.
• Closed with violations: The settings of the chart on the dashboard have the sla_failed parameter added with the failed value. Data is only displayed for the tickets closed with SLA violations.

Special parametersSpecial parameters

Relative dateRelative date

This parameter is used to specify an offset relative to the current point in time in one of the following formats:

• __relative_<symbol><amount><unit>
• __relative_<symbol><amount><unit>_<casting_type><unit>

Where:

• <symbol>: + or -
• <unit>:
  • y: Year
  • Q: Quarter
  • M: Month
  • w: Week
  • d: Day
  • h: Hour
  • m: Minute
  • s: Second
  • ms: Millisecond
• <casting_type>:
  • s: To the start
  • e: To the end

For example, if the current time is 2020-03-24T23:30:39.874Z, then:

• __relative_-7d: Seven days back, 2020-03-17T00:00:00.000Z
• __relative_+30m: 30 minutes later, 2020-03-25T00:00:39.874Z
• __relative_-0d: Today, 2020-03-24T00:00:00.000Z
• __relative_-0h: Now, 2020-03-24T23:30:39.874Z
• __relative_-3M_sQ: Minus 3 months (2019-12-24T00:00:00.000Z) cast to the start of the quarter: 2019-10-01T00:00:00.000Z
• __relative_+15s_em: Plus 15 seconds (2020-03-24T23:30:54.874Z) cast to the end of the minute: 2020-03-24T23:30:59.999Z

IntervalInterval

This parameter allows you to set a time interval in __interval_<start>_<end> format, where start/end is a relative date or ISO date.

For example, if the current time is 2020-03-24T23:30:39.874Z, then:

• __interval_2019-03-11T09:35:48_2019-12-28T09:35:48: From 2019-03-11T09:35:48 to 2019-12-28T09:35:48
• __interval_2019-01-17T09:35:48___relative_+0d: From 2019-01-17T09:35:48 to today (2020-03-24T23:59:59.999Z)
• __interval___relative_-2w_sM___relative_+1d: Two weeks ago or more (2020-03-10T00:00:00.000Z) cast to the start of the month: 2020-03-01T00:00:00.000Z until tomorrow (2020-03-25T23:59:59.999Z)

Order of applying parametersOrder of applying parameters

Here is the order in which parameters are applied to dashboard widgets (values from the previous items are overridden by the subsequent ones):

1. Dataset parameters for charts based on this dataset.

2. For charts:

   • Wizard: Dataset parameters with overridden values at the chart level and filters.
   • QL charts: Parameters.
   • Editor: Parameters specified on the Params tab.

3. Chart parameters from dashboard settings.

4. Dashboard parameters.

5. Dasboard selector values.

6. Parameters specified in a dashboard link, e.g., https://datalens.yandex.cloud/test-dashboard?OrderID=123456789.

7. Values from the state parameter in the dashboard link. DataLens remembers the selector settings and writes them to a special parameter named state shown in the browser address bar. To share the current dashboard state, just copy the resulting link. This way, you can show the dashboard with required data directly instead of describing the filter settings.

   Note

   Changing the dashboard settings does not update the state parameter in the link, so the settings it contains become irrelevant. To get the link with relevant settings, copy it again from the browser address bar.

For example, if a dashboard parameter has a default value, it overrides the parameter value in chart settings. If a dashboard selector has a parameter with the same name, its default value overrides the dashboard parameter value. If you specify the parameter value in the dashboard link, it overrides both the selector parameter with the same name and the parameter value in chart settings.

LimitationsLimitations

The following limitations apply when using parameters:

• You cannot use the following reserved keys:

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

  Parameters with these keys are ignored and not saved.

• Links can only use parameters that are set in the dashboard settings. Otherwise, they are ignored. For example, if a link contains ?product=Furniture, but the dashboard settings have no product parameter (not even with an empty value), this parameter will be ignored.

• Dashboard parameters are applied to widgets anyway. This may lead to errors in data requests.

• Parameters cannot be used when creating links. To create a link, you can add a manual selector with the appropriate parameter key, set links using this selector by the required parameters, and then delete it. For example, for the dashboard parameter named parameter:

  1. Add a manual selector to the dashboard with parameter specified in Field or parameter name.
  2. Establish an outbound link between the new selector and the required widgets on the dashboard.
  3. Delete the selector you added from the dashboard.

  The dashboard's parameter value will now be applied to all the widgets the remote selector was connected to.