Switch variable type: Add docs (#113029)

* docs: add docs for the switch variable type * chore: prettier fix * docs: fix review notes * Apply suggestions from code review Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com> * docs: move the switch variable section after ad-hoc variables * fix: vale fixes * Update docs/sources/visualizations/dashboards/variables/add-template-variables/index.md Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com> --------- Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>
2025-10-28 14:15:54 +00:00
parent 1cb66d86b0
commit 3131a69f04
2 changed files with 92 additions and 0 deletions
@@ -29,6 +29,7 @@ The available variable types described in the following sections:
 - [DatasourceVariableKind](#datasourcevariablekind)
 - [IntervalVariableKind](#intervalvariablekind)
 - [CustomVariableKind](#customvariablekind)
+- [SwitchVariableKind](#switchvariablekind)
 - [GroupByVariableKind](#groupbyvariablekind)
 - [AdhocVariableKind](#adhocvariablekind)

@@ -337,6 +338,50 @@ The following table explains the usage of the custom variable JSON fields:
 | skipUrlSync  | bool. Default is `false`.                                                                                                        |
 | description? | string                                                                                                                           |

+## `SwitchVariableKind`
+
+Following is the JSON for a default switch variable:
+
+```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:
+
+<!-- prettier-ignore-start -->
+
+| 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                                                                                                                           |
+
+<!-- prettier-ignore-end -->
+
 ## `GroupByVariableKind`

 Following is the JSON for a default group by variable:
@@ -104,6 +104,7 @@ The following table lists the types of variables shipped with Grafana.
 | Data source       | Quickly change the data source for an entire dashboard. [Add a data source variable](#add-a-data-source-variable).                                                                      |
 | Interval          | Interval variables represent time spans. [Add an interval variable](#add-an-interval-variable).                                                                                         |
 | Ad hoc filters    | Key/value filters that are automatically added to all metric queries for a data source (Prometheus, Loki, InfluxDB, and Elasticsearch only). [Add ad hoc filters](#add-ad-hoc-filters). |
+| Switch            | Display a switch that allows you to toggle between two configurable values for enabled and disabled states. [Add a switch variable](#add-a-switch-variable).                            |
 | Global variables  | Built-in variables that can be used in expressions in the query editor. Refer to [Global variables](#global-variables).                                                                 |
 | Chained variables | Variable queries can contain other variables. Refer to [Chained variables](#chained-variables).                                                                                         |

@@ -135,6 +136,7 @@ To create a variable, follow these steps:
   - [Data source](#add-a-data-source-variable)
   - [Interval](#add-an-interval-variable)
   - [Ad hoc filters](#add-ad-hoc-filters)
+   - [Switch](#add-a-switch-variable)

 <!-- vale Grafana.Spelling = YES -->

@@ -384,6 +386,51 @@ If one of the panels in the dashboard using that data source doesn't include tha
 In cases where the data source you're using doesn't support ad hoc filtering, consider using the special Dashboard data source.
 For more information, refer to [Filter any data using the Dashboard data source](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#filter-any-data-using-the-dashboard-data-source).

+## Add a switch variable
+
+_Switch_ variables display a switch with two configurable values representing enabled and disabled states. This variable type is useful when you need to:
+
+- Toggle between different query conditions
+- Enable or disable specific filters
+- Switch between different visualization modes
+- Control boolean parameters in your data sources
+
+1. [Enter general options](#enter-general-options).
+1. Under the **Switch options** section of the page, configure the switch values:
+
+   In the **Value pair type** drop-down list, select one of the following predefined options or choose **Custom** to define your own values:
+   - **True / False** - Uses boolean values `true` and `false`
+   - **1 / 0** - Uses numeric values `1` and `0`
+   - **Yes / No** - Uses string values `yes` and `no`
+   - **Custom** - Allows you to define custom values for both enabled and disabled states
+
+1. If you selected **Custom** in the previous step, configure the custom values:
+   - **Enabled value** - Enter the value that represents the enabled state (for example, "on").
+   - **Disabled value** - Enter the value that represents the disabled state (for example, "off").
+
+1. Click **Save dashboard**.
+1. Click **Back to dashboard** and **Exit edit**.
+
+### Switch variable examples
+
+The following example shows a switch variable `$debug_mode` used in a Prometheus query to conditionally include debug labels:
+
+```
+up{job="my-service"} and ($debug_mode == "true" or on() vector(0))
+```
+
+The following example shows a switch variable `$show_errors` used to filter log entries:
+
+```
+{job="application"} |= ($show_errors == "1" ? "ERROR" : "")
+```
+
+You can also use switch variables in panel titles and other dashboard elements:
+
+```
+{{#if debug_mode}}Debug Mode: {{/if}}Application Metrics
+```
+
 <!-- vale Grafana.Spelling = YES -->
 <!-- vale Grafana.WordList = YES -->