SQL 表达式

注意
SQL 表达式目前处于私有预览阶段。Grafana Labs 提供尽力而为的支持，并且在功能正式发布之前可能会发生破坏性更改。

SQL 表达式是服务器端表达式，使用类似 MySQL 的语法操作和转换数据源查询结果。它们允许你在查询数据后，使用 SQL 轻松查询和转换数据。SQL 提供了一种熟悉且强大的语法，可以处理从简单过滤到高度复杂的、多步骤的转换。

在 Grafana 中，服务器端表达式是在数据从数据源检索后、但在发送到前端进行可视化之前转换或计算数据的一种方式。Grafana 在服务器上评估这些表达式，而不是在浏览器或数据源处。

有关 Grafana 表达式的通用信息，请参阅编写表达式查询。

在开始之前

在特性开关 sqlExpressions 下启用 SQL 表达式。
- 如果你自托管 Grafana，可以在配置文件 grafana.ini 中找到特性开关。

[feature_toggles]
enable = sqlExpressions

如果你使用 Grafana Cloud，请联系支持以启用此功能。

使用 SQL 表达式转换数据

SQL 表达式允许你：

在不更改原始查询的情况下，整形、转换和修改查询结果。
JOIN (连接) 来自多个表的数据。
基于转换后的数据创建警报或记录规则。
对数据集执行最终阶段修改，包括：
- 显示、隐藏或重命名列。
- 根据条件过滤行。
- 聚合数据（例如：求和、平均值、计数）。
编写子查询和公共表表达式 (CTE) 以支持更复杂的逻辑
- 子查询是用于过滤、计算或转换的嵌套查询。
- CTE (公共表表达式) 是临时的命名结果集，有助于使复杂查询更具可读性和可重用性。

SQL 表达式的一个关键能力是能够 JOIN (连接) 来自多个表的数据。这允许用户以可预测、用户友好的方式组合和转换数据——即使对于复杂的用例也是如此。你可以 JOIN 来自无限数量数据源查询的数据。

要使用 SQL 表达式，你必须使用来自后端数据源的数据。在 Grafana 中，后端数据源指通过 Grafana 服务器（而不是直接从浏览器/前端）与数据库、服务或 API 通信的数据源插件或集成。

兼容的数据源

以下是兼容的数据源：

完全支持：支持每个数据源的所有查询类型。

Elasticsearch
MySQL
Loki
Graphite
Google Sheets
Amazon Athena

部分支持：以下数据源提供有限或有条件的支持。有些允许根据访问的服务类型进行不同类型的查询。例如，Azure Monitor 可以查询多个服务，每个服务都有自己的查询格式。在某些情况下，你还可以在面板中更改查询类型。

InfluxDB
Infinity
Azure Monitor
TestData
Tempo
Prometheus
Cloudwatch
GitHub
BigQuery

创建 SQL 表达式

要创建 SQL 表达式，请完成以下步骤：

导航到左侧菜单中的仪表盘。
选择一个仪表盘并打开一个仪表盘面板。
点击右上角的省略号并选择编辑。
点击+ 表达式。
从下拉列表中选择 SQL。

添加 SQL 表达式后，你可以通过在 SQL 表达式中引用查询的 RefID（就像它们是 SQL 数据库中的表一样）来从其他数据源查询中进行选择。

构建 SQL 表达式的工作流程

使用以下工作流程创建 SQL 表达式：

构建你的基础查询。创建单个查询并为其指定有意义的名称。创建提供你希望使用 SQL 表达式组合或转换的数据的查询（A、B 等）。
隐藏你的基础查询。点击每个基础查询旁边的 👁️ 眼睛图标，以将其从可视化中隐藏。这可以保持面板整洁，同时仍使数据可供 SQL 表达式使用。
切换到表格视图。将面板可视化设置为表格，以便在你构建和完善 SQL 表达式时检查和查看其结构和输出。
添加一个 SQL 表达式。添加一个新查询并选择 SQL 表达式作为其类型。
检查输入。从简单的测试查询开始，以了解输入框架的形状。
sql
```
SELECT * FROM A LIMIT 10.
```
这让你可以看到来自 query A 的可用列和示例行。对每个你想使用的输入查询重复此操作（例如，SELECT * FROM B LIMIT 10）。
检查你的数据。对每个输入查询重复此操作，以了解你正在处理的列结构和数据类型。
sql
```
SELECT * FROM <B, C, D, etc> LIMIT 10
```
构造 SQL 表达式。一旦你理解了你的数据，你就可以编写你的 SQL 表达式来连接、过滤或以其他方式转换数据。
验证并迭代。每次更新 SQL 查询后，点击刷新以重新评估并查看更新的结果。

选择可视化类型时，请确保你的 SQL 表达式返回所需形状的数据。例如，时间序列面板需要一个包含时间字段（例如，timestamp）和数值列（例如，__value__）的列。如果输出形状不正确，你的可视化可能显示为空白或无法渲染。

Grafana 中的 SQL 表达式工作流程设计为具有以下行为：

未隐藏的查询会自动可视化。如果输入查询未隐藏，Grafana 将尝试与你的 SQL 表达式一起渲染它。这会使输出变得杂乱，尤其是在表格可视化中。
SQL 表达式结果可能不会立即可见。你可能需要使用数据帧选择器（表格面板底部的下拉菜单）在原始查询和 SQL 表达式结果之间切换。
非表格或形状不正确的数据将不会在某些面板中渲染。诸如图形或 Gauge 之类的可视化需要结构正确的数据。格式不匹配将导致渲染问题或数据缺失。

要在 SQL 表达式中使用数据，数据必须采用表格格式，特别是 FullLong 格式。这意味着所有相关数据都包含在一个表中，其中指标标签等值存储为列和单个单元格。由于并非所有数据源默认都以这种格式返回结果，当在 SQL 表达式中引用兼容的查询结果时，Grafana 会自动将其转换为 FullLong 格式。

SQL 转换规则

当在 SQL 语句中引用 RefID（例如，SELECT * FROM A）时，系统会调用一个独特的 SQL 转换过程。

SQL 转换路径

查询结果被视为单个数据帧，没有标签，并直接映射到表格格式。
如果帧类型存在且是数值、宽时间序列或多帧时间序列（例如，带标签的格式），Grafana 会自动将数据转换为表格结构。

已知限制

目前，每个面板或警报仅支持一个 SQL 表达式。
Grafana 支持某些数据源。请参阅兼容的数据源以获取当前列表。

支持的数据源格式

Grafana 支持三种类型的数据源响应格式：

单一表格状帧:
这指的是以标准表格结构返回的数据，所有值都被组织成行和列，类似于从 SQL 查询获得的结果。
- 示例：针对 SQL 数据源（例如，PostgreSQL、MySQL）且格式设置为 Table 的任何查询。
Dataplane：时间序列格式:
此格式表示带有时间戳和关联值的时间序列数据。它通常从监控数据源返回。
- 示例：Prometheus 或 Loki Range Queries（返回一段时间内一组值的查询）。
Dataplane：数值 Long 格式:
此格式用于点时间（瞬时）指标查询，这些查询在特定时刻返回单个值（或一组值）。
- 示例：Prometheus 或 Loki Instant Queries（返回指标当前值的查询）。

有关 Dataplane 格式的更多信息，请参阅Grafana Dataplane 文档。

在 SQL 表达式中使用以下非表格格式时，它们会自动转换为表格格式 (FullLong)：

宽时间序列：标签键成为列名。
多帧时间序列：标签值成为每行中的值（如果缺少标签则为 null）。
数值宽：value 列包含数值指标值。
数值多：如果存在显示名称，它将出现在 display_name 列中。

转换期间

标签键成为列名。
标签值填充相应的行（如果缺少标签则为 null）。
value 列包含数值指标。
如果可用，display_name 列包含人类可读的名称。
metric_name 列存储原始指标标识符。
对于时间序列数据，Grafana 包含一个带有时间戳的 time 列。

SQL 表达式示例

创建以下 Prometheus 查询：
promql
```
sum(
  rate(go_cpu_classes_gc_total_cpu_seconds_total{namespace=~".*(namespace).*5."}[$__rate_interval])
) by (namespace)
```
面板显示 Go 垃圾回收 (GC) 随时间变化的 CPU 使用率，按命名空间细分。
添加 SQL 表达式 SELECT * from A。添加从 RefID A 中选择数据的 SQL 表达式后，Grafana 会将其转换为表格响应。