« ES|QL ES|QL reference »
Elastic Docs ›Elasticsearch Guide ›ES|QL

开始使用ES|QL查询

edit

开始使用 ES|QL 查询

edit

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

本入门指南也可在 elasticsearch-labs GitHub 仓库中作为 交互式 Python 笔记本 使用。

先决条件

edit

要跟随本指南中的查询，您可以设置自己的部署，或使用Elastic的公共ES|QL演示环境。

首先导入一些示例数据。在 Kibana 中，打开主菜单并选择 开发工具。运行以下两个请求：

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}

运行一个ES|QL查询

edit

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

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

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

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

  """
}

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

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

你的第一个 ES|QL 查询

edit

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

A source command producing a table from Elasticsearch

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

FROM sample_data

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

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

from sample_data

处理命令

edit

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

A processing command changing an input table

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

FROM sample_data
| LIMIT 3

为了提高可读性，您可以将每个命令放在单独的行上。然而，您不必这样做。以下查询与前一个查询相同：

FROM sample_data | LIMIT 3

排序表格

edit
A processing command sorting an input table

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

FROM sample_data
| SORT @timestamp DESC

查询数据

edit

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

FROM sample_data
| WHERE event_duration > 5000000

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

FROM sample_data
| WHERE message LIKE "Connected*"

更多处理命令

edit

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

链式处理命令

edit

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

Processing commands can be chained

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

FROM sample_data
| SORT @timestamp DESC
| LIMIT 3

处理命令的顺序很重要。首先将结果集限制为3行，然后再对这3行进行排序，与本例中先排序再限制结果集相比，很可能会返回不同的结果。

计算值

edit

使用 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)

计算统计数据

edit

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

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

访问列

edit

您可以通过名称访问列。如果名称包含特殊字符，需要用反引号（`）括起来。

为通过 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`)

创建直方图

edit

为了随着时间的推移跟踪统计数据，ES|QL 使您能够使用 BUCKET 函数创建直方图。BUCKET 创建人类友好的桶大小，并为每一行返回一个值，该值对应于该行所属的结果桶。

结合 BUCKET 与 STATS ... BY 来创建直方图。例如，统计每小时的事件数量：

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")

丰富数据

edit

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

esql enrich

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

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

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

在创建并执行策略后，您可以使用 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 进行数据增强的更多信息，请参阅 数据增强。

处理数据

edit

您的数据可能包含您想要 结构化 以使其更易于 分析的数据。例如，示例数据包含如下日志消息：

"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 进行数据处理。

了解更多

edit

要了解更多关于 ES|QL 的信息，请参阅 ES|QL 参考 和 使用 ES|QL。

« ES|QL ES|QL reference »