Using parameters and limitations

Parameters in DataLens allow you to use visualization features more flexibly and adapt the use of the same dashboards for different purposes.

Dashboard parameters apply to all its charts.

Using the parameters might be handy, for example, when you want to post a link to a dashboard with an applied filter in another dashboard table, on a Yandex Wiki page, or somewhere else.

Dashboard parametersDashboard parameters

In the dashboard settings section, you can set the parameters to use. For each parameter, specify a key and value. The saved dashboard parameters are inserted into all widgets (including charts and selectors) once they are uploaded. When opening this dashboard, its data will be filtered based on the specified parameter values.

A parameter name must be the same as the name of the dataset field by which data is filtered.

You can also specify parameter values in dashboard links. In this case, clicking a link will open the dashboard with a filter applied.

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

The parameter values specified in the link will take priority. For example, if the dashboard settings have the region parameter set to RU and the dashboard link indicates ?region=KZ, the KZ value is inserted into widgets.

Chart parametersChart parameters

You can also set chart parameter values in its settings on a dashboard. Thus, you can view the same chart with different filters on the same dashboard tab.

You can pass a parameter value to a wizard chart using a field's ID (see the instructions).

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_<sign><number><unit>
• __relative_<sign><number><unit>_<casting_type><unit>

Where:

• <sign>: + 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: In 30 minutes, 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 is used to set a time interval in __interval_<start>_<end> format, where <start>/<end> are relative dates or ISO dates.

E.g., 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 until 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

For dashboard widgets, parameters are applied in the following order (values from the previous items are overridden by the subsequent ones):

1. Chart parameters from dashboard settings.
2. Dashboard parameters.
3. Dasboard selector values.
4. Parameters specified in a dashboard link, such as https://datalens.yandex.cloud/test-dashboard?OrderID=123456789.
5. Values from the state parameter in a dashboard link. DataLens remembers the selector settings and writes them to a special parameter named state and 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.

Parameter limitationsParameter limitations

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

  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 a null value), this parameter is 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's 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.