Dashboard parameters
The 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 adapt the use of the same charts and widgets for different purposes. It may be helpful to use parameters in cases such as:
- You want to post a link to a dashboard with a filter applied: in another dashboard table, 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 both for the whole dashboard and for a separate chart on the dashboard. Dashboard parameters apply to all its charts, while 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 dashboard links. In this case, clicking a link will open the dashboard with a filter applied.
Note
To have the parameter value inserted 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 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 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 pass a transmit value to a wizard chart using field ID (see the instructions).
One chart is added three times to the Ticket SLA 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
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
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