# Variable types
****
This documentation topic is designed for Grafana workspaces that support **Grafana version 8.x**.
For Grafana workspaces that support Grafana version 12.x, see [Working in Grafana version 12](using-grafana-v12.md).
For Grafana workspaces that support Grafana version 10.x, see [Working in Grafana version 10](using-grafana-v10.md).
For Grafana workspaces that support Grafana version 9.x, see [Working in Grafana version 9](using-grafana-v9.md).
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](#add-a-query-variable). |
| Custom | Define the variable options manually using a comma-separated list. For more information, see [Adding a custom variable](#add-a-custom-variable). |
| Text box | Display a text input field with an optional default value. For more information, see [Adding a text box variable](#add-a-text-box-variable). |
| Constant | Define a hidden constant. For more information, see [Adding a constant variable](#add-a-constant-variable). |
| Data source | Quickly change the data source for an entire dashboard. For more information, see [Adding a data source variable](#add-a-data-source-variable). |
| Interval | Interval variables represent time spans. For more information, see [Adding an interval variable](#add-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](#add-ad-hoc-filters). |
| Global variables | Built-in variables that can be used in expressions in the query editor. For more information, see [Global variables](#global-variables). |
| Chained variables | Variable queries can contain other variables. For more information, see [Chained variables](#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](AMG-data-sources.md).
### 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.
1. On the **Variables** tab, choose **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Query**.
1. (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.
1. 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](AMG-data-sources.md).
1. 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.
1. 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.
1. (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](templates-and-variables.md#filter-variables-with-regex).
1. 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.
1. (Optional) Enter **Selection Options**. For more information, see [Entering variable selection options](templates-and-variables.md#enter-variable-selection-options).
1. In **Preview of values**, the Grafana workspace displays a list of the current variable values. Review them to ensure they match what you expect.
1. 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](#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.
1. On the **Variables** tab, choose **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, choose **Custom**.
1. (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.
1. 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.
1. (Optional) Enter **Selection Options**. For more information, see [Entering variable selection options](templates-and-variables.md#enter-variable-selection-options).
1. In **Preview of values**, the Grafana workspace displays a list of the current variable values. Review them to ensure they match what you expect.
1. 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.
1. On the **Variables** tab, choose **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Text box**.
1. (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.
1. 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.
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. 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.
1. On the **Variables** tab, choose **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Constant**.
1. (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.
1. 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](templates-and-variables.md#advanced-variable-format-options).
1. In **Preview of values**, the Grafana workspace displays the current variable value. Review it to ensure it matches what you expect.
1. 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.
1. On the **Variables** tab, choose **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Datasource**.
1. (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.
1. 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](AMG-data-sources.md).
1. (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.
1. (Optional) Enter **Selection Options**. For more information, see [Entering variable selection options](templates-and-variables.md#enter-variable-selection-options).
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. 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.
1. On the **Variables** tab, choose **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Interval**.
1. (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.
1. 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`.
1. (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.
1. In **Preview of values**, Grafana displays a list of the current variable values. Review them to ensure they match what you expect.
1. 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.
1. On the **Variables** tab, choose **New**.
1. Enter a **Name** for your variable.
1. In the **Type** list, select **Ad hoc filters**.
1. (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.
1. 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](AMG-data-sources.md).
1. 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.
### \$1\$1\$1dashboard
This variable is the name of the current dashboard.
### \$1\$1\$1from and \$1\$1\$1to
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 |
| --- | --- | --- |
| \$1\$1\$1\$1from\$1 | 1594671549254 | Unix millisecond epoch |
| \$1\$1\$1\$1from:date\$1 | 2020-07-13T20:19:09.254Z | No args, defaults to ISO 8601/RFC 3339 |
| \$1\$1\$1\$1from:date:iso\$1 | 2020-07-13T20:19:09.254Z | ISO 8601/RFC 3339 |
| \$1\$1\$1\$1from:date:seconds\$1 | 1594671549 | Unix seconds epoch |
| \$1\$1\$1\$1from:date:YYYY-MM\$1 | 2020-07 | Any custom data format. For more information, see [ Display](https://momentjs.com/docs/#/displaying/). |
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
### \$1\$1\$1interval
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`.
### \$1\$1\$1interval\$1ms
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`.
### \$1\$1\$1name
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.
### \$1\$1\$1org
This variable is the ID of the current organization. The variable `${__org.name}` is the name of the current organization.
### \$1\$1\$1user
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.
### \$1\$1\$1range
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`.
### \$1timeFilter or \$1\$1\$1timeFilter
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.