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

# 查询结果字段映射

> 说明如何把 SQL 和原文日志查询结果配置为值字段、标签字段和告警附加信息。

MySQL、PostgreSQL、Oracle、ClickHouse、Elasticsearch、SLS 等表格型查询，以及 Loki 和 VictoriaLogs 的**查原文**模式，都会返回包含多列数据的结果。你可以通过**值字段**和**标签字段**决定每一列的用途；其余列无需单独配置，会作为附加信息随告警携带。

<Warning>
  本页描述的完整字段映射行为需要 monit-edge `v0.53.0` 或以上版本，尤其是将查询附加信息统一命名为 `$<查询名称>.<字段名称>` 的能力。使用这些配置前，请先将告警引擎升级到 `v0.53.0` 或更高版本。
</Warning>

## 字段如何分类

假设查询 A 返回以下数据：

| service  | error\_count | sample\_message    | latest\_at          |
| -------- | -----------: | ------------------ | ------------------- |
| checkout |           27 | connection timeout | 2026-07-30 21:00:00 |

推荐配置：

| 字段用途 | 配置或结果                        | 作用                            |
| ---- | ---------------------------- | ----------------------------- |
| 值字段  | `error_count`                | 作为数值参与阈值判定，也会保存在告警事件中。        |
| 标签字段 | `service`                    | 标识告警对象。同一组标签对应同一个告警实例。        |
| 附加信息 | `sample_message`、`latest_at` | 自动随告警携带，用于补充排障上下文，但不参与告警身份计算。 |

<Note>
  附加信息不是需要填写的第三组字段。只要你明确选择了标签字段，查询结果中既不是标签字段、也不是值字段的列就会自动成为附加信息。
</Note>

### 值字段

值字段应返回可转换为数字的内容。启用**阈值判定**时必须至少配置一个值字段；使用**数据存在**或**数据缺失**模式时可以不配置。

* 值字段名称不能为空，也不能包含 `.`。
* 同一个字段不能同时配置为值字段和标签字段。
* 请先预览数据，按预览结果填写真实字段名。保存规则时不会连接数据源确认该列一定存在。

### 标签字段

标签字段决定告警身份，也决定不同查询的结果能否对应。请选择服务、集群、主机、实例等稳定维度。

* 标签字段名称不能为空，同一个字段不要重复添加。
* 同一个字段不能同时配置为标签字段和值字段。

不建议把以下内容配置为标签：

* 时间戳
* 日志原文或错误消息
* Trace ID、请求 ID 等每次都可能变化的值
* 其他高基数字段

这些字段变化频繁，作为标签时可能让每一行数据形成不同的告警，或者导致多个查询无法对齐。把它们留作附加信息更合适。

### 标签字段留空时

为了兼容已有规则，标签字段留空时，查询结果中除值字段外的所有字段都会作为标签，不会再产生查询附加信息。

| 标签字段配置 | 标签     | 附加信息   |
| ------ | ------ | ------ |
| 留空     | 所有非值字段 | 无      |
| 明确选择   | 仅选择的字段 | 其余非值字段 |

<Warning>
  对于日志原文查询，建议明确选择标签字段。否则时间戳和日志正文也可能成为标签，造成大量彼此独立的告警。
</Warning>

SLS 查询结果自带的 `__source__` 和 `__time__` 不会在标签字段留空时自动成为标签。如需使用这些内容，建议在查询中设置别名，再按普通字段配置。

## 在阈值表达式中引用值

查询名称就是阈值变量的前缀。例如，查询 A 的值字段为 `error_count`。

### 一个值字段

只配置一个值字段时，可以使用完整写法，也可以直接使用查询变量：

```text theme={null}
Critical: $A.error_count > 20
Warning: $A > 10
```

两种写法引用的是同一个值。

### 多个值字段

如果查询 A 同时配置了 `error_count` 和 `latency_ms`，必须写明字段名称：

```text theme={null}
Critical: $A.error_count > 20 or $A.latency_ms > 1000
```

此时不能直接写 `$A > 20`。表达式中的字段也必须已配置为该查询的值字段。这个要求同样适用于“结果满足条件才算恢复”的恢复表达式。

### 查询名称

查询名称必须以英文字母开头，后面只能包含英文字母和数字，例如 `A`、`B2` 或 `Latency`。`R` 和 `__all__` 是保留名称，不能使用。

## 多个查询如何对齐

在**阈值判定**模式中，查询 A、B 的结果只有在标签字段名和标签值都完全相同时，才能进入同一次阈值计算。

以下结果可以一一对应：

| 查询 | service  | cluster |               值字段 |
| -- | -------- | ------- | ----------------: |
| A  | checkout | prod    |  `error_count=27` |
| B  | checkout | prod    | `latency_ms=1350` |

你可以配置：

```text theme={null}
Critical: $A.error_count > 20 and $B.latency_ms > 1000
```

如果查询 B 没有 `cluster` 标签，或者 `cluster` 的值不同，这两行不会合并计算。请确保：

1. 各查询选择相同的标签字段，并返回相同的标签值。
2. 每个查询中，一个标签组合只对应一行结果。必要时先在查询语句中聚合。
3. 错误消息、日志正文等变化字段作为附加信息，不要作为标签。

<Warning>
  启用阈值判定并配置多个查询时，Critical、Warning、Info 的告警阈值表达式合计必须引用全部查询。并非每个级别都必须引用全部查询，例如 Critical 使用 A、Warning 使用 B 是允许的；不参与任何告警阈值的查询应删除。
</Warning>

## 在备注描述中使用附加信息

查询附加信息会进入 `$annotations`，并始终使用 `$<查询名称>.<字段名称>` 作为 key。无论配置了几个查询，也无论使用阈值判定、数据存在还是数据缺失模式，写法都相同：

```gotemplate theme={null}
{{ index $annotations "$A.sample_message" }}
{{ index $annotations "$B.sample_message" }}
```

`$` 前缀用于标识查询产生的字段。规则中手工配置的自定义字段名称不能以 `$` 开头。更多变量和示例请参见[备注模板](/zh/monitors/alert-rules/description-template)。

<Note>
  数据缺失告警会携带该告警对象最后一次成功查询时的附加信息。如果查询从未返回过数据，则没有可携带的查询附加信息。
</Note>

## 适用范围

本页适用于：

* MySQL、PostgreSQL、Oracle、ClickHouse、Elasticsearch 和 SLS 查询
* Loki 和 VictoriaLogs 的**查原文**主查询

Loki 和 VictoriaLogs 的**做统计**模式会直接返回带标签的时序数据，不需要手工映射这些结果字段。