Documentation Plugins Yugabyte Template variables

Yugabyte template variables

Use template variables to create dynamic, reusable dashboards that let you change query parameters without editing individual panels. For general information about template variables, refer to Templates and variables.

Before you begin

• Configure the Yugabyte data source.
• Understand Grafana template variables.

Supported variable types

The Yugabyte data source supports the following variable types:

Create a query variable

The variable query editor is a raw SQL editor with syntax highlighting and autocomplete. It’s the same editor as the query editor’s Code mode and doesn’t include the visual builder.

To create a query variable:

1. Navigate to Dashboard settings > Variables.
2. Click Add variable.
3. Select Query as the variable type.
4. Select the Yugabyte data source.
5. Enter a SQL query that returns the values you want to use.
6. Grafana shows a preview of the returned values below the query editor.

Query return format

Grafana determines variable values from the columns your query returns:

Grafana matches the text and value columns by name, and both must be string columns. Cast numeric columns to text with ::text, for example id::text AS value.

Single-column example

This query returns a list of distinct regions for use as variable values:

SQL Copy

SELECT DISTINCT region FROM sales ORDER BY region

Text and value example

This query displays a human-readable name while substituting an ID into queries:

SQL Copy

SELECT name AS text, id::text AS value FROM customers ORDER BY name

The variable drop-down displays name values, but the selected id is substituted into queries. The id column is cast to text with ::text so Grafana recognizes it as the value column.

Use variables in queries

Reference template variables in your SQL queries using the $variable or ${variable} syntax. Grafana substitutes single-value string variables as-is, so include quotes around string values in your query:

SQL Copy

SELECT created_at AS time, count(*) AS orders
FROM orders
WHERE region = '$region' AND $__timeFilter(created_at)
GROUP BY time
ORDER BY time

For numeric values, omit the quotes:

SQL Copy

SELECT * FROM orders WHERE total > $threshold

Chained variables

You can build chained, or dependent, variables where one variable’s query filters on the value selected in another variable. Because variable queries also expand template variables, you can reference another variable inside a query variable’s SQL.

For example, if you have a region variable, create a dependent city variable that only lists cities in the selected region:

SQL Copy

SELECT DISTINCT city FROM stores WHERE region = '$region' ORDER BY city

When you change the region selection, Grafana re-runs the city query and updates its available values.

Multi-value variables

When a variable allows multiple selections, the Yugabyte data source formats the values as a comma-separated, single-quoted list. For example, if you select pending, shipped, and delivered, the variable expands to 'pending','shipped','delivered'.

Use multi-value variables with the IN operator, and don’t add quotes around the variable:

SQL Copy

SELECT * FROM orders WHERE status IN ($status)

If you select pending and shipped, this expands to:

SQL Copy

SELECT * FROM orders WHERE status IN ('pending','shipped')

Because the values are always single-quoted, this format is intended for string columns. For numeric columns, use string comparisons or cast the column as needed.

Next steps

• Learn how to write queries in the Yugabyte query editor.
• Set up alerting on your YugabyteDB data.