Creating Dashboard Variables

1. Creating Query Variables

Property	Description	Example
name	Unique identifier for the variable	`instance`
label	Display name in the dashboard	`Instance`
query	Query to fetch variable values	`label_values(up, instance)`
refresh	When to refresh the variable values	`on Dashboard Load`
multi	Allow multiple selections	`true`
hide	Hide variable from dashboard	`false`

Example: Query Variable Configuration

{
  "name": "instance",
  "label": "Instance",
  "query": "label_values(up, instance)",
  "refresh": "on Dashboard Load",
  "multi": true,
  "hide": false
}

2. Creating Custom Variables

Property	Description	Example
name	The variable name used in queries and templates	`env`
label	Optional display label for the variable in the dashboard	`Environment`
type	Variable type (text, query, constant, datasource, interval)	`query`
hide	Controls visibility in the dashboard (0 = visible, 1 = hidden, 2 = variable)	`0`
multi	Allow selecting multiple values (true/false)	`false`
refresh	When to refresh the variable options (on dashboard load, on time range change, or manual)	`1`

Example: Creating a Custom Query Variable

{
  "name": "env",
  "label": "Environment",
  "type": "query",
  "hide": 0,
  "multi": false,
  "refresh": 1,
  "datasource": "Prometheus",
  "query": "label_values(up, job)"
}

Note: The query field uses the datasource's query language to fetch variable values.

Example: Creating a Constant Variable

{
  "name": "version",
  "label": "Version",
  "type": "constant",
  "hide": 0,
  "value": "v1.2.3"
}

3. Creating Constant Variables

Property	Value	Description
name	`"constantVar"`	Unique identifier for the variable
type	`"constant"`	Specifies the variable type as constant
value	`"staticValue"`	The fixed value that the variable holds

Example: Constant Variable in Dashboard JSON

{
  "panels": [],
  "templating": {
    "list": [
      {
        "name": "constantVar",
        "type": "constant",
        "value": "staticValue"
      }
    ]
  }
}

Note: Constant variables are useful for hardcoding values that should remain unchanged across dashboard instances.

4. Creating Interval Variables

Property	Value	Description
name	`interval`	Variable name used in queries and templates
type	`interval`	Defines the variable as an interval type
label	`time interval`	Human-readable label for the variable in the UI
query	`1m,5m,10m,30m,1h,6h,12h,1d,7d,30d`	Comma-separated list of interval values
refresh	`1`	Refresh behavior (1 = on dashboard load)

Example: Using Interval Variables in Queries

SELECT 
  timestamp,
  value
FROM metrics 
WHERE 
  $__timeFilter(timestamp) 
  AND interval = '$interval'

Note: Interval variables are particularly useful for time-series data where you want to allow users to switch between different aggregation periods (e.g., hourly vs daily).

5. Creating Data Source Variables

Property	Description	Example
name	The name of the variable	`datasource_var`
type	Must be `datasource`	`datasource`
label	Label for the variable in the dashboard	`Database Source`
query	Query to fetch data source names	`datasources`
refresh	When to refresh the variable values	`on Dashboard Load`

Example: Data Source Variable Configuration

{
  "name": "datasource_var",
  "type": "datasource",
  "label": "Database Source",
  "query": "datasources",
  "refresh": 1
}

Note: Data source variables allow you to dynamically select from available data sources in your Grafana instance.

6. Creating Ad Hoc Filters

Ad hoc filters allow users to dynamically filter data in a dashboard by adding arbitrary key-value pairs to the query. These filters are particularly useful for exploring data in real-time without predefined variables.

Property	Description	Example
name	The variable name used to reference the filter in queries.	`filter`
type	Must be set to `adhoc` for ad hoc filters.	`adhoc`
datasource	The data source to apply the filter to.	`prometheus`
hide	Controls whether the filter is hidden from users. Set to `1` to hide.	`0`

Example: Ad Hoc Filter Configuration

{
  "name": "filter",
  "type": "adhoc",
  "datasource": {
    "type": "prometheus",
    "uid": "prometheus-datasource-uid"
  },
  "hide": 0
}

Note: Ad hoc filters are supported in Grafana versions 8.0 and later.

Warning: Ad hoc filters can significantly increase query load if used with large datasets or frequent updates.

Key Points

Ad hoc filters are defined using type: adhoc.
They can be applied to any data source that supports filtering.
Filters are added dynamically by users at runtime.

7. Creating Text Box Variables

Property	Value	Description
name	`textBoxVar`	Unique identifier for the variable
type	`textbox`	Specifies the variable type as a text box
label	`Search Term`	User-friendly label for the variable in the dashboard
query	`default search term`	Default value for the text box variable
hide	`0`	Controls visibility in the dashboard (0 = visible, 1 = hidden)

Example: Text Box Variable Configuration

{
  "name": "textBoxVar",
  "type": "textbox",
  "label": "Search Term",
  "query": "default search term",
  "hide": 0
}

Note: Text box variables are useful for dynamic search terms or user-defined inputs that do not require a predefined list of values.

8. Configuring Multi-Value Selection

Property	Values	Description
multi	`true` / `false`	Enables or disables multi-value selection for the variable
includeAll	`true` / `false`	If enabled, adds an "All" option to the variable dropdown
allValue	`string`	Value to use when "All" is selected (e.g., `"$__all"`)

Example: Multi-Value Variable Configuration

{
  "name": "region",
  "type": "query",
  "multi": true,
  "includeAll": true,
  "allValue": "$__all"
}

Note: When multi is set to true, the variable can select multiple values, and the dashboard will filter using an IN clause in queries.

Warning: Using includeAll with multi-value variables can lead to performance issues if the "All" option includes too many values.

9. Setting Variable Display Options

Option	Values	Description
hide	`0`, `1`, `2`	0 = Show variable, 1 = Hide variable, 2 = Hide variable and show in dropdown
label	`string`	Text to display as the variable label in the dashboard
description	`string`	Help text to describe the variable's purpose
multiValue	`true`, `false`	Allow selecting multiple values from the variable
includeAll	`true`, `false`	Include an 'All' option in the variable dropdown
allValue	`string`	Value to use when 'All' is selected (e.g., `'.*'`)

Example: Setting Variable Display Options

{
  "name": "env",
  "type": "query",
  "label": "Environment",
  "hide": 0,
  "multiValue": true,
  "includeAll": true,
  "allValue": ".*"
}

Note: The hide option can be used to hide variables from the dashboard UI while still allowing them to be used in queries.

10. Configuring Variable Refresh

Property	Values	Description
refresh	`on dashboard load`, `on time range change`, `manual`, `never`	Determines when the variable values are refreshed
refresh	`1m`, `5m`, `10m`, `30m`, `1h`	Interval for auto-refreshing variables (only used when refresh is set to a time value)

Example: Setting refresh interval for a variable

{
  "name": "env",
  "type": "query",
  "refresh": "10m",
  "datasource": {
    "type": "prometheus",
    "uid": "prometheus-datasource-uid"
  },
  "query": "label_values(up, job)"
}

Note: Setting refresh to manual requires the user to click the refresh button in the dashboard to update variable values.

Warning: Setting refresh to on dashboard load or on time range change can increase dashboard load times if the variable query is expensive.

11. Setting Variable Sort Order

Option	Description	Notes
sort	`0`	Disabled sorting
sort	`1`	Sort by name (ascending)
sort	`2`	Sort by name (descending)
sort	`3`	Sort by value (ascending)
sort	`4`	Sort by value (descending)
sort	`5`	Sort by numeric value (ascending)
sort	`6`	Sort by numeric value (descending)

Example: Setting Sort Order in Variable Definition

{
  "name": "env",
  "label": "Environment",
  "description": "Select environment",
  "type": "query",
  "datasource": {
    "type": "prometheus",
    "uid": "prometheus-datasource-uid"
  },
  "query": "label_values(up, job)",
  "sort": 1
}

12. Using Variable Dependencies

Variable	Dependencies	Description
${var1}	`${var2}`	Uses `${var2}` to filter results
${var2}	`${var3}`	Depends on `${var3}` for value

Example: Variable Dependency Setup

const dashboard = {
  "panels": [
    {
      "type": "graph",
      "targets": [
        {
          "expr": "up{job=\"${var1}\"}"
        }
      ]
    }
  ],
  "templating": {
    "list": [
      {
        "name": "var1",
        "datasource": "Prometheus",
        "query": "label_values(up, job)"
      },
      {
        "name": "var2",
        "datasource": "Prometheus",
        "query": "label_values(up{job=\"${var1}\"}, instance)"
      }
    ]
  }
}