--- title: "variables | Grafana documentation" description: "A reference for the JSON variables schema used with Observability as Code." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # `variables` The available variable types described in the following sections: - [QueryVariableKind](#queryvariablekind) - [TextVariableKind](#textvariablekind) - [ConstantVariableKind](#constantvariablekind) - [DatasourceVariableKind](#datasourcevariablekind) - [IntervalVariableKind](#intervalvariablekind) - [CustomVariableKind](#customvariablekind) - [SwitchVariableKind](#switchvariablekind) - [GroupByVariableKind](#groupbyvariablekind) - [AdhocVariableKind](#adhocvariablekind) ## `QueryVariableKind` Following is the JSON for a default query variable: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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: - kind: “QueryVariable” - spec: [QueryVariableSpec](#queryvariablespec) ### `QueryVariableSpec` The following table explains the usage of the query variable JSON fields: Expand table NameUsage namestring. Name of the variable. current“Text” and a “value” or [`VariableOption`](#variableoption) label?string hide`VariableHide`. Options are: `dontHide`, `hideLabel`, and `hideVariable`. refresh`VariableRefresh`. Options are `never`, `onDashboardLoad`, and `onTimeChanged`. skipUrlSyncbool. Default is `false`. description?string datasource?[`DataSourceRef`](#datasourceref) query`DataQueryKind`. Consists of: - kind: string - spec: string regexstring sort`VariableSort`. Options are: - disabled - alphabeticalAsc - alphabeticalDesc - numericalAsc - numericalDesc - alphabeticalCaseInsensitiveAsc - alphabeticalCaseInsensitiveDesc - naturalAsc - naturalDesc definition?string options[`VariableOption`](#variableoption) multibool. Default is `false`. includeAllbool. Default is `false`. allValue?string placeholder?string #### `VariableOption` Expand table | 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` Expand table | Name | Usage | |-------|------------------------------------| | type? | string. The plugin type-id. | | uid? | The specific data source instance. | ## `TextVariableKind` Following is the JSON for a default text variable: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "variables": [ { "kind": "TextVariable", "spec": { "current": { "text": "", "value": "" }, "hide": "dontHide", "name": "", "query": "", "skipUrlSync": false } } ] ``` `TextVariableKind` consists of: - kind: TextVariableKind - spec: [TextVariableSpec](#textvariablespec) ### `TextVariableSpec` The following table explains the usage of the query variable JSON fields: Expand table | Name | Usage | |--------------|----------------------------------------------------------------------------------------------------------------------------------| | name | string. Name of the variable. | | current | “Text” and a “value” or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "variables": [ { "kind": "ConstantVariable", "spec": { "current": { "text": "", "value": "" }, "hide": "hideVariable", "name": "", "query": "", "skipUrlSync": true } } ] ``` `ConstantVariableKind` consists of: - kind: “ConstantVariable” - spec: [ConstantVariableSpec](#constantvariablespec) ### `ConstantVariableSpec` The following table explains the usage of the constant variable JSON fields: Expand table | Name | Usage | |--------------|----------------------------------------------------------------------------------------------------------------------------------| | name | string. Name of the variable. | | query | string | | current | “Text” and a “value” or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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: - kind: “DatasourceVariable” - spec: [DatasourceVariableSpec](#datasourcevariablespec) ### `DatasourceVariableSpec` The following table explains the usage of the data source variable JSON fields: Expand table | 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](#variableoption) under `QueryVariableKind`. | | options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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: - kind: “IntervalVariable” - spec: [IntervalVariableSpec](#intervalvariablespec) ### `IntervalVariableSpec` The following table explains the usage of the interval variable JSON fields: Expand table | Name | Usage | |--------------|----------------------------------------------------------------------------------------------------------------------------------| | name | string. Name of the variable. | | query | string | | current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | | options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "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) ### `CustomVariableSpec` The following table explains the usage of the custom variable JSON fields: Expand table | Name | Usage | |--------------|----------------------------------------------------------------------------------------------------------------------------------| | name | string. Name of the variable. | | query | string | | current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | | options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) 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 | ## `SwitchVariableKind` Following is the JSON for a default switch variable: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "variables": [ { "kind": "SwitchVariable", "spec": { "current": "false", "enabledValue": "true", "disabledValue": "false", "hide": "dontHide", "name": "", "skipUrlSync": false } } ] ``` `SwitchVariableKind` consists of: - kind: “SwitchVariable” - spec: [SwitchVariableSpec](#switchvariablespec) ### `SwitchVariableSpec` The following table explains the usage of the switch variable JSON fields: Expand table | Name | Usage | |---------------|------------------------------------------------------------------------------------------| | name | string. Name of the variable. | | current | string. Current value of the switch variable (either `enabledValue` or `disabledValue`). | | enabledValue | string. Value when the switch is in the enabled state. | | disabledValue | string. Value when the switch is in the disabled state. | | 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "variables": [ { "kind": "GroupByVariable", "spec": { "current": { "text": [ "" ], "value": [ "" ] }, "datasource": {}, "hide": "dontHide", "multi": false, "name": "", "options": [], "skipUrlSync": false } } ] ``` `GroupByVariableKind` consists of: - kind: “GroupByVariable” - spec: [GroupByVariableSpec](#groupbyvariablespec) ### `GroupByVariableSpec` The following table explains the usage of the group by variable JSON fields: Expand table | Name | Usage | |--------------|----------------------------------------------------------------------------------------------------------------------------------| | name | string. Name of the variable | | datasource? | `DataSourceRef`. Refer to the [`DataSourceRef` definition](#datasourceref) under `QueryVariableKind`. | | current | `Text` and a `value` or `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) under `QueryVariableKind`. | | options | `VariableOption`. Refer to the [`VariableOption` definition](#variableoption) 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "variables": [ { "kind": "AdhocVariable", "spec": { "baseFilters": [], "defaultKeys": [], "filters": [], "hide": "dontHide", "name": "", "skipUrlSync": false } } ] ``` `AdhocVariableKind` consists of: - kind: “AdhocVariable” - spec: [AdhocVariableSpec](#adhocvariablespec) ### `AdhocVariableSpec` The following table explains the usage of the ad hoc variable JSON fields: Expand table NameUsage namestring. Name of the variable. datasource?`DataSourceRef`. Consists of: - type? - string. The plugin type-id. - uid? - string. The specific data source instance. baseFilters[AdHocFilterWithLabels](#adhocfilterswithlabels) filters[AdHocFilterWithLabels](#adhocfilterswithlabels) defaultKeys[MetricFindValue](#metricfindvalue) label?string hide`VariableHide`. 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: Expand table | Name | Type | |--------------|---------------| | key | string | | operator | string | | value | string | | values? | `[...string]` | | keyLabel | string | | valueLabels? | `[...string]` | | forceEdit? | bool | #### `MetricFindValue` The following table explains the usage of the metric find value JSON fields: Expand table | Name | Type | |-------------|------------------| | text | string | | value? | string or number | | group? | string | | expandable? | bool |