« ES|QL ES|QL 参考 »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›ES|QL

ES|QL 查询入门

编辑

ES|QL 查询入门编辑

本指南介绍如何使用 ES|QL 查询和聚合数据。

本入门指南还可以在 elasticsearch-labs GitHub 存储库中以交互式 Python 笔记本的形式获取。

先决条件编辑

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

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

response = client.indices.create(
  index: 'sample_data',
  body: {
    mappings: {
      properties: {
        client_ip: {
          type: 'ip'
        },
        message: {
          type: 'keyword'
        }
      }
    }
  }
)
puts response

response = client.bulk(
  index: 'sample_data',
  body: [
    {
      index: {}
    },
    {
      "@timestamp": '2023-10-23T12:15:03.360Z',
      client_ip: '172.21.2.162',
      message: 'Connected to 10.1.0.3',
      event_duration: 3_450_233
    },
    {
      index: {}
    },
    {
      "@timestamp": '2023-10-23T12:27:28.948Z',
      client_ip: '172.21.2.113',
      message: 'Connected to 10.1.0.2',
      event_duration: 2_764_889
    },
    {
      index: {}
    },
    {
      "@timestamp": '2023-10-23T13:33:34.937Z',
      client_ip: '172.21.0.5',
      message: 'Disconnected',
      event_duration: 1_232_382
    },
    {
      index: {}
    },
    {
      "@timestamp": '2023-10-23T13:51:54.732Z',
      client_ip: '172.21.3.15',
      message: 'Connection error',
      event_duration: 725_448
    },
    {
      index: {}
    },
    {
      "@timestamp": '2023-10-23T13:52:55.015Z',
      client_ip: '172.21.3.15',
      message: 'Connection error',
      event_duration: 8_268_153
    },
    {
      index: {}
    },
    {
      "@timestamp": '2023-10-23T13:53:55.832Z',
      client_ip: '172.21.3.15',
      message: 'Connection error',
      event_duration: 5_033_755
    },
    {
      index: {}
    },
    {
      "@timestamp": '2023-10-23T13:55:01.543Z',
      client_ip: '172.21.3.15',
      message: 'Connected to 10.1.0.1',
      event_duration: 1_756_467
    }
  ]
)
puts response
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 查询编辑

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

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

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

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

  """
}

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

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

您的第一个 ES|QL 查询编辑

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

A source command producing a table from Elasticsearch

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 ... 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

访问列编辑

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

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

丰富数据编辑

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

esql enrich

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

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

response = client.indices.create(
  index: 'clientips',
  body: {
    mappings: {
      properties: {
        client_ip: {
          type: 'keyword'
        },
        env: {
          type: 'keyword'
        }
      }
    }
  }
)
puts response

response = client.bulk(
  index: 'clientips',
  body: [
    {
      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'
    }
  ]
)
puts response

response = client.enrich.put_policy(
  name: 'clientip_policy',
  body: {
    match: {
      indices: 'clientips',
      match_field: 'client_ip',
      enrich_fields: [
        'env'
      ]
    }
  }
)
puts response

response = client.enrich.execute_policy(
  name: 'clientip_policy',
  wait_for_completion: false
)
puts response
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 进行数据丰富的更多信息，请参阅 数据丰富。

处理数据编辑

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

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

« ES|QL ES|QL 参考 »