加载中

ES|QL 查询入门

Elastic Stack Serverless

本指南展示了如何使用 ES|QL 查询和聚合您的数据。

提示

此入门指南也可以在 elasticsearch-labs GitHub 存储库中找到 交互式 Python 笔记本。

要按照本指南中的查询进行操作，您可以设置自己的部署，或者使用 Elastic 的公共 ES|QL 演示环境。

首先，摄取一些示例数据。在 Kibana 中，打开主菜单并选择 Dev Tools（开发工具）。运行以下两个请求

 PUT sample_data {
  "mappings": {
    "properties": {
      "client_ip": {
        "type": "ip"
      },
      "message": {
        "type": "keyword"
      }
    }
  }
}

PUT sample_data/_bulk
{"index": {}}
{"@timestamp": "2023-10-23T12:15:03.360Z", "client_ip": "172.21.2.162", "message": "Connected to 10.1.0.3", "event_duration": 3450233}
{"index": {}}
{"@timestamp": "2023-10-23T12:27:28.948Z", "client_ip": "172.21.2.113", "message": "Connected to 10.1.0.2", "event_duration": 2764889}
{"index": {}}
{"@timestamp": "2023-10-23T13:33:34.937Z", "client_ip": "172.21.0.5", "message": "Disconnected", "event_duration": 1232382}
{"index": {}}
{"@timestamp": "2023-10-23T13:51:54.732Z", "client_ip": "172.21.3.15", "message": "Connection error", "event_duration": 725448}
{"index": {}}
{"@timestamp": "2023-10-23T13:52:55.015Z", "client_ip": "172.21.3.15", "message": "Connection error", "event_duration": 8268153}
{"index": {}}
{"@timestamp": "2023-10-23T13:53:55.832Z", "client_ip": "172.21.3.15", "message": "Connection error", "event_duration": 5033755}
{"index": {}}
{"@timestamp": "2023-10-23T13:55:01.543Z", "client_ip": "172.21.3.15", "message": "Connected to 10.1.0.1", "event_duration": 1756467}

本指南中使用的数据集已预加载到 Elastic ES|QL 公共演示环境中。访问 ela.st/ql 即可开始使用。

在 Kibana 中，您可以使用控制台或 Discover 运行 ES|QL 查询

要在控制台中开始使用 ES|QL，请打开主菜单并选择 Dev Tools（开发工具）。

ES|QL 查询 API 请求的一般结构是

POST /_query?format=txt
{
  "query": """

  """
}

在两组三引号之间输入实际的 ES|QL 查询。例如

POST /_query?format=txt
{
  "query": """
FROM sample_data
  """
}

要在 Discover 中开始使用 ES|QL，请打开主菜单并选择 Discover。接下来，从应用程序菜单栏中选择 Try ES|QL（尝试 ES|QL）。

调整时间过滤器，使其包含示例数据中的时间戳（2023 年 10 月 23 日）。

切换到 ES|QL 模式后，查询栏会显示一个示例查询。您可以使用本入门指南中的查询替换此查询。

为了更轻松地编写查询，自动完成功能提供了可能的命令和函数的建议

esql kibana auto complete

您可以通过拖动编辑器的底部边框来调整编辑器的高度。

每个 ES|QL 查询都以源命令开头。 源命令生成一个表，通常包含来自 Elasticsearch 的数据。

A source command producing a table from {{es}}

FROM 源命令返回一个包含来自数据流、索引或别名的文档的表。 结果表中的每一行代表一个文档。 此查询从 sample_data 索引返回最多 1000 个文档

FROM sample_data

每列对应一个字段，可以通过该字段的名称访问。

提示

ES|QL 关键字不区分大小写。 以下查询与前一个查询相同

from sample_data

源命令后可以跟一个或多个处理命令，用管道字符分隔：|。 处理命令通过添加、删除或更改行和列来更改输入表。 处理命令可以执行过滤、投影、聚合等。

A processing command changing an input table

例如，您可以使用 LIMIT 命令来限制返回的行数，最多 10,000 行

FROM sample_data
| LIMIT 3
提示

为了便于阅读，您可以将每个命令放在单独的一行上。 但是，您不必这样做。 以下查询与前一个查询相同

FROM sample_data | LIMIT 3
A processing command sorting an input table

另一个处理命令是 SORT 命令。 默认情况下，FROM 返回的行没有定义的排序顺序。 使用 SORT 命令按一列或多列对行进行排序

FROM sample_data
| SORT @timestamp DESC

使用 WHERE 命令查询数据。 例如，要查找所有持续时间超过 5 毫秒的事件

FROM sample_data
| WHERE event_duration > 5000000

WHERE 支持多个 运算符。 例如，您可以使用 LIKE 对 message 列运行通配符查询

FROM sample_data
| WHERE message LIKE "Connected*"

还有许多其他处理命令，例如 KEEP 和 DROP（用于保留或删除列）、ENRICH（用于使用 Elasticsearch 中索引的数据丰富表）以及 DISSECT 和 GROK（用于处理数据）。 有关所有处理命令的概述，请参阅 处理命令。

您可以链接处理命令，用管道字符分隔：|。 每个处理命令都作用于前一个命令的输出表。 查询的结果是由最终处理命令生成的表。

Processing commands can be chained

以下示例首先按 @timestamp 对表进行排序，然后将结果集限制为 3 行

FROM sample_data
| SORT @timestamp DESC
| LIMIT 3
注意

处理命令的顺序很重要。 如果先将结果集限制为 3 行，然后再对这 3 行进行排序，则很可能会返回与此示例不同的结果，在此示例中，排序位于限制之前。

使用 EVAL 命令将具有计算值的新列附加到表。 例如，以下查询附加一个 duration_ms 列。 列中的值是通过将 event_duration 除以 1,000,000 来计算的。 换句话说：event_duration 从纳秒转换为毫秒。

FROM sample_data
| EVAL duration_ms = event_duration/1000000.0

EVAL 支持多个 函数。 例如，要将数字四舍五入到具有指定位数的最近数字，请使用 ROUND 函数

FROM sample_data
| EVAL duration_ms = ROUND(event_duration/1000000.0, 1)

ES|QL 不仅可用于查询数据，还可用于聚合数据。 使用 STATS 命令来计算统计信息。 例如，中位数持续时间

FROM sample_data
| STATS median_duration = MEDIAN(event_duration)

您可以使用一个命令计算多个统计信息

FROM sample_data
| STATS median_duration = MEDIAN(event_duration), max_duration = MAX(event_duration)

使用 BY 按一列或多列对计算出的统计信息进行分组。 例如，要计算每个客户端 IP 的中位数持续时间

FROM sample_data
| STATS median_duration = MEDIAN(event_duration) BY client_ip

您可以通过列名访问列。 如果名称包含特殊字符，则需要用反引号 (```) 引用它。

为 EVAL 或 STATS 创建的列分配显式名称是可选的。 如果您不提供名称，则新列名等于函数表达式。 例如

FROM sample_data
| EVAL event_duration/1000000.0

在此查询中，EVAL 添加了一个名为 event_duration/1000000.0 的新列。 因为其名称包含特殊字符，所以要访问此列，请用反引号引用它

FROM sample_data
| EVAL event_duration/1000000.0
| STATS MEDIAN(`event_duration/1000000.0`)

为了跟踪一段时间内的统计信息，ES|QL 使您能够使用 BUCKET 函数创建直方图。 BUCKET 创建用户友好的存储桶大小，并为每一行返回与该行所在的存储桶相对应的值。

将 BUCKET 与 STATS 结合使用可创建直方图。 例如，要计算每小时的事件数

FROM sample_data
| STATS c = COUNT(*) BY bucket = BUCKET(@timestamp, 24, "2023-10-23T00:00:00Z", "2023-10-23T23:59:59Z")

或者每小时的中位数持续时间

FROM sample_data
| KEEP @timestamp, event_duration
| STATS median_duration = MEDIAN(event_duration) BY bucket = BUCKET(@timestamp, 24, "2023-10-23T00:00:00Z", "2023-10-23T23:59:59Z")

ES|QL 使您能够使用 ENRICH 命令，使用 Elasticsearch 中索引的数据丰富表。

esql enrich

在使用 ENRICH 之前，您需要首先创建和执行一个丰富策略。

以下请求创建并执行一个名为 clientip_policy 的策略。 该策略将 IP 地址链接到环境（“Development”、“QA”或“Production”）

 PUT clientips {
  "mappings": {
    "properties": {
      "client_ip": {
        "type": "keyword"
      },
      "env": {
        "type": "keyword"
      }
    }
  }
}

PUT clientips/_bulk
{ "index" : {}}
{ "client_ip": "172.21.0.5", "env": "Development" }
{ "index" : {}}
{ "client_ip": "172.21.2.113", "env": "QA" }
{ "index" : {}}
{ "client_ip": "172.21.2.162", "env": "QA" }
{ "index" : {}}
{ "client_ip": "172.21.3.15", "env": "Production" }
{ "index" : {}}
{ "client_ip": "172.21.3.16", "env": "Production" }

PUT /_enrich/policy/clientip_policy
{
  "match": {
    "indices": "clientips",
    "match_field": "client_ip",
    "enrich_fields": ["env"]
  }
}

PUT /_enrich/policy/clientip_policy/_execute?wait_for_completion=false

在 ela.st/ql 的演示环境中，已经创建并执行了一个名为 clientip_policy 的丰富策略。 该策略将 IP 地址链接到环境（“Development”、“QA”或“Production”）。

创建并执行策略后，您可以将其与 ENRICH 命令一起使用

FROM sample_data
| KEEP @timestamp, client_ip, event_duration
| EVAL client_ip = TO_STRING(client_ip)
| ENRICH clientip_policy ON client_ip WITH env

您可以在后续命令中使用 ENRICH 命令添加的新 env 列。 例如，要计算每个环境的中位数持续时间

FROM sample_data
| KEEP @timestamp, client_ip, event_duration
| EVAL client_ip = TO_STRING(client_ip)
| ENRICH clientip_policy ON client_ip WITH env
| STATS median_duration = MEDIAN(event_duration) BY env

有关使用 ES|QL 进行数据丰富的更多信息，请参阅 数据丰富。

您的数据可能包含非结构化字符串，您希望对其进行结构化，以便更轻松地分析数据。 例如，示例数据包含如下日志消息

"Connected to 10.1.0.3"

通过从这些消息中提取 IP 地址，您可以确定哪个 IP 接受的客户端连接最多。

为了在查询时构建非结构化字符串，您可以使用 ES|QL 的 DISSECT 和 GROK 命令。DISSECT 通过使用基于分隔符的模式来分解字符串。GROK 的工作方式类似，但使用正则表达式。这使得 GROK 更加强大，但通常也更慢。

在这种情况下，不需要正则表达式，因为 message 非常简单： "Connected to "，后跟服务器 IP。要匹配此字符串，您可以使用以下 DISSECT 命令

FROM sample_data
| DISSECT message "Connected to %{server_ip}"

这会为那些 message 与此模式匹配的行添加一个 server_ip 列。对于其他行，server_ip 的值为 null。

您可以在后续命令中使用 DISSECT 命令添加的新 server_ip 列。例如，要确定每个服务器接受了多少连接

FROM sample_data
| WHERE STARTS_WITH(message, "Connected to")
| DISSECT message "Connected to %{server_ip}"
| STATS COUNT(*) BY server_ip

有关使用 ES|QL 进行数据处理的更多信息，请参阅 使用 DISSECT 和 GROK 进行数据处理。

要了解有关 ES|QL 的更多信息，请参阅 ES|QL 参考。

了解更多关于使用 ES|QL 进行搜索用例的信息

© . All rights reserved.