From 179a9f7f028f4d0947d5c5f0ed2bb4012cac5ba0 Mon Sep 17 00:00:00 2001 From: Larissa Wandzura Date: Mon, 12 Jan 2026 11:35:41 -0600 Subject: [PATCH] created a separate template variables doc --- docs/sources/datasources/mysql/_index.md | 6 + .../datasources/mysql/configure/_index.md | 14 +- .../datasources/mysql/query-editor/_index.md | 104 ++----------- .../mysql/template-variables/index.md | 146 ++++++++++++++++++ 4 files changed, 173 insertions(+), 97 deletions(-) create mode 100644 docs/sources/datasources/mysql/template-variables/index.md diff --git a/docs/sources/datasources/mysql/_index.md b/docs/sources/datasources/mysql/_index.md index 023ccbd1f22..59f6d48df33 100644 --- a/docs/sources/datasources/mysql/_index.md +++ b/docs/sources/datasources/mysql/_index.md @@ -37,6 +37,11 @@ refs: destination: /docs/grafana//datasources/mysql/troubleshooting/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana//datasources/mysql/troubleshooting/ + mysql-template-variables: + - pattern: /docs/grafana/ + destination: /docs/grafana//datasources/mysql/template-variables/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana//datasources/mysql/template-variables/ alerting: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/ @@ -61,6 +66,7 @@ The following documents will help you get started with the MySQL data source in - [Configure the MySQL data source](ref:configure-mysql-data-source) - [MySQL query editor](ref:mysql-query-editor) +- [MySQL template variables](ref:mysql-template-variables) - [Troubleshoot MySQL data source issues](ref:troubleshoot-mysql) Once you have configured the data source you can: diff --git a/docs/sources/datasources/mysql/configure/_index.md b/docs/sources/datasources/mysql/configure/_index.md index 085c9eb2bcc..e0156daf899 100644 --- a/docs/sources/datasources/mysql/configure/_index.md +++ b/docs/sources/datasources/mysql/configure/_index.md @@ -56,6 +56,11 @@ refs: destination: /docs/grafana//datasources/mysql/troubleshooting/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana//datasources/mysql/troubleshooting/ + mysql-template-variables: + - pattern: /docs/grafana/ + destination: /docs/grafana//datasources/mysql/template-variables/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana//datasources/mysql/template-variables/ --- # Configure the MySQL data source @@ -284,7 +289,8 @@ For all available configuration options, refer to the [Grafana provider data sou After configuring your MySQL data source, you can: -- [Write queries](ref:mysql-query-editor) using the query editor to explore and visualize your data -- [Add annotations](ref:annotate-visualizations) to overlay MySQL events on your graphs -- [Set up alerting](ref:alerting) to create alert rules based on your MySQL data -- [Troubleshoot issues](ref:mysql-troubleshoot) if you encounter problems with your data source +- [Write queries](ref:mysql-query-editor) using the query editor to explore and visualize your data. +- [Use template variables](ref:mysql-template-variables) to create dynamic, reusable dashboards. +- [Add annotations](ref:annotate-visualizations) to overlay MySQL events on your graphs. +- [Set up alerting](ref:alerting) to create alert rules based on your MySQL data. +- [Troubleshoot issues](ref:mysql-troubleshoot) if you encounter problems with your data source. diff --git a/docs/sources/datasources/mysql/query-editor/_index.md b/docs/sources/datasources/mysql/query-editor/_index.md index 5139a04d2f3..1cb0e99bc85 100644 --- a/docs/sources/datasources/mysql/query-editor/_index.md +++ b/docs/sources/datasources/mysql/query-editor/_index.md @@ -61,6 +61,11 @@ refs: configure-standard-options: - pattern: /docs/grafana/ - destination: /docs/grafana//panels-visualizations/configure-standard-options/ + mysql-template-variables: + - pattern: /docs/grafana/ + destination: /docs/grafana//datasources/mysql/template-variables/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana//datasources/mysql/template-variables/ --- # MySQL query editor @@ -305,105 +310,17 @@ Table panel result: The query returns multiple columns representing minimum and maximum values within the defined range. -## Templating +## Template variables -Instead of hardcoding values like server, application, or sensor names in your metric queries, you can use variables. Variables appear as drop-down select boxes at the top of the dashboard. These drop-downs make it easy to change the data being displayed in your dashboard. +Instead of hard-coding values like server, application, or sensor names in your metric queries, you can use variables. Variables appear as drop-down select boxes at the top of the dashboard, making it easy to change the data displayed in your dashboard. -Refer to [Templates](ref:variables) for an introduction to creating template variables as well as the different types. - -### Query variable - -If you add a `Query` template variable you can write a MySQL query to retrieve items such as measurement names, key names, or key values, which will be displayed in the drop-down menu. - -For example, you can use a variable to retrieve all the values from the `hostname` column in a table by creating the following query in the templating variable _Query_ setting. - -```sql -SELECT hostname FROM my_host -``` - -A query can return multiple columns, and Grafana will automatically generate a list based on the query results. For example, the following query returns a list with values from `hostname` and `hostname2`. - -```sql -SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city -``` - -To use time range dependent macros like `$__timeFilter(column)` in your query,you must set the template variable's refresh mode to _On Time Range Change_. - -```sql -SELECT event_name FROM event_log WHERE $__timeFilter(time_column) -``` - -Another option is a query that can create a key/value variable. The query should return two columns that are named `__text` and `__value`. The `__text` column must contain unique values (if not, only the first value is used). This allows the drop-down options to display a text-friendly name as the text while using an ID as the value. For example, a query could use `hostname` as the text and `id` as the value: - -```sql -SELECT hostname AS __text, id AS __value FROM my_host -``` - -You can also create nested variables. For example, if you have a variable named `region`, you can configure the `hosts` variable to display only the hosts within the currently selected region as shown in the following example. If `region` is a multi-value variable, use the `IN` operator instead of `=` to match multiple values. - -```sql -SELECT hostname FROM my_host WHERE region IN($region) -``` - -#### Use `__searchFilter` to filter results in a query variable - -Using `__searchFilter` in the query field allows the query results to be filtered based on the user’s input in the drop-down selection box. If you do not enter anything, the default value for `__searchFilter` is % - -Note that you must enclose the `__searchFilter` expression in quotes as Grafana does not add them automatically. - -The following example demonstrates how to use `__searchFilter` in the query field to enable real-time searching for `hostname` as the user type in the drop-down selection box. - -```sql -SELECT hostname FROM my_host WHERE hostname LIKE '$__searchFilter' -``` - -### Using variables in queries - -Template variable values are only quoted when the template variable is a `multi-value`. - -If the variable is a multi-value variable, use the `IN` comparison operator instead of `=` to match against multiple values. - -You can use two different syntaxes: - -`$` Example with a template variable named `hostname`: - -```sql -SELECT - UNIX_TIMESTAMP(atimestamp) as time, - aint as value, - avarchar as metric -FROM my_table -WHERE $__timeFilter(atimestamp) and hostname in($hostname) -ORDER BY atimestamp ASC -``` - -`[[varname]]` Example with a template variable named `hostname`: - -```sql -SELECT - UNIX_TIMESTAMP(atimestamp) as time, - aint as value, - avarchar as metric -FROM my_table -WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) -ORDER BY atimestamp ASC -``` - -#### Disabling quoting for multi-value variables - -Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if `server01` and `server02` are selected then it will be formatted as: `'server01', 'server02'`. To disable quoting, use the csv formatting option for variables: - -Grafana automatically formats multi-value variables as a quoted, comma-separated string. For example, if `server01` and `server02` are selected, they are formatted as `'server01'`, `'server02'`. To remove the quotes, enable the CSV formatting option for the variables. - -`${servers:csv}` - -Read more about variable formatting options in the [Variables](ref:variable-syntax-advanced-variable-format-options) documentation. +For detailed information on using template variables with MySQL, refer to [MySQL template variables](ref:mysql-template-variables). ## Annotations [Annotations](ref:annotate-visualizations) allow you to overlay rich event information on top of graphs. You add annotation queries via the **Dashboard settings > Annotations view**. -**Example query using a`time` column with epoch values:** +**Example query using a `time` column with epoch values:** ```sql SELECT @@ -416,7 +333,7 @@ WHERE $__unixEpochFilter(epoch_time) ``` -You may use one or more tags to show them as annotations in a common-separate string. +You may use one or more tags to show them as annotations in a common-separated string. **Example query using a `time` column with epoch values for a single tag:** @@ -473,3 +390,4 @@ For more information regarding alerting refer to the following: - [Alert rules](ref:alert-rules) - [Template annotations and labels](ref:template-annotations-and-labels) + diff --git a/docs/sources/datasources/mysql/template-variables/index.md b/docs/sources/datasources/mysql/template-variables/index.md new file mode 100644 index 00000000000..c576e8fab8a --- /dev/null +++ b/docs/sources/datasources/mysql/template-variables/index.md @@ -0,0 +1,146 @@ +--- +description: Using template variables with MySQL in Grafana +keywords: + - grafana + - mysql + - templates + - variables + - queries +labels: + products: + - cloud + - enterprise + - oss +menuTitle: Template variables +title: MySQL template variables +weight: 300 +refs: + variables: + - pattern: /docs/grafana/ + destination: /docs/grafana//dashboards/variables/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana//dashboards/variables/ + variable-syntax-advanced-variable-format-options: + - pattern: /docs/grafana/ + destination: /docs/grafana//dashboards/variables/variable-syntax/#advanced-variable-format-options + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana//dashboards/variables/variable-syntax/#advanced-variable-format-options + add-template-variables: + - pattern: /docs/grafana/ + destination: /docs/grafana//dashboards/variables/add-template-variables/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana//dashboards/variables/add-template-variables/ +--- + +# MySQL template variables + +Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. +Grafana displays these variables in drop-down select boxes at the top of the dashboard to help you change the data displayed in your dashboard. +Grafana refers to such variables as **template variables**. + +For an introduction to templating and template variables, refer to [Templating](ref:variables) and [Add and manage variables](ref:add-template-variables). + +## Query variable + +A query variable in Grafana dynamically retrieves values from your data source using a query. With a query variable, you can write a SQL query that returns values such as measurement names, key names, or key values that are shown in a drop-down select box. + +For example, the following query returns all values from the `hostname` column: + +```sql +SELECT hostname FROM my_host +``` + +A query can return multiple columns, and Grafana automatically generates a list using the values from those columns. For example, the following query returns values from both the `hostname` and `hostname2` columns, which are included in the variable's drop-down list. + +```sql +SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city +``` + +To use time range dependent macros like `$__timeFilter(column)` in your query, you must set the template variable's refresh mode to **On Time Range Change**. + +```sql +SELECT event_name FROM event_log WHERE $__timeFilter(time_column) +``` + +### Key/value variables + +You can create a key/value variable using a query that returns two columns named `__text` and `__value`. + +- The `__text` column defines the label shown in the drop-down. +- The `__value` column defines the value passed to panel queries. + +This is useful when you want to display a user-friendly label (like a hostname) but use a different underlying value (like an ID). + +Note that the values in the `__text` column should be unique. If there are duplicates, Grafana uses only the first matching entry. + +```sql +SELECT hostname AS __text, id AS __value FROM my_host +``` + +### Nested variables + +You can create nested variables, where one variable depends on the value of another. For example, if you have a variable named `region`, you can configure a `hosts` variable to only show hosts from the selected region. If `region` is a multi-value variable, use the `IN` operator instead of `=` to match against multiple selected values. + +```sql +SELECT hostname FROM my_host WHERE region IN($region) +``` + +### Filter results with `__searchFilter` + +Using `__searchFilter` in the query field allows the query results to be filtered based on the user's input in the drop-down selection box. If you don't enter anything, the default value for `__searchFilter` is `%`. + +Note that you must enclose the `__searchFilter` expression in quotes as Grafana doesn't add them automatically. + +The following example demonstrates how to use `__searchFilter` in the query field to enable real-time searching for `hostname` as the user types in the drop-down selection box. + +```sql +SELECT hostname FROM my_host WHERE hostname LIKE '$__searchFilter' +``` + +## Use variables in queries + +Grafana automatically quotes template variable values only when the template variable is a `multi-value`. + +When using a multi-value variable, use the `IN` comparison operator instead of `=` to match against multiple values. + +Grafana supports two syntaxes for using variables in queries: + +- **`$` syntax** + +Example with a template variable named `hostname`: + +```sql +SELECT + UNIX_TIMESTAMP(atimestamp) as time, + aint as value, + avarchar as metric +FROM my_table +WHERE $__timeFilter(atimestamp) and hostname in($hostname) +ORDER BY atimestamp ASC +``` + +- **`[[varname]]` syntax** + +Example with a template variable named `hostname`: + +```sql +SELECT + UNIX_TIMESTAMP(atimestamp) as time, + aint as value, + avarchar as metric +FROM my_table +WHERE $__timeFilter(atimestamp) and hostname in([[hostname]]) +ORDER BY atimestamp ASC +``` + +### Disable quoting for multi-value variables + +By default, Grafana formats multi-value variables as a quoted, comma-separated string. For example, if `server01` and `server02` are selected, the result will be `'server01'`, `'server02'`. To disable quoting, use the `csv` formatting option for variables: + +```text +${servers:csv} +``` + +This outputs the values as an unquoted comma-separated list. + +Refer to [Advanced variable format options](ref:variable-syntax-advanced-variable-format-options) for additional information.