# Templates and variables **** 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). A variable is a placeholder for a value. You can use variables in metric queries and in panel titles. Variables give you the ability to create more interactive and dynamic dashboards. Instead of hardcoding things like server, application, and sensor names in your metric queries, you can use variables in their place. Variables are displayed as dropdown lists at the top of the dashboard. When you change the value by using the dropdown list at the top of the dashboard, your panel’s metric queries reflect the new value. These can be especially useful for administrators who want to allow viewers to adjust visualizations quickly but do not want to give them full editing permissions. Grafana viewers can use variables. By using variables and templates, you can single-source dashboards. If you have multiple identical data sources or servers, you can make one dashboard and use variables to change what you are viewing. This simplifies maintenance and upkeep. For a list of supported variable types, and instructions for adding each type of variable, see [Variable types](variables-types.md) ## Templates A *template* is any query that contains a variable. For example, if you were administering a dashboard to monitor several servers, you could make a dashboard for each server. Or you could create one dashboard and use panels with template queries, as shown in the following example. ``` wmi_system_threads{instance=~"$server"} ``` Variable values are always synced to the URL by using the syntax `var-=value`. ## Variable best practices Variable dropdown lists are displayed in the order they are listed in the variable list in **Dashboard settings**. Put the variables that you will change often at the top, so that they will be shown first, at the far left on the dashboard. ## Variable syntax Panel titles and metric queries can see variables by using two different syntaxes: + `$varname` This syntax is easier to read, as in the following example: `apps.frontend.$server.requests.count`. However, you cannot use a variable in the middle of a word. + `${var_name}` Use this syntax when you want to interpolate a variable in the middle of an expression. + `${var_name:}` This format gives you more control over how Grafana interpolates values. For more information, see [Advanced variable format options](#advanced-variable-format-options). Before queries are sent to your data source, the query is *interpolated*, meaning that the variable is replaced with its current value. During interpolation, the variable value might be *escaped* to conform to the syntax of the query language and where it is used. For example, a variable that is used in a regex expression in a Prometheus query will be regex-escaped. Read the data source–specific documentation topic for details on value escaping during interpolation. For information about advanced syntax to override data source default formatting, see [Advanced variable format options](#advanced-variable-format-options). # 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. ## Other variable options This section explains the other variable options that are available. ### Entering variable selection options You can use **Selection Options** to manage variable option selections. All selection options are optional, and they are off by default. #### Multi-value If you turn this option on, the variable dropdown list supports the selection of multiple options at the same time. For more information, see [Formatting multi-value variables](#formatting-multi-value-variables). #### Include All option The Grafana workspace adds an `All` option to the variable dropdown list. If an end user selects this option, all variable options are selected. #### Custom all value This option is visible only if the **Include All option** is selected. To define the value of the `All` option, enter regex, glob, or Lucene syntax in the **Custom all value** field. By default, the `All` value includes all options in combined expression. This can become very long and can have performance problems. Sometimes it can be better to specify a custom all value, like a wild card regex. When you use custom regex, glob, or Lucene syntax in the **Custom all value** option, it is never escaped, so you must consider what is a valid value for your data source. ### Advanced variable format options The formatting of the variable interpolation depends on the data source, but there are some situations where you might want to change the default formatting. For example, the default for the MySQL data source is to join multiple values as comma-separated with quotes: `'server01','server02'`. In some cases, you might want to have a comma-separated string without quotes: `server01,server02`. To do this, use the following advanced variable formatting options. #### General syntax Syntax: `${var_name:option}` If any invalid formatting option is specified, `glob` is the default, or fallback, option. #### CSV Formats variables with multiple values as a comma-separated string. ``` servers = ['test1', 'test2'] String to interpolate: '${servers:csv}' Interpolation result: 'test1,test2' ``` #### Distributed - OpenTSDB Formats variables with multiple values in custom format for OpenTSDB. ``` servers = ['test1', 'test2'] String to interpolate: '${servers:distributed}' Interpolation result: 'test1,servers=test2' ``` #### Doublequote Formats single-value and multi-value variables into a comma-separated string, escapes `"` in each value by `\"`, and quotes each value with `"`. ``` servers = ['test1', 'test2'] String to interpolate: '${servers:doublequote}' Interpolation result: '"test1","test2"' ``` #### Glob - Graphite Formats variables with multiple values into a glob (for Graphite queries). ``` servers = ['test1', 'test2'] String to interpolate: '${servers:glob}' Interpolation result: '{test1,test2}' ``` #### JSON Formats variables with multiple values as a comma-separated string. ``` servers = ['test1', 'test2'] String to interpolate: '${servers:json}' Interpolation result: '["test1", "test2"]' ``` #### Lucene - OpenSearch Formats variables with multiple values in Lucene format for OpenSearch. ``` servers = ['test1', 'test2'] String to interpolate: '${servers:lucene}' Interpolation result: '("test1" OR "test2")' ``` #### Percentencode Formats single-value and multi-value variables for use in URL parameters. ``` servers = ['foo()bar BAZ', 'test2'] String to interpolate: '${servers:percentencode}' Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2' ``` #### Pipe Formats variables with multiple values into a pipe-separated string. ``` servers = ['test1.', 'test2'] String to interpolate: '${servers:pipe}' Interpolation result: 'test1.|test2' ``` #### Raw Turns off data source–specific formatting, such as single quotes in an SQL query. ``` servers = ['test1.', 'test2'] String to interpolate: '${var_name:raw}' Interpolation result: '{test.1,test2}' ``` #### Regex Formats variables with multiple values into a regex string. ``` servers = ['test1.', 'test2'] String to interpolate: '${servers:regex}' Interpolation result: '(test1\.|test2)' ``` #### Singlequote Formats single- and multi-value variables into a comma-separated string, escapes `'` in each value by `\'` and quotes each value with `'`. ``` servers = ['test1', 'test2'] String to interpolate: '${servers:singlequote}' Interpolation result: "'test1','test2'" ``` #### Sqlstring Formats single- and multi-value variables into a comma-separated string, escapes `'` in each value by `''` and quotes each value with `'`. ``` servers = ["test'1", "test2"] String to interpolate: '${servers:sqlstring}' Interpolation result: "'test''1','test2'" ``` #### Text Formats single-value and multi-value variables into their text representation. For a single variable, it will just return the text representation. For multi-value variables, it will return the text representation combined with `+`. ``` servers = ["test1", "test2"] String to interpolate: '${servers:text}' Interpolation result: "test1 + test2" ``` ### Formatting multi-value variables Interpolating a variable with multiple values selected is tricky as it is not straight forward how to format the multiple values into a string that is valid in the given context where the variable is used. Grafana tries to solve this by enabling each data source plugin to inform the templating interpolation engine what format to use for multiple values. **Note** The **Custom all value** option on the variable must be blank for Grafana to format all values into a single string. If leave it blank, then the Grafana concatenates (adds together) all the values in the query. Something like `value1,value2,value3`. If a custom `all` value is used, then instead the value will be something like `*` or `all`. #### Multi-value variables with a Graphite data source Graphite uses glob expressions. A variable with multiple values would, in this case, be interpolated as `{host1,host2,host3}` if the current variable value was *host1*, *host2*, and *host3*. #### Multi-value variables with a Prometheus or InfluxDB data source InfluxDB and Prometheus use regex expressions, so the same variable would be interpolated as `(host1|host2|host3)`. Every value would also be regex escaped. If not, a value with a regex control character would break the regex expression. #### Multi-value variables with an Elastic data source Amazon OpenSearch uses Lucene query syntax, so the same variable would be formatted as `("host1" OR "host2" OR "host3")`. In this case, every value must be escaped so that the value contains only Lucene control words and quotation marks. #### Troubleshooting formatting Automatic escaping and formatting can cause problems. It can be tricky to grasp the logic behind a problem, especially for InfluxDB and Prometheus, where the use of regex syntax requires that the variable is used in regex operator context. If you do not want Grafana to do this automatic regex escaping and formatting, you must do one of the following: + Turn off the **Multi-value** **Include All option** options. + Use the [raw variable format](\$1\$1< relref "advanced-variable-format-options.md\$1raw" >\$1\$1). ### Filtering variables with regex Using the Regex Query option, you can filter the list of options returned by the variable query or modify the options returned. This section shows how to use regex to filter and modify values in the variable dropdown list. Using the Regex Query option, you filter the list of options returned by the Variable query or modify the options returned. For more information, see [ Regular expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions). Examples of filtering on the following list of options: ``` backend_01 backend_02 backend_03 backend_04 ``` #### Filtering so that only the options that end with `01` or `02` are returned Regex: ``` /.*[01|02]/ ``` Result: ``` backend_01 backend_02 ``` #### Filtering and modifying the options using a regex capture group to return part of the text Regex: ``` /.*(01|02)/ ``` Result: ``` 01 02 ``` #### Filtering and modifying - Prometheus Example List of options: ``` up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000 up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000 up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000 ``` Regex: ``` /.*instance="([^"]*).*/ ``` Result: ``` demo.robustperception.io:9090 demo.robustperception.io:9093 demo.robustperception.io:9100 ``` #### Filtering and modifying using named text and value capture groups Using named capture groups, you can capture separate "text" and "value" parts from the options returned by the variable query. The variable dropdown list can contain a friendly name for each value that can be selected. For example, when querying the `node_hwmon_chip_names` Prometheus metric, the `chip_name` is friendlier than the `chip` value. Start with the following variable query result. ``` node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1 ``` Pass it through the following Regex. ``` /chip_name="(?[^"]+)|chip="(?[^"]+)/g ``` The following dropdown list is produced. ``` Display Name Value ------------ ------------------------- enp216s0f0np0 0000:d7:00_0_0000:d8:00_0 enp216s0f0np1 0000:d7:00_0_0000:d8:00_1 enp216s0f0np2 0000:d7:00_0_0000:d8:00_2 enp216s0f0np3 0000:d7:00_0_0000:d8:00_3 ``` **Note:** Only `text` and `value` capture group names are supported. ### Repeating panels or rows You can create dynamic dashboards using *template variables*. All variables in your queries expand to the current value of the variable before the query is sent to the database. With variables, you can reuse a single dashboard for all your services. Template variables can be very useful for dynamically changing your queries across a whole dashboard. If you want Grafana to dynamically create new panels or rows based on the values that you have selected, you can use the *Repeat* feature. #### Repeating panels If you have a variable with `Multi-value` or `Include all value` options turned on, you can choose one panel and have Grafana repeat that panel for every selected value. You can find the *Repeat* feature under the *General tab* in panel edit mode. The `direction` controls how the panels are arranged. If you choose `horizontal`, the panels are arranged side-by-side. Grafana automatically adjusts the width of each repeated panel so that the whole row is filled. Currently, you cannot mix other panels on a row with a repeated panel. Set `Max per row` to tell Grafana how many panels per row you want at most. It defaults to *4*. If you choose `vertical`, the panels are arranged from top to bottom in a column. The width of the repeated panels is the same as of the first panel (the original template) that is being repeated. Make changes only to the first panel (the original template). For the changes take effect on all panels, you need to start a dynamic dashboard re-build. You can do this by either changing the variable value (that is, the basis for the repeat) or reloading the dashboard. **Note** Repeating panels require variables to have one or more items selected. You cannot repeat a panel zero times to hide it. #### Repeating rows As seen above with the panels you can also repeat rows if you have variables set with `Multi-value` or `Include all value` selection option. To turn on this feature, you must first add a new *Row* by using the *Add Panel* menu. Then pause on the row title and choose the cog button to access the `Row Options` configuration panel. You can then select the variable you want to repeat the row for. A best practice is to use a variable in the row title as well.