查询构建器
所有查询都可以使用 ClickHouse 插件运行。查询构建器是用于简单查询的便捷选项，但对于复杂的查询，您需要使用 SQL 编辑器。
查询构建器中的所有查询都有一个 查询类型，并且至少需要选择一列。
可用的查询类型是
- 表格：用于以表格格式显示数据的最简单的查询类型。对于包含聚合函数的简单和复杂查询来说，这是一个很好的选择。
- 日志：针对日志查询构建进行优化。在探索视图中使用 配置的默认值 时效果最佳。
- 时间序列：最适合用于构建时间序列查询。允许选择专用的时间列并添加聚合函数。
- 跟踪：针对搜索/查看跟踪进行优化。在探索视图中使用 配置的默认值 时效果最佳。
- SQL 编辑器：当您需要完全控制查询时，可以使用 SQL 编辑器。在此模式下，可以执行任何 SQL 查询。
查询类型
查询类型 设置将更改查询构建器的布局，以匹配要构建的查询类型。查询类型还决定了在可视化数据时使用哪个面板。
表格
最灵活的查询类型是表格查询。这是其他查询构建器的通用选项，旨在处理简单和聚合查询。
| 字段 | 描述 |
|---|---|
| 构建器模式 | 简单查询不包含聚合和分组，而聚合查询包含这些选项。 |
| 列 | 选定的列。可以在此字段中键入原始 SQL，以允许函数和列别名。 |
| 聚合 | 一个 聚合函数 列表。允许为函数和列设置自定义值。仅在聚合模式下可见。 |
| 分组依据 | 一个 GROUP BY 表达式列表。仅在聚合模式下可见。 |
| 排序依据 | 一个 ORDER BY 表达式列表。 |
| 限制 | 将一个 LIMIT 语句附加到查询的末尾。如果设置为 0，则它将被排除。某些可视化可能需要将其设置为 0 以显示所有数据。 |
| 过滤器 | 要在 WHERE 子句中应用的过滤器列表。 |
此查询类型将以表格形式呈现数据。
日志
日志查询类型提供了一个专注于查询日志数据的查询构建器。可以在数据源的 日志配置 中配置默认值，以允许查询构建器预先加载默认数据库/表和列。还可以启用 OpenTelemetry，以便根据架构版本自动选择列。
默认情况下，添加了时间和级别过滤器，以及时间列的排序依据。这些过滤器与它们各自的字段相关联，并将随着列的更改而更新。默认情况下，级别过滤器会从 SQL 中排除，将其从 IS ANYTHING 选项更改为其他选项将启用它。
日志查询类型支持 数据链接。
| 字段 | 描述 |
|---|---|
| 使用 OTel | 启用 OpenTelemetry 列。将覆盖选定的列，以使用选定的 OTel 架构版本定义的列（禁用列选择）。 |
| 列 | 要添加到日志行的额外列。可以在此字段中键入原始 SQL，以允许函数和列别名。 |
| 时间 | 日志的主要时间戳列。将显示时间类型的列，但允许使用自定义值/函数。 |
| 日志级别 | 可选。日志的级别或严重程度。值通常类似于 INFO、error、Debug 等。 |
| 消息 | 日志消息内容。 |
| 排序依据 | 一个 ORDER BY 表达式列表。 |
| 限制 | 将一个 LIMIT 语句附加到查询的末尾。如果设置为 0，则它将被排除，但不建议针对大型日志数据集执行此操作。 |
| 过滤器 | 要在 WHERE 子句中应用的过滤器列表。 |
| 消息过滤器 | 一个文本输入，用于使用 LIKE %value% 方便地过滤日志。在输入为空时排除。 |
此查询类型将使用日志面板呈现数据，并在顶部使用日志直方图面板。
在查询中选定的额外列可以在扩展的日志行中查看。
时间序列
时间序列查询类型类似于 表格，但侧重于时间序列数据。
这两个视图基本相同，但有以下显著区别
- 一个专用的时间字段。
- 在聚合模式下，会自动应用时间间隔宏，以及时间字段的分组依据。
- 在聚合模式下，“列”字段将被隐藏。
- 会自动为时间字段添加时间范围过滤器和排序依据。
在某些情况下，时间序列面板似乎被截断，因为限制默认设置为 1000。
尝试通过将其设置为 0 来删除 LIMIT 子句（如果您的数据集允许）。
| 字段 | 描述 |
|---|---|
| 构建器模式 | 简单查询不包含聚合和分组，而聚合查询包含这些选项。 |
| 时间 | 查询的主要时间列。将显示时间类型的列，但允许使用自定义值/函数。 |
| 列 | 选定的列。可以在此字段中键入原始 SQL，以允许函数和列别名。仅在简单模式下可见。 |
| 聚合 | 一个 聚合函数 列表。允许为函数和列设置自定义值。仅在聚合模式下可见。 |
| 分组依据 | 一个 GROUP BY 表达式列表。仅在聚合模式下可见。 |
| 排序依据 | 一个 ORDER BY 表达式列表。 |
| 限制 | 将一个 LIMIT 语句附加到查询的末尾。如果设置为 0，则它将被排除，建议针对某些时间序列数据集执行此操作，以便显示完整可视化。 |
| 过滤器 | 要在 WHERE 子句中应用的过滤器列表。 |
此查询类型将使用时间序列面板呈现数据。
跟踪
跟踪查询类型提供了一个用于轻松搜索和查看跟踪的查询构建器。它专为 OpenTelemetry 数据设计，但可以选择列来呈现来自不同架构的跟踪。可以在数据源的 跟踪配置 中配置默认值，以允许查询构建器预先加载默认数据库/表和列。如果配置了默认值，则默认情况下会折叠列选择。还可以启用 OpenTelemetry，以便根据架构版本自动选择列。
默认过滤器已添加，目的是仅显示顶级跨度。还包括时间列和持续时间时间列的排序依据。这些过滤器与它们各自的字段相关联，并将随着列的更改而更新。默认情况下，服务名称过滤器会从 SQL 中排除，将其从 IS ANYTHING 选项更改为其他选项将启用它。
跟踪查询类型支持 数据链接。
| 字段 | 描述 |
|---|---|
| 跟踪模式 | 将查询从跟踪搜索更改为跟踪 ID 查找。 |
| 使用 OTel | 启用 OpenTelemetry 列。将覆盖选定的列，以使用选定的 OTel 架构版本定义的列（禁用列选择）。 |
| 跟踪 ID 列 | 跟踪的 ID。 |
| 跨度 ID 列 | 跨度 ID。 |
| 父跨度 ID 列 | 父跨度 ID。这通常对于顶级跟踪为空。 |
| 服务名称列 | 服务名称。 |
| 操作名称列 | 操作名称。 |
| 开始时间列 | 跟踪跨度的主要时间列。跨度开始的时间。 |
| 持续时间时间列 | 跨度的持续时间。默认情况下，Grafana 预计这是一个以毫秒为单位的浮点数。会通过 持续时间单位 下拉列表自动应用转换。 |
| 持续时间单位 | 用于持续时间的单位时间。默认情况下为纳秒。选定的单位将转换为以毫秒为单位的浮点数，这是 Grafana 所需的。 |
| 标签列 | 跨度标签。如果未使用基于 OTel 的架构，请排除此项，因为它需要特定的 Map 列类型。 |
| 服务标签列 | 服务标签。如果未使用基于 OTel 的架构，请排除此项，因为它需要特定的 Map 列类型。 |
| 排序依据 | 一个 ORDER BY 表达式列表。 |
| 限制 | 在查询末尾追加 LIMIT 语句。如果设置为 0，则将其排除，但不建议对大型跟踪数据集这样做。 |
| 过滤器 | 要在 WHERE 子句中应用的过滤器列表。 |
| 跟踪 ID | 要过滤的跟踪 ID。仅在跟踪 ID 模式下使用，以及在打开跟踪 ID 数据链接 时。 |
此查询类型将以跟踪搜索模式下的表格视图和跟踪 ID 模式下的跟踪面板显示数据。
SQL 编辑器
对于过于复杂的查询构建器查询，可以使用 SQL 编辑器。这允许您通过编写和运行纯 ClickHouse SQL 来完全控制查询。
可以通过在查询编辑器顶部选择“SQL 编辑器”来打开 SQL 编辑器。
宏函数 仍然可以在此模式下使用。
您可以切换查询类型，以获得最适合您的查询的可视化效果。即使在仪表板视图中，此切换也会产生影响，尤其是在时间序列数据中。
数据链接
Grafana 数据链接 可用于链接到新的查询。此功能已在 ClickHouse 插件中启用，用于将跟踪链接到日志，反之亦然。它在 数据源配置 中为日志和跟踪都配置了 OpenTelemetry 时效果最佳。
如何创建数据链接
您可以通过在查询中选择名为 traceID 的列来创建数据链接。此名称不区分大小写，并支持在“ID”之前添加下划线。例如：traceId、TraceId、TRACE_ID 和 tracE_iD 都是有效的。
如果在 日志 或 跟踪 查询中启用了 OpenTelemetry，则将自动包含跟踪 ID 列。
通过包含跟踪 ID 列，“查看跟踪”和“查看日志”链接将附加到数据。
链接功能
有了数据链接，您可以使用提供的跟踪 ID 打开跟踪和日志。
“查看跟踪”将打开一个带有跟踪的拆分面板，而“查看日志”将打开一个按跟踪 ID 过滤的日志查询。如果从仪表板而不是探索视图中单击链接，则该链接将在探索视图的新选项卡中打开。
在跨查询类型（日志到跟踪和跟踪到日志）时，需要为 日志 和 跟踪 都配置默认值。在打开相同查询类型的链接时，不需要默认值，因为查询可以简单地复制。
宏
宏是一种向查询添加动态 SQL 的简单方法。在将查询发送到 ClickHouse 服务器之前，插件会扩展宏并将其替换为完整表达式。
来自 SQL 编辑器和查询构建器的查询都可以使用宏。
使用宏
宏可以包含在查询中的任何位置，根据需要多次包含。
以下是如何使用 $__timeFilter 宏的示例
输入
SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)
最终查询输出
SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)
在此示例中，Grafana 仪表板的时间范围将应用于 log_time 列。
插件还支持使用大括号 {} 的符号。当在 参数 内需要查询时，请使用此符号。
宏列表
这是插件中所有可用宏的列表
| 宏 | 描述 | 输出示例 |
|---|---|---|
$__dateFilter(columnName) | 使用 Grafana 面板的时间范围作为 日期，替换为对提供的列的时间范围过滤器。 | columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23') |
$__timeFilter(columnName) | 使用 Grafana 面板的时间范围作为 日期时间，替换为对提供的列的时间范围过滤器。 | columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726) |
$__timeFilter_ms(columnName) | 使用 Grafana 面板的时间范围作为 日期时间64，替换为对提供的列的时间范围过滤器。 | columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456) |
$__dateTimeFilter(dateColumn, timeColumn) | 使用单独的日期和日期时间列，组合 $__dateFilter() 和 $__timeFilter() 的简写。别名 $__dt() | $__dateFilter(dateColumn) AND $__timeFilter(timeColumn) |
$__fromTime | 替换为 Grafana 面板范围的开始时间，转换为 日期时间。 | toDateTime(1415792726) |
$__fromTime_ms | 替换为面板范围的开始时间，转换为 日期时间64。 | fromUnixTimestamp64Milli(1415792726123) |
$__toTime | 替换为 Grafana 面板范围的结束时间，转换为 日期时间。 | toDateTime(1447328726) |
$__toTime_ms | 替换为面板范围的结束时间，转换为 日期时间64。 | fromUnixTimestamp64Milli(1447328726456) |
$__timeInterval(columnName) | 替换为根据窗口大小（以秒为单位）计算间隔的函数。 | toStartOfInterval(toDateTime(columnName), INTERVAL 20 second) |
$__timeInterval_ms(columnName) | 替换为根据窗口大小（以毫秒为单位）计算间隔的函数。 | toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond) |
$__interval_s | 替换为仪表板间隔（以秒为单位）。 | 20 |
$__conditionalAll(condition, $templateVar) | 当第二个参数中的模板变量未选择所有值时，替换为第一个参数。当模板变量选择所有值时，替换为 1=1。 | condition 或 1=1 |