Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation

Grafana documentation

Observability as Code

JSON schema v2

variables schema

Grafana Cloud Enterprise Open source

`variables`

The available variable types described in the following sections:

QueryVariableKind
TextVariableKind
ConstantVariableKind
DatasourceVariableKind
IntervalVariableKind
CustomVariableKind
GroupByVariableKind
AdhocVariableKind

`QueryVariableKind`

Following is the JSON for a default query variable:

  "variables": [
    {
      "kind": "QueryVariable",
      "spec": {
        "current": {
          "text": "",
          "value": ""
        },
        "hide": "dontHide",
        "includeAll": false,
        "multi": false,
        "name": "",
        "options": [],
        "query": defaultDataQueryKind(),
        "refresh": "never",
        "regex": "",
        "skipUrlSync": false,
        "sort": "disabled"
      }
    }
  ]

QueryVariableKind consists of:

kind: “QueryVariable”
spec: QueryVariableSpec

`QueryVariableSpec`

The following table explains the usage of the query variable JSON fields:

Name	Usage
name	string. Name of the variable.
current	“Text” and a “value” or `VariableOption`
label?	string
hide	`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`.
refresh	`VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`.
skipUrlSync	bool. Default is `false`.
description?	string
datasource?	`DataSourceRef`
query	`DataQueryKind`. Consists of: kind: string spec: string
regex	string
sort	`VariableSort`. Options are: disabled alphabeticalAsc alphabeticalDesc numericalAsc numericalDesc alphabeticalCaseInsensitiveAsc alphabeticalCaseInsensitiveDesc naturalAsc naturalDesc
definition?	string
options	`VariableOption`
multi	bool. Default is `false`.
includeAll	bool. Default is `false`.
allValue?	string
placeholder?	string

`VariableOption`

Name	Usage
selected	bool. Whether or not the option is selected.
text	string. Text to be displayed for the option.
value	string. Value of the option.

`DataSourceRef`

Name	Usage
type?	string. The plugin type-id.
uid?	The specific data source instance.

`TextVariableKind`

Following is the JSON for a default text variable:

  "variables": [
    {
      "kind": "TextVariable",
      "spec": {
        "current": {
          "text": "",
          "value": ""
        },
        "hide": "dontHide",
        "name": "",
        "query": "",
        "skipUrlSync": false
      }
    }
  ]

TextVariableKind consists of:

kind: TextVariableKind
spec: TextVariableSpec

`TextVariableSpec`

The following table explains the usage of the query variable JSON fields:

Name	Usage
name	string. Name of the variable.
current	“Text” and a “value” or `VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
query	string
label?	string
hide	`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`.
skipUrlSync	bool. Default is `false`.
description?	string

`ConstantVariableKind`

Following is the JSON for a default constant variable:

  "variables": [
    {
      "kind": "ConstantVariable",
      "spec": {
        "current": {
          "text": "",
          "value": ""
        },
        "hide": "hideVariable",
        "name": "",
        "query": "",
        "skipUrlSync": true
      }
    }
  ]

ConstantVariableKind consists of:

kind: “ConstantVariable”
spec: ConstantVariableSpec

`ConstantVariableSpec`

The following table explains the usage of the constant variable JSON fields:

Name	Usage
name	string. Name of the variable.
query	string
current	“Text” and a “value” or `VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
label?	string
hide	`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`.
skipUrlSync	bool. Default is `false`.
description?	string

`DatasourceVariableKind`

Following is the JSON for a default data source variable:

  "variables": [
    {
      "kind": "DatasourceVariable",
      "spec": {
        "current": {
          "text": "",
          "value": ""
        },
        "hide": "dontHide",
        "includeAll": false,
        "multi": false,
        "name": "",
        "options": [],
        "pluginId": "",
        "refresh": "never",
        "regex": "",
        "skipUrlSync": false
      }
    }
  ]

DatasourceVariableKind consists of:

kind: “DatasourceVariable”
spec: DatasourceVariableSpec

`DatasourceVariableSpec`

The following table explains the usage of the data source variable JSON fields:

Name	Usage
name	string. Name of the variable.
pluginId	string
refresh	`VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`.
regex	string
current	`Text` and a `value` or `VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
options	`VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
multi	bool. Default is `false`.
includeAll	bool. Default is `false`.
allValue?	string
label?	string
hide	`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`.
skipUrlSync	bool. Default is `false`.
description?	string

`IntervalVariableKind`

Following is the JSON for a default interval variable:

  "variables": [
    {
      "kind": "IntervalVariable",
      "spec": {
        "auto": false,
        "auto_count": 0,
        "auto_min": "",
        "current": {
          "text": "",
          "value": ""
        },
        "hide": "dontHide",
        "name": "",
        "options": [],
        "query": "",
        "refresh": "never",
        "skipUrlSync": false
      }
    }
  ]

IntervalVariableKind consists of:

kind: “IntervalVariable”
spec: IntervalVariableSpec

`IntervalVariableSpec`

The following table explains the usage of the interval variable JSON fields:

Name	Usage
name	string. Name of the variable.
query	string
current	`Text` and a `value` or `VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
options	`VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
auto	bool. Default is `false`.
auto_count	integer. Default is `0`.
refresh	`VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`.
label?	string
hide	`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`.
skipUrlSync	bool. Default is `false`
description?	string

`CustomVariableKind`

Following is the JSON for a default custom variable:

  "variables": [
    {
      "kind": "CustomVariable",
      "spec": {
        "current": defaultVariableOption(),
        "hide": "dontHide",
        "includeAll": false,
        "multi": false,
        "name": "",
        "options": [],
        "query": "",
        "skipUrlSync": false
      }
    }
  ]

CustomVariableKind consists of:

kind: “CustomVariable”
spec: CustomVariableSpec

`CustomVariableSpec`

The following table explains the usage of the custom variable JSON fields:

Name	Usage
name	string. Name of the variable.
query	string
current	`Text` and a `value` or `VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
options	`VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
multi	bool. Default is `false`.
includeAll	bool. Default is `false`.
allValue?	string
label?	string
hide	`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`.
skipUrlSync	bool. Default is `false`.
description?	string

`GroupByVariableKind`

Following is the JSON for a default group by variable:

  "variables": [
    {
      "kind": "GroupByVariable",
      "spec": {
        "current": {
          "text": [
            ""
          ],
          "value": [
            ""
          ]
        },
        "datasource": {},
        "hide": "dontHide",
        "multi": false,
        "name": "",
        "options": [],
        "skipUrlSync": false
      }
    }
  ]

GroupByVariableKind consists of:

kind: “GroupByVariable”
spec: GroupByVariableSpec

`GroupByVariableSpec`

The following table explains the usage of the group by variable JSON fields:

Name	Usage
name	string. Name of the variable
datasource?	`DataSourceRef`. Refer to the `DataSourceRef` definition under `QueryVariableKind`.
current	`Text` and a `value` or `VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
options	`VariableOption`. Refer to the `VariableOption` definition under `QueryVariableKind`.
multi	bool. Default is `false`.
label?	string
hide	`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`.
skipUrlSync	bool. Default is `false`.
description?	string.

`AdhocVariableKind`

Following is the JSON for a default ad hoc variable:

  "variables": [
    {
      "kind": "AdhocVariable",
      "spec": {
        "baseFilters": [],
        "defaultKeys": [],
        "filters": [],
        "hide": "dontHide",
        "name": "",
        "skipUrlSync": false
      }
    }
  ]

AdhocVariableKind consists of:

kind: “AdhocVariable”
spec: AdhocVariableSpec

`AdhocVariableSpec`

The following table explains the usage of the ad hoc variable JSON fields:

Name	Usage
name	string. Name of the variable.
datasource?	`DataSourceRef`. Consists of: type? - string. The plugin type-id. uid? - string. The specific data source instance.
baseFilters	AdHocFilterWithLabels
filters	AdHocFilterWithLabels
defaultKeys	MetricFindValue
label?	string
hide	`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`.
skipUrlSync	bool. Default is `false`.
description?	string