Dashboard Variables

Variables enable you to create interactive, dynamic dashboards that can be filtered and customized without editing. They allow users to change data sources, filter data, and modify queries through dropdown selectors.

What are Variables?

Variables are placeholders that can be used in:

Panel queries
Panel titles and descriptions
Dashboard annotations
Dashboard links
Alert rule queries

interface BaseVariableModel {
  id: string;                  // Unique identifier
  name: string;                // Variable name (used as ${name})
  type: VariableType;          // Variable type
  label?: string;              // Display label in UI
  description?: string;        // Variable description
  hide: VariableHide;          // Visibility setting
  skipUrlSync: boolean;        // Skip URL synchronization
}

enum VariableHide {
  dontHide = 0,               // Show in dropdown
  hideLabel = 1,              // Hide label, show value
  hideVariable = 2            // Completely hide
}

Variable Types

Query Variable

Populate variable values from a data source query:

interface QueryVariableModel extends BaseVariableModel {
  type: 'query';
  query: string | Record<string, any>;  // Data source query
  datasource: DataSourceRef;            // Data source
  refresh: VariableRefresh;             // When to update
  regex?: string;                       // Filter/capture regex
  sort: VariableSort;                   // Sort order
  multi: boolean;                       // Allow multiple selection
  includeAll: boolean;                  // Include "All" option
  allValue?: string;                    // Custom "All" value
}

enum VariableRefresh {
  never = 0,          // Never refresh
  onDashboardLoad = 1,  // On dashboard load
  onTimeRangeChange = 2  // On time range change
}

enum VariableSort {
  disabled = 0,              // No sorting
  alphabeticalAsc = 1,       // A-Z
  alphabeticalDesc = 2,      // Z-A
  numericalAsc = 3,          // 1-9
  numericalDesc = 4,         // 9-1
  alphabeticalCaseInsensitiveAsc = 5,
  alphabeticalCaseInsensitiveDesc = 6
}

Create Query Variable

Go to Dashboard settings → Variables → New variable

Configure Settings

Set name, label, and type to “Query”

Select Data Source

Choose the data source to query

Define Query

Write a query that returns variable values

Set Refresh Behavior

Choose when the variable updates

Save Variable

Click Apply to save the variable

Example Query Variable:

{
  name: "server",
  type: "query",
  label: "Server",
  query: "label_values(up, instance)",  // Prometheus query
  datasource: { type: "prometheus", uid: "prom-uid" },
  refresh: VariableRefresh.onTimeRangeChange,
  multi: true,
  includeAll: true,
  sort: VariableSort.alphabeticalAsc
}

Custom Variable

Define variable values manually:

interface CustomVariableModel extends BaseVariableModel {
  type: 'custom';
  query: string;              // Comma-separated values
  multi: boolean;             // Allow multiple selection
  includeAll: boolean;        // Include "All" option
  allValue?: string;          // Custom "All" value
}

// Example
{
  name: "environment",
  type: "custom",
  label: "Environment",
  query: "production,staging,development",
  multi: false,
  includeAll: false
}

Datasource Variable

Select from available data sources of a specific type:

interface DataSourceVariableModel extends BaseVariableModel {
  type: 'datasource';
  query: string;              // Data source type (e.g., "prometheus")
  regex?: string;             // Filter by name regex
  multi: boolean;             // Allow multiple selection
  includeAll: boolean;        // Include "All" option
}

// Example
{
  name: "datasource",
  type: "datasource",
  label: "Data Source",
  query: "prometheus",        // Type of datasource
  regex: "/prod-.*/",         // Only datasources matching regex
  multi: false
}

Constant Variable

Define a hidden constant value:

interface ConstantVariableModel extends BaseVariableModel {
  type: 'constant';
  query: string;              // The constant value
  hide: VariableHide.hideVariable;  // Usually hidden
}

// Example
{
  name: "cluster",
  type: "constant",
  query: "prod-us-east",
  hide: VariableHide.hideVariable
}

Interval Variable

Provide time interval options:

interface IntervalVariableModel extends BaseVariableModel {
  type: 'interval';
  query: string;              // Comma-separated intervals
  auto: boolean;              // Enable auto option
  auto_count?: number;        // Auto interval count
  auto_min?: string;          // Minimum auto interval
}

// Example
{
  name: "interval",
  type: "interval",
  label: "Interval",
  query: "1m,5m,10m,30m,1h,6h,12h,1d",
  auto: true,
  auto_count: 30,
  auto_min: "10s"
}

Text Box Variable

Allow free-text input:

interface TextBoxVariableModel extends BaseVariableModel {
  type: 'textbox';
  query: string;              // Default value
}

// Example
{
  name: "search",
  type: "textbox",
  label: "Search",
  query: ""                   // Default empty
}

Ad Hoc Filters

Create dynamic key-value filters:

interface AdHocVariableModel extends BaseVariableModel {
  type: 'adhoc';
  datasource: DataSourceRef;  // Data source for filters
  filters: AdHocVariableFilter[];  // Current filters
  baseFilters?: AdHocVariableFilter[];  // Default filters
}

interface AdHocVariableFilter {
  key: string;                // Label/tag name
  operator: string;           // =, !=, =~, !~
  value: string;              // Filter value
  condition?: string;         // AND/OR (for multiple filters)
}

// Example
{
  name: "filters",
  type: "adhoc",
  datasource: { type: "prometheus", uid: "prom-uid" },
  filters: [
    { key: "job", operator: "=", value: "api" },
    { key: "status", operator: "!=", value: "500" }
  ]
}

Ad hoc filters automatically add filter controls to the dashboard and inject filters into queries.

Using Variables

In Queries

Reference variables using ${variable_name} or $variable_name:

# Single value
rate(http_requests_total{instance="${server}"}[5m])

# Multi-value with regex
rate(http_requests_total{instance=~"${server:regex}"}[5m])

# All values
rate(http_requests_total{instance=~"${server:pipe}"}[5m])

Variable Formats

Format variables for different use cases:

// Available formats
${variable}              // Default format
${variable:csv}          // Comma-separated: a,b,c
${variable:pipe}         // Pipe-separated: a|b|c
${variable:regex}        // Regex: (a|b|c)
${variable:json}         // JSON array: ["a","b","c"]
${variable:singlequote}  // Single quotes: 'a','b','c'
${variable:doublequote}  // Double quotes: "a","b","c"
${variable:raw}          // Raw unescaped value
${variable:text}         // Text label instead of value
${variable:percentencode} // URL percent encoding

In Titles and Text

Use variables in panel titles and markdown:

# Dashboard: ${environment} - ${cluster}

## Server: ${server}

Current time range: ${__from:date} to ${__to:date}

Built-in Variables

Grafana provides built-in time and dashboard variables:

// Time range variables
$__from          // Start of time range (milliseconds)
$__to            // End of time range (milliseconds)
$__interval      // Calculated interval
$__interval_ms   // Interval in milliseconds
$__range         // Time range duration
$__range_s       // Range in seconds
$__range_ms      // Range in milliseconds

// Dashboard variables
$__dashboard     // Dashboard name
$__user_id       // Current user ID
$__user_login    // Current user login
$__user_email    // Current user email
$__org_id        // Organization ID
$__org_name      // Organization name

// Time formatting
${__from:date:iso}              // ISO 8601: 2024-01-01T00:00:00Z
${__from:date:YYYY-MM-DD}       // Custom format: 2024-01-01
${__from:date:seconds}          // Unix timestamp

Multi-Value Variables

Allow selecting multiple values:

multi: true          // Enable multi-select
includeAll: true     // Add "All" option
allValue: ".*"       // Value when "All" is selected

Handling Multi-Value in Queries

# Regex format for label matching
metric{label=~"${variable:regex}"}

# Pipe format
metric{label=~"${variable:pipe}"}

Variable Dependencies

Variables can reference other variables:

// First variable: region
{
  name: "region",
  type: "query",
  query: "label_values(region)"
}

// Second variable depends on first
{
  name: "datacenter",
  type: "query",
  query: "label_values(up{region='${region}'}, datacenter)",
  refresh: VariableRefresh.onTimeRangeChange
}

// Third variable depends on second
{
  name: "server",
  type: "query",
  query: "label_values(up{datacenter='${datacenter}'}, instance)",
  refresh: VariableRefresh.onTimeRangeChange
}

Variable dependencies create a chain reaction. When a parent variable changes, all dependent variables refresh automatically.

Variable Regex Filtering

Filter and transform variable values using regex:

regex: string;              // Regex pattern

// Examples
regex: "/^prod-.*/"         // Only values starting with "prod-"
regex: "/server-(.*)/"     // Extract capture group: server-web01 → web01
regex: "/^(?!test).*/"     // Exclude values starting with "test"
regex: "/(staging|prod)/"  // Only staging or prod

Regex with Capture Groups

// Input values: prod-web-01, prod-db-01, prod-cache-01
regex: "/prod-(.*)-\\d+/"  // Extracts: web, db, cache

// Input values: us-east-1a, us-west-2b, eu-west-1c  
regex: "/(us-.*)-.*/"       // Extracts: us-east-1, us-west-2

Variable URL Synchronization

Variables sync with URL parameters:

# URL format
https://grafana.example.com/d/dashboard-uid?var-server=web01&var-env=prod

# Multi-value
?var-server=web01&var-server=web02&var-server=web03

# Disable sync for a variable
skipUrlSync: true

Advanced Configuration

Repeat Panels/Rows by Variable

Create dynamic panels:

// Panel configuration
{
  repeat: "server",           // Variable name
  repeatDirection: "h",       // "h" horizontal, "v" vertical
  maxPerRow: 4                // Max panels per row
}

Variable Value Groups

Group variable values for better organization:

// Query returns: prod:server1, prod:server2, staging:server3
// Automatically groups by prefix before colon
query: "label_values(server)"

Best Practices

Naming

Use clear, descriptive variable names: environment not env, server_name not srv

Labels

Provide user-friendly labels that differ from internal variable names

Order

Order variables logically: region → datacenter → server

Defaults

Set sensible default values to avoid empty dashboards

Performance Tips

Use VariableRefresh.onDashboardLoad for static data
Avoid complex regex patterns on large result sets
Limit multi-value selections when possible
Use constant variables for frequently used values
Cache data source queries when appropriate

Common Patterns

Environment Selector

{
  name: "env",
  type: "custom",
  label: "Environment",
  query: "production,staging,development",
  current: { value: "production", text: "Production" }
}

Dynamic Datasource

{
  name: "datasource",
  type: "datasource",
  label: "Data Source",
  query: "prometheus",
  multi: false,
  includeAll: false
}

Time Interval

{
  name: "rate_interval",
  type: "interval",
  label: "Rate Interval",
  query: "1m,5m,10m,30m,1h",
  auto: true,
  auto_count: 30,
  auto_min: "1m"
}

Troubleshooting

Variable Not Updating

Check refresh setting matches your use case
Verify query returns data
Check for circular dependencies
Review data source permissions

Verify query syntax for the data source type
Check time range includes data
Review regex filter pattern
Ensure data source is accessible

Multi-Value Not Working

Use appropriate format: ${var:regex} for labels, ${var:singlequote} for SQL
Check allValue configuration
Verify query supports multiple values

Next Steps

Templating

Learn advanced templating techniques

Creating Dashboards

Apply variables when creating dashboards

Panels

Use variables in panel queries

Sharing

Share dashboards with variable values

Overview

Getting Started

Dashboards

Data Sources

Alerting

Explore

Visualization

​Dashboard Variables

​What are Variables?

​Variable Types

​Query Variable

​Custom Variable

​Datasource Variable

​Constant Variable

​Interval Variable

​Text Box Variable

​Ad Hoc Filters

​Using Variables

​In Queries

​Variable Formats

​In Titles and Text

​Built-in Variables

​Multi-Value Variables

​Handling Multi-Value in Queries

​Variable Dependencies

​Variable Regex Filtering

​Regex with Capture Groups

​Variable URL Synchronization

​Advanced Configuration

​Repeat Panels/Rows by Variable

​Variable Value Groups

​Best Practices

Naming

Labels

Order

Defaults

​Performance Tips

​Common Patterns

​Environment Selector

​Dynamic Datasource

​Time Interval

​Troubleshooting

​Variable Not Updating

​Empty Dropdown

​Multi-Value Not Working

​Next Steps

Templating

Creating Dashboards

Panels

Sharing

Build docs developers (and LLMs) love

Dashboard Variables

What are Variables?

Variable Types

Query Variable

Custom Variable

Datasource Variable

Constant Variable

Interval Variable

Text Box Variable

Ad Hoc Filters

Using Variables

In Queries

Variable Formats

In Titles and Text

Built-in Variables

Multi-Value Variables

Handling Multi-Value in Queries

Variable Dependencies

Variable Regex Filtering

Regex with Capture Groups

Variable URL Synchronization

Advanced Configuration

Repeat Panels/Rows by Variable

Variable Value Groups

Best Practices

Performance Tips

Common Patterns

Environment Selector

Dynamic Datasource

Time Interval

Troubleshooting

Variable Not Updating

Empty Dropdown

Multi-Value Not Working

Next Steps