« EQL APIs Features APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

ES|QL API

edit

ES|QL API

edit

Elasticsearch 查询语言（ES|QL）提供了一种强大的方式来过滤、转换和分析存储在 Elasticsearch 中的数据，以及未来在其他运行时中的数据。有关 ES|QL 的概述和相关教程，请参阅 ES|QL。

ES|QL 查询 API

edit

返回 ES|QL (Elasticsearch 查询语言) 查询的搜索结果。

POST /_query
{
  "query": """
    FROM library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """
}

请求

edit

POST _query

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须对您搜索的数据流、索引或别名具有read 索引权限。

查询参数

edit
delimiter
(可选，字符串) CSV结果的分隔符。默认为,。该API仅支持CSV响应的此参数。
drop_null_columns
(可选, 布尔值) 是否应从结果的 columns 和 values 部分中移除完全为 null 的列？默认为 false。如果为 true，则响应将包括一个名为 all_columns 的额外部分，其中包含所有列的名称。
format

(可选，字符串) 响应的格式。有关有效值，请参阅 响应格式。

您还可以使用Accept HTTP头指定格式。如果您同时指定此参数和Accept HTTP头，此参数优先。

请求体

edit
columnar
(可选，布尔值) 如果为 true，则以列格式返回结果。默认为 false。该 API 仅支持在 CBOR、JSON、SMILE 和 YAML 响应中使用此参数。请参阅 列结果。
include_ccs_metadata
(可选，布尔值) 如果为 true，跨集群搜索将包括每个集群上查询的元数据。默认为 false。该 API 仅支持 CBOR、JSON、SMILE 和 YAML 响应的此参数。请参阅 跨集群元数据。
locale
(可选，字符串) 返回根据区域设置约定格式化的结果（特别是日期）。 有关语法，请参阅 返回本地化结果。
params
(可选, 数组) query 中参数的值。有关语法，请参阅 将参数传递给查询。
profile
(可选, 布尔值) 如果提供并且为true，响应将包含一个额外的profile对象，其中包含有关查询如何执行的信息。它提供了对查询每个部分的性能的洞察。这是用于人类调试的，因为对象的格式可能会随时更改。可以将其视为EXPLAIN ANALYZE或EXPLAIN PLAN。
query
(必需，字符串) 要运行的 ES|QL 查询。有关语法，请参阅 语法参考。
table
(可选，对象) 命名为 "table" 的参数，可以被 LOOKUP 命令引用。

响应体

edit
columns
(对象数组) 返回的values中每个列的name和type。每个对象代表一个单独的列。
all_columns
(对象数组) 每个查询列的名称和类型。每个对象代表一个单独的列。仅当请求中发送了drop_null_columns时，才会返回此内容。
values
(数组数组) 搜索结果的值。
_clusters
(对象) 关于参与跨集群查询执行的集群的元数据。仅在以下情况下返回：(1) 对于跨集群搜索，(2) 当在请求体中发送 include_ccs_metadata 并设置为 true，以及 (3) 当响应的 format 设置为 JSON（默认）、CBOR、SMILE 或 YAML 时。有关更多信息，请参阅 跨集群元数据。
profile
(对象) 描述查询执行情况的配置文件。仅当在请求体中发送了profile时才会返回。 该对象本身用于人类调试，并且可能随时更改。可以将其视为 EXPLAIN ANALYZE 或 EXPLAIN PLAN。

ES|QL 异步查询 API

edit

运行一个异步的 ES|QL 查询。

异步查询API允许您异步执行查询请求，监控其进度，并在结果可用时检索结果。

该API接受与同步 查询API相同的参数和请求体，以及下面概述的与异步相关的附加属性。

POST /_query/async
{
  "query": """
    FROM library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s"
}

如果在给定的超时时间内（在此情况下为2秒）结果不可用，则不会返回结果，而是返回一个包含以下内容的响应：

  • 一个查询ID
  • 一个is_running值为true，表示查询正在进行中

查询继续在后台运行，不会阻塞其他请求。

{
  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running": true
}

否则，如果响应的 is_running 值为 false，异步查询已完成，结果将被返回。

{
  "is_running": false,
  "columns": ...
}

请求

edit

POST /_query/async

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须对您查询的数据流、索引或别名具有read 索引权限。

路径参数

edit

该API接受与同步的查询API相同的参数。

请求体

edit

该API接受与同步 查询API相同的请求体，以及以下 参数：

wait_for_completion_timeout

(可选，时间值) 等待请求完成的时间。默认为1秒，表示请求等待1秒以获取查询结果。

如果查询在此期间完成，则将返回结果。否则，将返回一个查询 id，该 ID 可以在以后用于检索结果。

如果请求在此期间未完成，将返回一个查询 id。

keep_on_completion

(可选, 布尔值) 如果true，查询及其结果将存储在集群中。

如果为false，则仅当请求在由 wait_for_completion_timeout 参数设置的期间内未完成时，查询及其结果才会存储在集群中。默认为false。

keep_alive

(可选, 时间值) 查询及其结果在集群中存储的周期。默认为5d（五天）。

当此期限到期时，查询及其结果将被删除，即使查询仍在进行中。

如果keep_on_completion参数为false，Elasticsearch仅存储在wait_for_completion_timeout参数设置的时间内未完成的异步查询，无论此值如何。

响应体

edit

API返回与同步的查询API相同的响应体，以及以下属性：

id

(字符串) 查询的标识符。

仅当满足以下任一条件时，才会提供此查询 ID：

您可以使用此ID与ES|QL async query get API来获取查询的当前状态和可用结果。

is_running

(布尔值) 如果true，查询请求仍在执行中。

ES|QL 异步查询获取 API

edit

返回当前状态和可用的结果，适用于ES|QL 异步查询或存储的结果。

GET /_query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=

请求

edit

GET /_query/async/

先决条件

edit
  • 如果启用了Elasticsearch安全功能，只有最初提交ES|QL查询的用户才能使用此API检索结果。

路径参数

edit
<query_id>

(必需, 字符串) 查询的标识符。

在 ES|QL async query API 的响应中，会提供一个查询 ID，用于在等待时间内未完成的查询。如果请求的 keep_on_completion 参数为 true，也会提供一个查询 ID。

查询参数

edit
wait_for_completion_timeout

(可选, 时间值) 等待请求完成的时间限制。默认为无超时，意味着请求会等待完整的查询结果。

如果指定了此参数，并且在此时段内请求完成，则返回完整的查询结果。

如果请求在此期间未完成，响应将返回一个is_running值为true且无结果。

响应体

edit

ES|QL 异步查询获取 API 返回与 ES|QL 查询 API 相同的响应体。请参阅 ES|QL 查询 API 的 响应体参数。

ES|QL 异步查询删除 API

edit

ES|QL 异步查询删除 API 用于通过 ID 手动删除异步查询。如果查询仍在运行，则查询将被取消。否则，存储的结果将被删除。

DELETE /query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=

请求

edit

DELETE /_query/async/

前提条件

edit

  • 如果启用了Elasticsearch安全功能，只有以下用户可以使用此API删除查询：

    • 提交原始查询请求的经过身份验证的用户
    • 拥有cancel_task 集群权限的用户

路径参数

edit
<query_id>

(必需, 字符串) 用于删除查询的标识符。

在 ES|QL async query API 的响应中，会提供一个查询 ID，用于在等待时间内未完成的查询。如果请求的 keep_on_completion 参数为 true，也会提供一个查询 ID。

« EQL APIs Features APIs »