Dashboard URL variables

Dashboard URL variables allow you to provide more context when you share a dashboard URL.

For example, you could share a basic URL to your dashboard that looks like this:

https://${your-domain}/path/to/your/dashboard

This allows someone to navigate to the dashboard, but doesn't provide any helpful context that might be available.

Instead, you can add dashboard variables, passed as query parameters in the dashboard URL, to provide a URL like this:

https://${your-domain}/path/to/your/dashboard?var-example=value

This allows you to provide added context to the dashboard when someone navigates to it.

Variables as query parameters

Grafana interprets query string parameters prefixed with var- as variables in the given dashboard.

For example:

https://${your-domain}/path/to/your/dashboard?var-example=value

In this URL, the query parameter var-example=value represents the dashboard variable example with a value of value.

Multiple values for a variable

To pass multiple values, repeat the variable parameter once for each value:

https://${your-domain}/path/to/your/dashboard?var-example=value1&var-example=value2

Grafana interprets var-example=value1&var-example=value2 as the dashboard variable example with two values: value1 and value2.

Example

This dashboard in Grafana Play passes the variable server with multiple values, and the variables app and interval with a single value each.

Filters and group by dimensions

Filters automatically query your data source for available dimensions and lets users add or remove filters and group by dimensions on the dashboard dynamically. This allows you to quickly apply filters dashboard-wide to all metric queries that use the specified data source. The group by function allows you to then group data by keys, letting you split it up.

For more information, refer to Filter and Group by documentation.

To pass a filter as a query parameter, use the variable syntax to pass the filter. Then provide the key, operator, and value as a pipe-separated list.

For example:

https://${your-domain}/path/to/your/dashboard?var-filter=example_key|=|example_value

In this URL, the query parameter var-filter=key|=|value applies the configured filter using the example_key key, the = operator, and the example_value value.

{{< admonition type="note" >}} When sharing URLs with filters, remember to encode the URL. In the preceding example, replace the pipes (|) with %7C and the equality operator (=) with %3D. {{< /admonition >}}

Example

This dashboard in Grafana Play passes the filter variable Filters with the filter value job = metrictank/tsdb-gw.

Time range control using the URL

{{< docs/shared lookup="dashboards/time-range-URLs.md" source="grafana" version="<GRAFANA_VERSION>" >}}

Variables in dashboard links

When you create dashboard links the dashboard settings, you can have current dashboard variables included in the link by selecting that option:

{{< figure src="/media/docs/grafana/dashboards/screenshot-dashboard-link-variables-11.1.png" max-width="500px" alt="Dashboard link page with variables option selected" >}}

For steps to add variables to dashboard links, refer to Manage dashboard links.