Dashboard parameters
A dashboard parameter is a variable used to filter widgets on the dashboard when you open it. 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 parameters
Dashboard parameters are substituted into all widgets (including charts and selectors) when they are uploaded. When opening such a dashboard, its data will be filtered based on the specified parameter values. 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 by which data is filtered.
Note
In some cases, you should use the field ID as the parameter name:
- If the field name contains Cyrillic characters or consists of two words.
- If you want to use the parameter value in a selector based on a dataset.
If the field ID changes, you should also update the parameter name. For more information, see this guide.
You can also specify parameter values in a dashboard link. In which case clicking a link will open the dashboard with a filter applied.
Note
To have the parameter value substituted into the dataset-based selector when you click the link, specify the field ID both as the parameter name and in the dashboard link.
The first parameter of the link is separated from the dashboard path with ?
, and the remaining parameters with &
. For example, the link 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 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 thenot_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 thefailed
value. Data is only displayed for the tickets closed with SLA violations.
Special parameters
Relative 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
: YearQ
: QuarterM
: Monthw
: Weekd
: Dayh
: Hourm
: Minutes
: Secondms
: Millisecond
<casting_type>
:s
: To the starte
: To the end
E.g., 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
Note
If the casting is not specified, then for the units of day and longer, the time is cast to the start of the day, i.e., 00:00:00.000
, and shorter units cast to the current time.
Interval
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
: From2019-03-11T09:35:48
to2019-12-28T09:35:48
__interval_2019-01-17T09:35:48___relative_+0d
: From2019-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 parameters
For dashboard widgets, parameters are applied in the following order (values from the previous items are overridden by the subsequent ones):
- Chart parameters from dashboard settings.
- Dashboard parameters.
- Dasboard selector values.
- Parameters specified in a dashboard link, e.g,
https://datalens.yandex.cloud/test-dashboard?OrderID=123456789
. - Values from the
state
parameter in a dashboard link. DataLens remembers the selector settings and writes them to a special parameter namedstate
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.
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
_opened_info
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 noproduct
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
:- Add a manual selector to the dashboard with
parameter
specified in Field or parameter name. - Establish an outbound link between the new selector and the required widgets on the dashboard.
- 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. - Add a manual selector to the dashboard with