> ## 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.

# 变量

> 用模板变量让一个仪表盘在服务、主机或环境之间切换，并为每个取值重复面板。

变量把在网格上方选中的值代入每个面板的查询、标题和链接。这样一个仪表盘就能服务所有服务、主机或环境，而不必为每一个复制一份。

## 添加变量

打开编辑器，点击 **设置 → 变量**，然后添加变量：

| 字段 | 规则 |
| - | - |
| **名称** | 在查询中使用的名称，例如 `service`。只用字母、数字和 `_`，并以字母或 `_` 开头，否则不会被替换。 |
| **标签** | 显示在选择器上方的文字。 |
| **类型** | 取值的来源。参见[类型](#类型)。 |
| **查询 / 选项** | 查询或取值，取决于类型。 |
| **多选** | 可以同时选择多个值。 |
| **包含全部选项** | 增加 **All**，代表列表中的全部取值。 |
| **隐藏方式** | **无** 显示选择器，**标签** 隐藏它的标签，**变量** 隐藏选择器。 |
| **刷新** | 查询变量何时重新读取取值：**从不**、**加载时**，或每次 **时间范围** 变化时。 |

保存仪表盘后变量才会保留。

## 类型

| 类型 | 取值 |
| - | - |
| **查询** | 从数据中读取。参见[查询变量](#查询变量)。 |
| **自定义** | 固定列表，用逗号分隔，例如 `prod, staging, dev`。 |
| **文本** | 查看者在网格上方的输入框中输入的内容。 |
| **常量** | 保存在仪表盘模型中的固定值，不会显示在网格上方。 |
| **间隔**、**数据源** | 保存在仪表盘模型中的列表，例如随导入的 JSON 一起带来的列表。 |

### 查询变量

查询变量在当前时间范围内读取取值。选择 **查询类型**：

| 查询类型 | 字段 | 取值 |
| - | - | - |
| **标签值** | **指标** 和 **标签**，例如 `http_requests_total` 和 `service`。 | 该指标各序列上这个标签的取值，覆盖所有持有该指标的指标数据流。 |
| **经典查询** | 表达式，例如 `label_values(http_requests_total, service)`。 | 与 **标签值** 相同。 |
| **SQL** | **数据流名称**、**数据流类型** 和 SQL 语句。 | 第一列的取值。 |

第一个取值作为默认值。查询中可以使用其他变量，例如在 SQL 中写 `WHERE environment = '$env'`，这样选中某个环境后，服务列表会随之缩小。

## 使用变量

在查询、面板标题、文本元素或链接中写 `$name` 或 `${name}`。名称后面紧跟字母时需要花括号，例如 `${service}_errors`。多选变量的多个取值默认用逗号连接；加上格式可以改变连接方式：

| 写法 | `checkout` 和 `payment` 的结果 |
| - | - |
| `${service}` | `checkout,payment` |
| `${service:csv}` | `checkout,payment` |
| `${service:pipe}` | `checkout\|payment` |
| `${service:regex}` | `checkout\|payment`，每个取值都按正则表达式转义。 |
| `${service:sqlstring}` | `'checkout','payment'`，按 SQL 加引号，例如用于 `IN (${service:sqlstring})`。 |
| `${service:json}` | `["checkout","payment"]` |

例如 PromQL 面板 `sum(rate(http_requests_total{service=~"${service:regex}"}[5m]))` 会跟随选中的服务变化。

## 地址中的取值

选中的取值保存在仪表盘地址中，形式为 `var-<name>=<value>`，多选变量的每个取值各占一个参数。复制地址，或用这些参数拼出链接，即可用同样的取值打开仪表盘。[数据链接](https://docs.molesignal.com/zh-Hans/dashboards/edit.md#数据链接)也可以把变量传递下去。

## 按变量重复面板

在面板的 **面板** 标签页中选择 **重复变量**。仪表盘会为每个选中的取值绘制一份面板副本，副本中的变量取该值。选择 **重复方向**（**横向**、**纵向** 或 **网格**）和 **每行最多数量**。只有原始面板会被保存，副本跟随选择变化。


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