作者：来自 Elastic Cauê Marcondes
现在，你可以通过 Elasticsearch 插件在 Grafana 中编写 ES|QL 查询。了解如何启用该功能，并直接在 Grafana 界面中编写基于管道（pipe）的查询。
通过以下方式亲身体验 Elasticsearch：深入探索 Elasticsearch Labs 仓库 中的示例 Notebooks，开始 免费云试用，或立即在你的 本地机器 上体验 Elastic。
Elasticsearch 数据源是 Grafana 生态系统中最受欢迎的插件之一，现在从 Grafana 13.0 开始，它新增了对 ES|QL 的实验性支持。ES|QL 是 Elasticsearch 现代化的基于管道（pipe）的查询语言，可用于查询日志、指标和追踪数据，并支持将 Elasticsearch 作为原生的 Prometheus PromQL 数据源，所有操作都可以直接在 Grafana 查询编辑器中完成。
该集成由 Elastic 与 Grafana Labs 合作开发，并贡献回 Grafana 开源项目 。只需启用一个功能开关（elasticsearchESQLQuery = true），即可启用基于 Monaco 编辑器的 ES|QL 查询体验，支持语法高亮、自动补全和内联错误提示。本文将介绍如何启用该功能，并编写你的第一个 ES|QL 查询，用于日志分析、时间序列可视化以及指标聚合。
背景
Elasticsearch 一直是 Grafana UI 中使用最广泛的插件之一。此前，Elasticsearch 插件仅支持 Lucene 和原始 Query DSL 查询。
ES|QL 是 Elastic 推出的现代化管道式查询语言，专为日志、指标和追踪数据分析而设计。相比 Query DSL 或 Lucene，其直观的语法使过滤、聚合和数据转换更加简单。
自 2024 年以来，这一直是社区持续提出的需求，详见：grafana/grafana#81765。
如何在 Grafana 中启用 ES|QL 支持
该功能由 elasticsearchESQLQuery 功能开关控制。要启用它，请将以下配置添加到你的 grafana.ini：
`
1. [feature_toggles]
2. elasticsearchESQLQuery = true
`AI写代码
保存配置后，重新启动 Grafana。该功能从 Grafana 13.0 开始提供。
Grafana 查询编辑器中的 ES|QL
启用该功能开关后，Elasticsearch 查询编辑器将新增一个 **查询语言（Query language）**选择器。你可以在同一个编辑器面板中，在 Lucene、Raw DSL 和 ES|QL 之间自由切换。
选择 ES|QL 后，编辑器会切换为基于 Monaco 的代码编辑器——与 VS Code 使用的是同一个编辑器引擎。你将开箱即用地获得语法高亮、错误高亮以及基础自动补全功能。
智能索引预填充（Smart index pre-population） 让你能够快速开始：如果数据源设置中配置了索引模式（index pattern），首次点击进入 ES|QL 编辑器时，会自动插入 FROM <index>。你可以自由修改或删除它。如果没有配置索引，则 FROM 子句会保持为空。
运行你的第一个查询
按严重级别统计日志条目数量
这是一个很好的入门查询，可以用来确认 ES|QL 已正常工作，同时帮助你熟悉其语法。
`
1. FROM logs*
2. | STATS count = COUNT(*) BY log.level
3. | SORT count DESC
`AI写代码
在 Raw Data（原始数据）面板类型中运行它，就可以看到按日志级别（log level）统计的表格结果。
浏览最新错误（Browse the latest errors）
WHERE、KEEP、SORT 和 LIMIT 让你可以轻松过滤出你真正关心的字段和行。
`
1. FROM logs
2. | WHERE log.level == "error"
3. | KEEP @timestamp, host.name, service.name, message
4. | SORT @timestamp DESC
5. | LIMIT 20
`AI写代码
日志随时间变化
使用 BUCKET 将日志数量按小时区间分组。这与 Metrics 面板类型配合效果很好，可以将其渲染为时间序列图。
`
1. FROM logs*
2. | STATS count = COUNT(*) BY bucket = BUCKET(@timestamp, 1 hour)
3. | SORT bucket ASC
`AI写代码
按日志活动统计的 Top hosts
识别最活跃的 hosts 是一个常见的运维任务。使用 STATS 搭配 BY 和 LIMIT 可以让它更简洁。
`
1. FROM logs*
2. | STATS log_count = COUNT(*) BY host.name
3. | SORT log_count DESC
4. | LIMIT 10
`AI写代码
TS 命令用于时间序列指标
对于 时间序列数据流（Time Series Data Streams，TSDS） 中的指标数据，ES|QL 的 TS 源命令可以实现指标分析与时间序列聚合。
示例：
RATE()：随时间变化的速率AVG_OVER_TIME()：在滑动窗口内的平均值INCREASE()：某个时间段内的总增长量DELTA()：首尾值之间的差值LAST_OVER_TIME()：窗口内的最新值
其模式遵循两层聚合：先对单个时间序列应用内部函数，再对结果进行外部聚合（例如按 host 或 service 分组）。
`
1. TS metrics*
2. | STATS SUM(RATE(metrics.system.cpu.time)) BY TBUCKET(10 m)
`AI写代码
你也可以使用 AVG_OVER_TIME()来计算一个 metric 在 sliding window 上的平均值，然后按 host 和 10-minute buckets 对结果进行拆分：
`
1. TS metrics*
2. | STATS MAX(AVG_OVER_TIME(metrics.system.memory.utilization)) BY host.name,TBUCKET(10m)
`AI写代码
TS 也会通过 ES|QL 向量化计算引擎执行查询。内部基准测试显示，相比在 TSDS 支持的数据上执行等价 Query DSL 查询，性能提升可达一个数量级或更高。
参考：
内联错误信息
ES|QL 查询通过 Elasticsearch 的 /_query HTTP 端点 执行。如果你的查询存在语法错误，或引用了不存在的字段，Elasticsearch 会返回结构化错误响应。插件会将其直接展示为查询编辑器中的内联提示，让你在 Grafana UI 中就能清楚看到问题所在。
在上面的示例中，host.nam 少了最后的 e。Elasticsearch 会将其识别为校验异常（verification exception），并返回无法解析的字段名称。该错误信息会以内联方式显示在查询编辑器中，就在查询下方。
技术细节
在底层实现中，该插件将 ES|QL 和其他查询类型分成不同的处理路径。ES|QL 查询会发送到 /_query 端点，并使用 Content-Type: application/json。Lucene 和 Query DSL 查询仍然使用 /_msearch，并采用 Content-Type: application/x-ndjson。
这种拆分是有意设计的：/_query 返回的是不同结构的响应，插件会独立解析该响应，然后再将数据传递给 Grafana 的面板。
试用一下！
这也意味着现在是一个很好的时机去尝试并提供反馈。
上游 PR（upstream PR）以及原始跟踪 issue （original tracking issue）都是公开的。如果你遇到问题或有需求，都可以在这些地方留言。
下一步
-
在你的 Grafana 13.0 实例中通过
elasticsearchESQLQuery = true启用该功能 -
在你自己的索引上尝试上面的示例查询
-
对于指标数据，可以在 Elasticsearch 9.2 或 Serverless 数据源上尝试 ES|QL 的
TS命令 -
阅读完整的 ES|QL 概览 以探索该语言的更多能力
如果你还没有使用 Elasticsearch，可以在 Elastic Cloud 上启动免费试用。
