Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Dashboards and Variables

Grafana Dashboard Variables: Query, Custom, Interval and Multi-Value

Make Grafana dashboards reusable with variables: query, custom, interval, text box, data source and ad hoc filters, multi-value formats, All option and chained variables.

A dashboard with a hard-coded server name is useful once. A dashboard with a variable for the server is useful for every server. Variables appear as dropdowns at the top of the dashboard, and their selected values are substituted into queries, panel titles, links and more. This lesson covers the variable types, the substitution syntax, multi-value formatting and chaining.

Grafana does not run on this site, so interface steps are in words. The TryIt blocks are Python stand-ins that reproduce the value formatting rules so you can experiment with them.

Creating a variable

Open the dashboard, go to Settings > Variables (in newer versions the Edit mode sidebar or the Variables tab), and click Add variable. Every variable has:

  • a Name: letters, digits and underscores, used as $name. Keep it short, with no spaces, and not starting with __, which is reserved.
  • an optional Label, the text shown above the dropdown.
  • a Type that decides where values come from.
  • options for Multi-value, Include All option, and what to show (label and value, value only, or hidden).

Variable types

Type Values come from Typical use
Query A query on a data source List hosts, regions, databases
Custom A comma-separated list you type dev,staging,prod
Text box Free text typed by the viewer A customer ID or search term
Constant A fixed hidden value A shared prefix reused in many queries
Data source The list of data sources of a type Switch a dashboard between Prometheus servers
Interval Time spans such as 1m,10m,1h Let the viewer choose the aggregation step
Ad hoc filters Label key and value pairs added on the fly Free filtering on any label

A Query variable is the workhorse. For Prometheus, a query such as label_values(node_uname_info, nodename) returns every value of the label. For SQL you write SELECT DISTINCT region FROM sales ORDER BY 1, and the first column becomes the value (a second column can supply a different display text). You can also set a Regex to filter or rewrite what comes back, a Sort order, and a Refresh policy: On dashboard load or On time range change.

Using a variable

In any query or text field write $variable or ${variable}. Use the braces form when the name is next to other text: ${region}_requests. A few examples:

PROMQL
rate(http_requests_total{job="$job", instance=~"$instance"}[$__rate_interval])
SQL
SELECT $__timeGroupAlias(ts, '1h'), SUM(total) FROM orders
WHERE region IN ($region) AND $__timeFilter(ts) GROUP BY 1 ORDER BY 1

Panel titles accept variables too (CPU on $host), and so do text panels and links. The current selection is also stored in the URL as var-host=web-1, so you can share a dashboard link with the exact choice made.

Multi-value and All

Tick Multi-value and the viewer can select several values; tick Include All option and a special "All" value appears. With several values selected, Grafana must turn them into text that your query language understands, and the correct format depends on the data source:

  • Prometheus: use the regex operator, instance=~"$instance". Grafana formats multi values as (a|b|c) automatically for Prometheus.
  • SQL data sources: use IN ($region). Values are quoted for SQL, giving 'eu','us'.
  • Others: pick a format explicitly with the ${var:format} syntax.

When All is selected, Grafana substitutes every value by default, which can make a huge query. Set Custom all value to something like .* (regex) or % so that the query matches everything without listing it.

Formatting options

Syntax: ${variable:format}. Common formats:

Format Example result for a, b
csv a,b
pipe a|b
regex (a|b)
glob {a,b}
json ["a","b"]
singlequote 'a','b'
doublequote "a","b"
sqlstring 'a','b'
queryparam var-name=a&var-name=b
raw a,b unchanged by escaping
text / value Show the display text or the underlying value (when text and value differ)
Python Stand-in: multi-value formats

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Chained (dependent) variables

A query variable can use another variable in its own query. Define $cluster first, then $namespace with the query label_values(kube_pod_info{cluster="$cluster"}, namespace), and $pod that depends on both. When the viewer changes $cluster, Grafana refreshes $namespace and then $pod. Order matters: variables are listed in the order they refresh, so drag dependent ones below their parents. Avoid more than three or four levels; each level is another round of queries on load.

flowchart LR
    C["$cluster"] --> N["$namespace"]
    N --> P["$pod"]
    P --> Pn["Panels"]
    C --> Pn
    N --> Pn

Selections flow down the chain; every panel can use any of the three.

Python Stand-in: a dependent variable

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Special variables

Grafana provides built-ins you can use without defining them:

  • $__interval, $__interval_ms, $__rate_interval (see the query editor).
  • $__from and $__to: the range as Unix epoch milliseconds. ${__from:date:iso} formats them.
  • $__dashboard, $__org, $__user (for example ${__user.login}).
  • $timeFilter for some older data sources.

Good habits

  • Give variables a clear Label and sensible default (set the dashboard's saved selection).
  • Sort query variables alphabetically (or numerically) so the list is predictable.
  • Use hidden constants for repeated prefixes, so changing one value updates every query.
  • Do not make a variable query heavy: it runs on every load.
  • Keep names stable; renaming a variable does not rewrite the queries that use it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which variable type lets a viewer type any value, such as a customer ID?

    A text box variable takes free text typed into a field above the dashboard.
  2. 2. A multi-value variable is used in a Prometheus label matcher. Which operator should you write?

    Multiple values become a regex alternation, so the matcher must be a regex match, =~.
  3. 3. What does the Custom all value setting do?

    It keeps the query short by substituting a wildcard instead of listing every option.
  4. 4. How do you make $namespace depend on $cluster?

    Chained variables reference their parent in their own query; parents must come earlier in the list.

Summary

  • Variables are dropdowns whose values are substituted into queries, titles and links as $name or ${name}.
  • Types: query, custom, text box, constant, data source, interval and ad hoc filters.
  • Multi-value and All need the right operator and format (=~ for Prometheus, IN for SQL, or ${var:format}).
  • Chained variables narrow each other; order them parent first.
  • The selection lives in the URL as var-name=value, which makes dashboards shareable.

Next: Repeating Panels and Rows