Variable types - Amazon Managed Grafana
Adding a query variableAdding a custom variableAdding a text box variableAdding a constant variableAdding a data source variableAdding an interval variableAdding ad hoc filtersChained variablesGlobal variables

Variable types

This documentation topic is designed for Grafana workspaces that support Grafana version 8.x.

For Grafana workspaces that support Grafana version 10.x, see Working in Grafana version 10.

For Grafana workspaces that support Grafana version 9.x, see Working in Grafana version 9.

Grafana uses several types of variables.

Variable type Description
Query Query-generated list of values such as metric names, server names, sensor IDs, data centers, and so on. For more information, see Adding a query variable.
Custom Define the variable options manually using a comma-separated list. For more information, see Adding a custom variable.
Text box Display a text input field with an optional default value. For more information, see Adding a text box variable.
Constant Define a hidden constant. For more information, see Adding a constant variable.
Data source Quickly change the data source for an entire dashboard. For more information, see Adding a data source variable.
Interval Interval variables represent time spans. For more information, see Adding an interval variable.
Ad hoc filters Key/value filters that are automatically added to all metric queries for a data source (InfluxDB, Prometheus, and OpenSearch only). For more information, see Adding ad hoc filters.
Global variables Built-in variables that can be used in expressions in the query editor. For more information, see Global variables.
Chained variables Variable queries can contain other variables. For more information, see Chained variables.

Adding a query variable

Using query variables, you can write a data source query that returns a list of metric names, tag values, or keys. For example, a query variable might return a list of server names, sensor IDs, or data centers. The variable values change as they dynamically fetch options with a data source query.

Query expressions can contain references to other variables and, in effect, create linked variables. Grafana detects this and automatically refreshes a variable when one of its linked variables change.

Query expressions

Query expressions are different for each data source. For more information, see the documentation for your data source at Connect to data sources.

Entering general options

To enter general options for a query variable

  1. Navigate to the dashboard that you want to make a variable for, and then choose the Dashboard settings (gear) icon at the top of the page.

  2. On the Variables tab, choose New.

  3. Enter a Name for your variable.

  4. In the Type list, select Query.

  5. (Optional) For Label, enter the display name of the variable dropdown list. If you don’t enter a display name, the dropdown label will be the variable name.

  6. Choose a Hide option:

    • No selection (blank) – The variable dropdown list displays the variable Name or Label value. This is the default.

    • Label – The variable dropdown list displays only the selected variable value and a down arrow.

    • Variable – No variable dropdown list is displayed on the dashboard.

Entering query options

To enter query options for a query variable

  1. In the Data source list, select the target data source for the query. For more information about data sources, see Connect to data sources.

  2. In the Refresh list, select when the variable should update options.

    • Never - Caches variable queries, and values are not updated. This is fine if the values never change, but problematic if they are dynamic and change a lot.

    • On Dashboard Load - Queries the data source every time the dashboard loads. This slows down dashboard loading, because the variable query must to be completed before dashboard can be initialized.

    • On Time Range Change - Queries the data source when the dashboard time range changes. Use this option only if your variable options query contains a time range filter or is dependent on the dashboard time range.

  3. In the Query field, enter a query.

    • The query field varies according to your data source. Some data sources have custom query editors.

    • If you need more room in a single input field query editor, pause on the lines in the lower right corner of the field and drag downward to expand.

  4. (Optional) In the Regex field, type a regex expression to filter or capture specific parts of the names returned by your data source query. For examples, see Filtering variables with regex.

  5. In the Sort list, select the sort order for values to be displayed in the dropdown list. The default option, Disabled, means that the order of options returned by your data source query will be used.

  6. (Optional) Enter Selection Options. For more information, see Entering variable selection options.

  7. In Preview of values, the Grafana workspace displays a list of the current variable values. Review them to ensure they match what you expect.

  8. Choose Add to add the variable to the dashboard.

Adding a custom variable

Use a custom variable for values that do not change. This might be numbers, strings, or even other variables.

For example, if you have server names or region names that do not change, you can create them as custom variables rather than query variables. Because they do not change, you might use them in chained variables rather than other query variables. That would reduce the number of queries Grafana must send when chained variables are updated. For more information about chained variables, see Chained variables.

Entering general options

To enter query options for a custom variable

  1. Navigate to the dashboard you want to make a variable for and then choose the Dashboard settings (gear) icon at the top of the page.

  2. On the Variables tab, choose New.

  3. Enter a Name for your variable.

  4. In the Type list, choose Custom.

  5. (Optional) For Label, enter the display name of the variable dropdown list. If you don’t enter a display name, the dropdown label will be the variable name.

  6. Choose a Hide option:

    • No selection (blank) – The variable dropdown list displays the variable Name or Label value. This is the default.

    • Label ‐ The variable list dropdown displays only the selected variable value and a down arrow.

    • Variable – No variable dropdown list is displayed on the dashboard.

Entering custom options

To enter custom options for a custom variable

  1. In the Values separated by comma list, enter the values for this variable in a comma-separated list. You can include numbers, strings, other variables, or key-value pairs separated by a colon.

  2. (Optional) Enter Selection Options. For more information, see Entering variable selection options.

  3. In Preview of values, the Grafana workspace displays a list of the current variable values. Review them to ensure they match what you expect.

  4. Choose Add to add the variable to the dashboard.

Adding a text box variable

Text box variables display a text input field with an optional default value. This is the most flexible variable, because you can enter any value. Use this type of variable if you have metrics with high cardinality or if you want to update multiple panels in a dashboard at the same time.

Entering general options

To enter general options for a text box variable

  1. Navigate to the dashboard you want to make a variable for and then choose the Dashboard settings (gear) icon at the top of the page.

  2. On the Variables tab, choose New.

  3. Enter a Name for your variable.

  4. In the Type list, select Text box.

  5. (Optional) For Label, enter the display name of the variable dropdown list. If you don’t enter a display name, then the dropdown label will be the variable name.

  6. Choose a Hide option:

    • No selection (blank) – The variable dropdown list displays the variable Name or Label value. This is the default.

    • Label – The variable dropdown list displays only the selected variable value and a down arrow.

    • Variable – No variable dropdown list is displayed on the dashboard.

Entering text options

To enter text options for a text box variable

  1. (Optional) In the Default value field, select the default value for the variable. If you do not enter anything in this field, then Grafana displays an empty text box that you can type text into.

  2. In Preview of values, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.

  3. Choose Add to add the variable to the dashboard.

Adding a constant variable

To define a hidden constant, use constant variables. Constant variables are useful for metric path prefixes for dashboards you want to share. When you export a dashboard, constant variables are converted to import options.

Constant variables are not flexible. Each constant variable holds only one value. To update it, you must update the variable settings.

Constant variables are useful when you have complex values that you must include in queries but don’t want to retype in every single query. For example, if you had a server path called i-0b6a61efe2ab843gg, you could replace it with a variable called $path_gg.

Entering general options

To enter general options for a constant variable

  1. Navigate to the dashboard that you want to make a variable for and then choose the Dashboard settings (gear) icon at the top of the page.

  2. On the Variables tab, choose New.

  3. Enter a Name for your variable.

  4. In the Type list, select Constant.

  5. (Optional) For Label, enter the display name of the variable dropdown list. If you don’t enter a display name, then the dropdown label will be the variable name.

  6. Choose a Hide option:

    • Variable – No variable dropdown list is displayed on the dashboard. This is the default.

    • No selection (blank) – The variable dropdown list displays the variable Name or Label value.

    • Label – The variable dropdown list displays only the selected variable value and a down arrow.

Entering constant options

To enter constant options for a constant variable

  1. In the Value field, enter the variable value. You can enter letters, numbers, and symbols. If you use advanced variable format options, you can even use wild cards. For more information, see Advanced variable format options.

  2. In Preview of values, the Grafana workspace displays the current variable value. Review it to ensure it matches what you expect.

  3. Choose Add to add the variable to the dashboard.

Adding a data source variable

To change the data source for an entire dashboard quickly, you can use data source variables. They are useful if you have multiple instances of a data source, perhaps in different environments.

Entering general options

To enter general options for a data source variable

  1. Navigate to the dashboard you want to make a variable for, and then choose the Dashboard settings (gear) icon at the top of the page.

  2. On the Variables tab, choose New.

  3. Enter a Name for your variable.

  4. In the Type list, select Datasource.

  5. (Optional) For Label, enter the display name of the variable dropdown list. If you don’t enter a display name, the dropdown label will be the variable name.

  6. Choose a Hide option:

    • No selection (blank) – The variable dropdown list displays the variable Name or Label value. This is the default.

    • Label – The variable dropdown list displays only the selected variable value and a down arrow.

    • Variable – No variable dropdown list is displayed on the dashboard.

Entering data source options

To enter data source options for a data source variable

  1. In the Type list, select the target data source for the variable. For more information about data sources, see Connect to data sources.

  2. (Optional) For Instance name filter, enter a regex filter for which data source instances to choose from in the variable value drop-down list. Keep this field empty to display all instances.

  3. (Optional) Enter Selection Options. For more information, see Entering variable selection options.

  4. In Preview of values, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.

  5. Choose Add to add the variable to the dashboard.

Adding an interval variable

Use an interval variable to represent time spans such as 1m,1h, 1d. You can think of them as a dashboard-wide group-by-time command. Interval variables change how the data is grouped in the visualization. You can also use the Auto option to return a set number of data points per time span.

You can use an interval variable as a parameter to group by time (for InfluxDB), date histogram interval (for OpenSearch), or as a summarize function parameter (for Graphite).

Entering general options

To enter general options for an interval variable

  1. Navigate to the dashboard you want to make a variable for and then choose the Dashboard settings (gear) icon at the top of the page.

  2. On the Variables tab, choose New.

  3. Enter a Name for your variable.

  4. In the Type list, select Interval.

  5. (Optional) For Label, enter the display name of the variable dropdownlist . If you don’t enter a display name, the dropdown label will be the variable name.

  6. Choose a Hide option:

    • No selection (blank) – The variable dropdown list displays the variable Name or Label value. This is the default.

    • Label – The variable dropdown list displays only the selected variable value and a down arrow.

    • Variable – No variable dropdown list is displayed on the dashboard.

Entering interval options

To enter interval options for an interval variable

  1. In the Values field, enter the time range intervals that you want to appear in the variable drop-down list. The following time units are supported: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), and y (years). You can also accept or edit the default values: 1m,10m,30m,1h,6h,12h,1d,7d,14d,30d.

  2. (Optional) Turn on Auto Option if you want to add the auto option to the list. Use this option to specify how many times the current time range should be divided to calculate the current auto time span. If you turn it on, then two more options appear:

    • Step count – Select the number of times that the current time range will be divided to calculate the value, similar to the Max data points query option. For example, if the current visible time range is 30 minutes, then the auto interval groups the data into 30 one-minute increments. The default value is 30 steps.

    • Min Interval – The minimum threshold below which the step count intervals will not divide the time. To continue the 30-minute example, if the minimum interval is set to 2m, Grafana groups the data into 15 2-minute increments.

  3. In Preview of values, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.

  4. Choose Add to add the variable to the dashboard.

Interval variable examples

Example using the template variable myinterval in a Graphite function: 


summarize($myinterval, sum, false)

A more complex Graphite example: 


groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5), '$interval', 'sum', false), 2, 'sum')

Adding ad hoc filters

You can use one-time, or ad hoc filters to add key/value filters that are automatically added to all metric queries that use the specified data source. Unlike other variables, you do not use one-time filters in queries. Instead, you use them to write filters for existing queries.

Note

Note: One-time, or ad hoc, filter variables work only with InfluxDB, Prometheus, and OpenSearch data sources.

Entering general options

To enter general options for an ad hoc filter

  1. Navigate to the dashboard that you want to make a variable for, and then choose the Dashboard settings (gear) icon at the top of the page.

  2. On the Variables tab, choose New.

  3. Enter a Name for your variable.

  4. In the Type list, select Ad hoc filters.

  5. (Optional) For Label, enter the display name of the variable dropdown list. If you don’t enter a display name, the dropdown label will be the variable name.

  6. Choose a Hide option:

    • No selection (blank) – The variable dropdown list displays the variable Name or Label value. This is the default.

    • Label – The variable dropdown list displays only the selected variable value and a down arrow.

    • Variable – No variable dropdown list is displayed on the dashboard.

Entering options

To enter options for an ad hoc filter

  1. In the Data source list, select the target data source. For more information about data sources, see Connect to data sources.

  2. Choose Add to add the variable to the dashboard.

Creating ad hoc filters

Ad hoc filters are one of the most complex and flexible variable options available. Instead of a regular list of variable options, this variable enables the construction of a dashboard-wide ad hoc query. Filters that you apply in this manner are applied to all panels on the dashboard.

Chained variables

Chained variables, also called linked variables or nested variables, are query variables with one or more other variables in their variable query. This section explains how chained variables work, and it provides links to example dashboards that use chained variables.

Chained variable queries are different for each data source, but the premise is the same for all. You can use chained variable queries in any data source that supports them.

You can build complex linked, templated dashboards, 5 or 10 levels deep. Technically, there is no limit to how deep or complex you can go, but the more links you have, the greater the query load.

Best practices and tips

The following practices will make your dashboards and variables easier to use.

Creating new chained variables

  • Chaining variables creates parent-child dependencies. You can envision them as a ladder or a tree.

  • The quickest way to create a new chained variable is to copy the variable that you want to base the new one on. In the variable list, choose the Duplicate variable icon to the right of the variable entry to create a copy. You can then add on to the query for the parent variable.

  • New chained variables that you create this way appear at the bottom of the list. To give the list a logical order, drag the variable to a different position in the list.

Variable order

To change the order of variables in the dashboard variable list, choose the up and down arrows on the right side of each entry. The Grafana workspace lists variable dropdown lists left to right according to this list, displaying the variable at the top of the list on the far left.

  • List variables that do not have dependencies at the top, before their child variables.

  • Each variable should follow the one that it is dependent on.

  • The UI doesn't indicate which variables have dependency relationships. List the variables in a logical order to make it clearer to end users (and yourself).

Complexity consideration

The more layers of dependency you have in variables, the longer it takes to update dashboards after you change variables.

For example, if you have a series of four linked variables (country, region, server, metric) and you change a root variable value (country), the Grafana workspace must run queries for all the dependent variables before it updates the visualizations in the dashboard.

Global variables

Grafana has global built-in variables that can be used in expressions in the query editor. This topic lists them in alphabetical order and defines them. These variables are useful in queries, dashboard links, panel links, and data links.

$__dashboard

This variable is the name of the current dashboard.

$__from and $__to

Grafana has two built in time range variables: $__from and $__to. They are currently always interpolated as epoch milliseconds by default but you can control date formatting.

Syntax Example result Description
${__from} 1594671549254 Unix millisecond epoch
${__from:date} 2020-07-13T20:19:09.254Z No args, defaults to ISO 8601/RFC 3339
${__from:date:iso} 2020-07-13T20:19:09.254Z ISO 8601/RFC 3339
${__from:date:seconds} 1594671549 Unix seconds epoch
${__from:date:YYYY-MM} 2020-07 Any custom data format. For more information, see Display.

The above syntax works with ${__to} as well.

You can use this variable in URLs as well. For example, to send an end user to a dashboard that shows a time range from six hours ago until now, use the following URL: https://play.grafana.org/d/000000012/grafana-play-home?viewPanel=2&orgId=1?from=now-6h&to=now

$__interval

You can use the $__interval variable as a parameter to group by time (for InfluxDB, Myself, Postgres, MSSQL), Date histogram interval (for OpenSearch), or as a summarize function parameter (for Graphite).

The Grafana workspace automatically calculates an interval that can be used to group by time in queries. When there are more data points than can be shown on a graph, queries can be made more efficient by grouping by a larger interval. For example, it is more efficient to group by 1 day than by 10s when looking at 3 months of data. The graph will look the same, and the query will be faster. The $__interval is calculated by using the time range and the width of the graph (the number of pixels).

Approximate Calculation: (from - to) / resolution

For example, when the time range is 1 hour and the graph is full screen, the interval might be calculated to 2m; points are grouped in 2-minute intervals. If the time range is 6 months and the graph is full screen, the interval might be 1d (1 day); points are grouped by day.

In the InfluxDB data source, the legacy variable $interval is the same variable. Use $__interval instead.

The InfluxDB and OpenSearch data sources have Group by time interval fields that are used to hardcode the interval or to set the minimum limit for the $__interval variable by using the > syntax -> >10m.

$__interval_ms

This variable is the $__interval variable in milliseconds, not a time interval formatted string. For example, if the $__interval is 20m then the $__interval_ms is 1200000.

$__name

This variable is only available in the Singlestat panel and can be used in the prefix or suffix fields on the Options tab. The variable will be replaced with the series name or alias.

$__org

This variable is the ID of the current organization. The variable ${__org.name} is the name of the current organization.

$__user

The variable ${__user.id} is the ID of the current user. The variable ${__user.login} is the login handle of the current user. The variable ${__user.email} is the email for the current user.

$__range

This variable is currently supported only for Prometheus data sources. This variable represents the range for the current dashboard. It is calculated by to - from. It has millisecond and second representations called $__range_ms and $__range_s.

$timeFilter or $__timeFilter

The $timeFilter variable returns the currently selected time range as an expression. For example, the time range interval Last 7 days expression is time > now() - 7d.

This variable is used in several places, including:

  • The WHERE clause for the InfluxDB data source. Grafana adds it automatically to InfluxDB queries when in Query Editor mode. You can add it manually in Text Editor mode: WHERE $timeFilter.

  • Log Analytics queries in the Azure Monitor data source.

  • SQL queries in MySQL, Postgres, and MSSQL.

  • The $__timeFilter variable is used in the MySQL data source.