This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentation Grafana documentation Data sources Microsoft SQL Server Template variables

Microsoft SQL Server 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 general information on using variables in Grafana, refer to Add variables.

For an introduction to templating and template variables, refer to Templating and Add and manage 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 Copy

SELECT hostname FROM 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 Copy

SELECT [host].[hostname], [other_host].[hostname2] FROM host JOIN other_host ON [host].[city] = [other_host].[city]

You can also 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 Copy

SELECT hostname __text, id __value FROM host

You can also 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 Copy

SELECT hostname FROM host WHERE region IN ($region)

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:

• $<varname> syntax

Example with a template variable named hostname:

SQL Copy

SELECT
  atimestamp time,
  aint value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp

• [[varname]] syntax

Example with a template variable named hostname:

SQL Copy

SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp

Format variables for SQL queries

When using template variables inside SQL queries, the formatting option you choose determines how Grafana renders the variable value. Choosing the correct format prevents SQL injection risks and avoids broken queries from incorrect quoting.

Use sqlstring for safe single-value interpolation

The ${var:sqlstring} format wraps the variable value in single quotes and escapes any internal single quotes. This is the recommended approach for single-value variables used in WHERE clauses:

SQL Copy

SELECT * FROM events
WHERE hostname = ${hostname:sqlstring}

If hostname is set to server01, this expands to:

SQL Copy

SELECT * FROM events
WHERE hostname = 'server01'

Multi-value variable formatting

When a variable allows multiple selections, Grafana provides several formatting options:

For multi-value variables in SQL WHERE clauses, the default formatting with IN is typically correct:

SQL Copy

SELECT * FROM events
WHERE hostname IN ($hostname)

If hostname has values server01 and server02 selected, this expands to:

SQL Copy

SELECT * FROM events
WHERE hostname IN ('server01','server02')

Disable quoting for multi-value variables

To output multi-value variables without automatic quoting, use the csv format:

text Copy

${servers:csv}

This outputs the values as an unquoted comma-separated list. Use this only when you handle quoting yourself or when the values are numeric.

Refer to Advanced variable format options for the full list of formatting options.