查询构建器
任何查询都可以使用 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 以根据模式版本自动选择列（禁用列选择）。
添加默认过滤器旨在仅显示顶级 span。还包括时间和持续时间时间列的排序依据。这些过滤器与其各自的字段相关联，并将随着列的更改而更新。默认情况下，服务名称过滤器从 SQL 中排除，将其从 IS ANYTHING 选项更改将启用它。
追踪查询类型支持数据链接。
| 字段 | 描述 |
|---|---|
| 追踪模式 | 将查询从追踪搜索更改为追踪 ID 查找。 |
| 使用 OTel | 启用 OpenTelemetry 列。将覆盖选定的列，以使用所选 OTel 模式版本定义的列（禁用列选择）。 |
| 追踪 ID 列 | 追踪的 ID。 |
| Span ID 列 | Span ID。 |
| 父 Span ID 列 | 父 span ID。对于顶级追踪，这通常为空。 |
| 服务名称列 | 服务名称。 |
| 操作名称列 | 操作名称。 |
| 开始时间列 | 追踪 span 的主要时间列。span 开始的时间。 |
| 持续时间时间列 | span 的持续时间。默认情况下，Grafana 期望这是一个以毫秒为单位的浮点数。转换会通过“持续时间单位”下拉列表自动应用。 |
| 持续时间单位 | 用于持续时间的单位。默认为纳秒。选定的单位将转换为 Grafana 要求的以毫秒为单位的浮点数。 |
| 标签列 | Span 标签。如果未使用基于 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 面板的时间范围作为 Date，替换为提供的列上的时间范围过滤器。 | columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23') |
$__timeFilter(columnName) | 使用 Grafana 面板的时间范围作为 DateTime，替换为提供的列上的时间范围过滤器。 | columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726) |
$__timeFilter_ms(columnName) | 使用 Grafana 面板的时间范围作为 DateTime64，替换为提供的列上的时间范围过滤器。 | columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456) |
$__dateTimeFilter(dateColumn, timeColumn) | 结合 $__dateFilter() 和 $__timeFilter() 的简写，使用单独的 Date 和 DateTime 列。别名 $__dt() | $__dateFilter(dateColumn) AND $__timeFilter(timeColumn) |
$__fromTime | 替换为 Grafana 面板范围的开始时间，并强制转换为 DateTime。 | toDateTime(1415792726) |
$__fromTime_ms | 替换为面板范围的开始时间，并强制转换为 DateTime64。 | fromUnixTimestamp64Milli(1415792726123) |
$__toTime | 替换为 Grafana 面板范围的结束时间，并强制转换为 DateTime。 | toDateTime(1447328726) |
$__toTime_ms | 替换为面板范围的结束时间，并强制转换为 DateTime64。 | 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 |