> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables

> Let one dashboard switch between services, hosts, or environments with template variables, and repeat a panel for each value.

A variable puts a value chosen above the grid into the queries, titles, and links of every panel. One
dashboard then serves every service, host, or environment, without a copy for each.

## Add a variable

Open the editor, select **Settings → Variables**, and add a variable:

| Field | Rule |
| - | - |
| **Name** | The name used in queries, such as `service`. Use letters, digits, and `_`, starting with a letter or `_`: other names are not replaced. |
| **Label** | The text shown above the selector. |
| **Type** | Where the values come from. See [Types](#types). |
| **Query / options** | The query or the values, depending on the type. |
| **Multi** | Several values can be chosen at once. |
| **Include all** | Adds **All**, which stands for every value of the list. |
| **Hide** | **None** shows the selector, **Label** hides its label, **Variable** hides the selector. |
| **Refresh** | When a query variable reads its values again: **Never**, **On load**, or on each change of the **Time range**. |

Save the dashboard to keep the variable.

## Types

| Type | Values |
| - | - |
| **Query** | Read from the data. See [Query variables](#query-variables). |
| **Custom** | A fixed list, entered comma-separated, for example `prod, staging, dev`. |
| **Text** | Whatever the viewer types in a box above the grid. |
| **Constant** | A fixed value kept in the dashboard model. It never shows above the grid. |
| **Interval**, **Data source** | A list kept in the dashboard model, for example one that came with imported JSON. |

### Query variables

A query variable reads its values in the current time range. Choose the **Query type**:

| Query type | Fields | Values |
| - | - | - |
| **Label values** | **Metric** and **Label**, for example `http_requests_total` and `service`. | The values of the label on the series of the metric, across every metrics stream that holds it. |
| **Classic query** | An expression such as `label_values(http_requests_total, service)`. | The same as **Label values**. |
| **SQL** | **Stream name**, **Stream type**, and an SQL statement. | The values of the first column. |

The first value becomes the default. A query can use another variable, for example an SQL statement
with `WHERE environment = '$env'`, so choosing an environment narrows the services.

## Use a variable

Write `$name` or `${name}` in a query, a panel title, a text element, or a link. The braces are needed
when letters follow the name, for example `${service}_errors`. A variable with several values gives
them joined with commas; add a format to change that:

| Syntax | Result for `checkout` and `payment` |
| - | - |
| `${service}` | `checkout,payment` |
| `${service:csv}` | `checkout,payment` |
| `${service:pipe}` | `checkout\|payment` |
| `${service:regex}` | `checkout\|payment`, each value escaped for a regular expression. |
| `${service:sqlstring}` | `'checkout','payment'`, quoted for SQL, for example in `IN (${service:sqlstring})`. |
| `${service:json}` | `["checkout","payment"]` |

For example, a PromQL panel `sum(rate(http_requests_total{service=~"${service:regex}"}[5m]))` follows
the selected services.

## Values in the address

The chosen values are kept in the address of the dashboard as `var-<name>=<value>`, repeated for each
value of a multi-value variable. Copy the address, or build a link with these parameters, to open the
dashboard with the same choice. A [data link](https://docs.molesignal.com/en-US/dashboards/edit.md#data-links) can pass the
variables on as well.

## Repeat panels by a variable

On the **Panel** tab of a panel, choose a **Repeat variable**. The dashboard then draws one copy of the
panel for each selected value, with the variable set to that value in the copy. Choose the
**Repeat direction**: **Horizontal**, **Vertical**, or **Grid**, and **Max per row**. Only the original
panel is saved; the copies follow the selection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.