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.

Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Observability as Codebreadcrumb arrow JSON schema v2breadcrumb arrow variables schema
Grafana Cloud Enterprise Open source

variables

The available variable types described in the following sections:

QueryVariableKind

Following is the JSON for a default query variable:

JSON 
  "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:

QueryVariableSpec

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

NameUsage
namestring. Name of the variable.
current“Text” and a “value” or VariableOption
label?string
hideVariableHide. Options are: dontHide, hideLabel, and hideVariable.
refreshVariableRefresh. Options are never, onDashboardLoad, and onTimeChanged.
skipUrlSyncbool. Default is false.
description?string
datasource?DataSourceRef
queryDataQueryKind. Consists of:
  • kind: string
  • spec: string
regexstring
sortVariableSort. Options are:
  • disabled
  • alphabeticalAsc
  • alphabeticalDesc
  • numericalAsc
  • numericalDesc
  • alphabeticalCaseInsensitiveAsc
  • alphabeticalCaseInsensitiveDesc
  • naturalAsc
  • naturalDesc
definition?string
optionsVariableOption
multibool. Default is false.
includeAllbool. Default is false.
allValue?string
placeholder?string

VariableOption

NameUsage
selectedbool. Whether or not the option is selected.
textstring. Text to be displayed for the option.
valuestring. Value of the option.

DataSourceRef

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

TextVariableKind

Following is the JSON for a default text variable:

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

TextVariableKind consists of:

TextVariableSpec

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

NameUsage
namestring. Name of the variable.
current“Text” and a “value” or VariableOption. Refer to the VariableOption definition under QueryVariableKind.
querystring
label?string
hideVariableHide. Options are: dontHide, hideLabel, and hideVariable.
skipUrlSyncbool. Default is false.
description?string

ConstantVariableKind

Following is the JSON for a default constant variable:

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

ConstantVariableKind consists of:

ConstantVariableSpec

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

NameUsage
namestring. Name of the variable.
querystring
current“Text” and a “value” or VariableOption. Refer to the VariableOption definition under QueryVariableKind.
label?string
hideVariableHide. Options are: dontHide, hideLabel, and hideVariable.
skipUrlSyncbool. Default is false.
description?string

DatasourceVariableKind

Following is the JSON for a default data source variable:

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

DatasourceVariableKind consists of:

DatasourceVariableSpec

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

NameUsage
namestring. Name of the variable.
pluginIdstring
refreshVariableRefresh. Options are never, onDashboardLoad, and onTimeChanged.
regexstring
currentText and a value or VariableOption. Refer to the VariableOption definition under QueryVariableKind.
optionsVariableOption. Refer to the VariableOption definition under QueryVariableKind.
multibool. Default is false.
includeAllbool. Default is false.
allValue?string
label?string
hideVariableHide. Options are: dontHide, hideLabel, and hideVariable.
skipUrlSyncbool. Default is false.
description?string

IntervalVariableKind

Following is the JSON for a default interval variable:

JSON 
  "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:

IntervalVariableSpec

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

NameUsage
namestring. Name of the variable.
querystring
currentText and a value or VariableOption. Refer to the VariableOption definition under QueryVariableKind.
optionsVariableOption. Refer to the VariableOption definition under QueryVariableKind.
autobool. Default is false.
auto_countinteger. Default is 0.
refreshVariableRefresh. Options are never, onDashboardLoad, and onTimeChanged.
label?string
hideVariableHide. Options are: dontHide, hideLabel, and hideVariable.
skipUrlSyncbool. Default is false
description?string

CustomVariableKind

Following is the JSON for a default custom variable:

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

CustomVariableKind consists of:

CustomVariableSpec

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

NameUsage
namestring. Name of the variable.
querystring
currentText and a value or VariableOption. Refer to the VariableOption definition under QueryVariableKind.
optionsVariableOption. Refer to the VariableOption definition under QueryVariableKind.
multibool. Default is false.
includeAllbool. Default is false.
allValue?string
label?string
hideVariableHide. Options are: dontHide, hideLabel, and hideVariable.
skipUrlSyncbool. Default is false.
description?string

GroupByVariableKind

Following is the JSON for a default group by variable:

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

GroupByVariableKind consists of:

GroupByVariableSpec

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

NameUsage
namestring. Name of the variable
datasource?DataSourceRef. Refer to the DataSourceRef definition under QueryVariableKind.
currentText and a value or VariableOption. Refer to the VariableOption definition under QueryVariableKind.
optionsVariableOption. Refer to the VariableOption definition under QueryVariableKind.
multibool. Default is false.
label?string
hideVariableHide. Options are: dontHide, hideLabel, and hideVariable.
skipUrlSyncbool. Default is false.
description?string.

AdhocVariableKind

Following is the JSON for a default ad hoc variable:

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

AdhocVariableKind consists of:

AdhocVariableSpec

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

NameUsage
namestring. Name of the variable.
datasource?DataSourceRef. Consists of:
  • type? - string. The plugin type-id.
  • uid? - string. The specific data source instance.
baseFiltersAdHocFilterWithLabels
filtersAdHocFilterWithLabels
defaultKeysMetricFindValue
label?string
hideVariableHide. Options are: dontHide, hideLabel, and hideVariable.
skipUrlSyncbool. Default is false.
description?string

AdHocFiltersWithLabels

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

NameType
keystring
operatorstring
valuestring
values?[...string]
keyLabelstring
valueLabels?[...string]
forceEdit?bool

MetricFindValue

The following table explains the usage of the metric find value JSON fields:

NameType
textstring
value?string or number
group?string
expandable?bool