Elasticsearch：ES|QL 同步及 async 查询操作-个人在线分享

ES|QL query API

请求

前提条件

查询参数

请求正文

响应正文

ES|Q async query API

请求

前提条件

路径参数

请求正文

响应正文

ES|QL async query get API

请求

前提条件

路径参数

查询参数

响应正文

ES|QL async query delete API

请求

前提条件

路径参数

Elasticsearch 查询语言 (ES|QL) 提供了一种强大的方法来过滤、转换和分析存储在 Elasticsearch 中以及将来在其他运行时中的数据。有关 ES|QL 和相关教程的概述，请参阅 ES|QL。在今天的文章中，我们将介绍 ES|QL 的同步及异步操作。

ES|QL query API

和下面的异步请求相对应，以示区别，这个请求也称作为 ES|QL 的同步请求。

例子：

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

返回 ES|QL（Elasticsearch 查询语言）查询的搜索结果。更多例子请在文章 “Elasticsearch：ES|QL 查询展示” 中进行查看。

请求

POST _query

前提条件

如果启用了 Elasticsearch 安全功能，你必须具有所搜索的数据流、索引或别名的读取（read）索引权限。

查询参数

条目	描述
delimiter	（可选，字符串）CSV 结果的分隔符。默认为 ,。针对 CSV 响应，API 仅支持此参数。
drop_null_columns	（可选，布尔值）是否应从结果的列和值部分中删除完全为空的列？默认为 false。如果为 true，则响应将包含一个名为 all_columns 的额外部分，其中包含所有列的名称。
format	（可选，字符串）响应的格式。有关有效值，请参阅响应格式。你还可以使用 Accept HTTP 标头指定格式。如果您同时指定此参数和 Accept HTTP 标头，则此参数优先。

条目

描述

delimiter

（可选，字符串）CSV 结果的分隔符。默认为 ,。针对 CSV 响应，API 仅支持此参数。

drop_null_columns

（可选，布尔值）是否应从结果的列和值部分中删除完全为空的列？默认为 false。如果为 true，则响应将包含一个名为 all_columns 的额外部分，其中包含所有列的名称。

format

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

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

请求正文

条目	描述
columnar	（可选，布尔值）如果为 true，则以列格式返回结果。默认为 false。API 仅支持 CBOR、JSON、SMILE 和 YAML 响应的此参数。请参阅列式结果。
locale	（可选，字符串）返回按照语言环境惯例格式化的结果（尤其是日期）。有关语法，请参阅返回本地化结果。
params	（可选，数组）查询中的参数值。有关语法，请参阅将参数传递给查询。
query	（必需，字符串）要运行的 ES\|QL 查询。有关语法，请参阅语法参考。

响应正文

条目	描述
`columns`	（对象数组）值中返回的每一列的列名和类型。每个对象都是一列。
all_columns	（对象数组）每个查询列的列名和类型。每个对象都是一个单独的列。仅当 drop_null_columns 与请求一起发送时才会返回。
rows	（数组的数组）搜索结果的值。

ES|Q async query API

用于返回异步 ES|QL 查询

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

该 API 接受与同步查询 API （也就是上面描述的 ES|QL query 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": ...
}

请求

POST /_query/async

前提条件

如果启用了 Elasticsearch 安全功能，你必须具有所搜索的数据流、索引或别名的读取（read）索引权限。

路径参数

该 API 接受与同步查询 API 相同的参数。和上面描述 ES|QL query API 中描述的一样。

请求正文

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

条目	描述
wait_for_completion_timeout	（可选，时间值）等待请求完成的超时时长。默认为 1 秒，表示请求等待 1 秒以获取查询结果。如果查询在此期间完成，则将返回结果。否则，将返回查询 id，稍后可用于检索结果。如果请求在此期间未完成，则返回查询 id (如下）。
keep_on_completion	（可选，布尔值）如果为 true，则查询及其结果将存储在集群中。如果为 false，则仅当请求在 wait_for_completion_timeout 参数设置的时间段内未完成时，查询及其结果才会存储在集群中。默认为 false。
keep_alive	（可选，时间值）查询及其结果在集群中存储的期限。默认为 5d（五天）。当此期限到期时，查询及其结果将被删除，即使查询仍在进行中。如果 keep_on_completion 参数为 false，Elasticsearch 仅存储在 wait_for_completion_timeout 参数设置的期限内未完成的异步查询，而不管此值是多少。

条目

描述

wait_for_completion_timeout

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

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

如果请求在此期间未完成，则返回查询 id (如下）。

keep_on_completion

（可选，布尔值）如果为 true，则查询及其结果将存储在集群中。

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

keep_alive

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

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

如果 keep_on_completion 参数为 false，Elasticsearch 仅存储在 wait_for_completion_timeout 参数设置的期限内未完成的异步查询，而不管此值是多少。

响应正文

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

条目	描述
id	（字符串）查询的标识符。仅当满足以下条件之一时才提供此查询 id：查询请求在 wait_for_completion_timeout 参数的超时期限内未返回完整结果。查询请求的 keep_on_completion 参数为 true。你可以将此 ID 与 ES\|QL 异步查询获取 API 一起使用，以获取查询的当前状态和可用结果。
is_running	（布尔值）如果为真，则查询请求仍在执行。

条目

描述

（字符串）查询的标识符。

仅当满足以下条件之一时才提供此查询 id：

查询请求在 wait_for_completion_timeout 参数的超时期限内未返回完整结果。
查询请求的 keep_on_completion 参数为 true。

你可以将此 ID 与 ES|QL 异步查询获取 API 一起使用，以获取查询的当前状态和可用结果。

is_running

（布尔值）如果为真，则查询请求仍在执行。

ES|QL async query get API

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

GET /_query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=

请求

GET /_query/async/

前提条件

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

路径参数

条目	描述
	（必需，字符串）查询的标识符。对于未在等待时间内完成的查询，ES\|QL 异步查询 API 的响应中会提供查询 id。如果请求的 keep_on_completion 参数为 true，也会提供查询 ID。

条目

描述

（必需，字符串）查询的标识符。

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

查询参数

条目	描述
wait_for_completion_timeout	（可选，时间值）等待请求完成的超时时长。默认为无超时，表示请求等待完整的查询结果。如果指定此参数并且请求在此期间完成，则返回完整的查询结果。如果请求在此期间未完成，则响应将返回 is_running 值 true 且无结果。

条目

描述

wait_for_completion_timeout

（可选，时间值）等待请求完成的超时时长。默认为无超时，表示请求等待完整的查询结果。

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

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

响应正文

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

ES|QL async query delete API

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

DELETE /query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=

请求

DELETE /_query/async/

前提条件

如果启用了 Elasticsearch 安全功能，则只有以下用户可以使用此 API 删除查询：
- 提交原始查询请求的经过身份验证的用户
- 具有 cancel_task 集群权限的用户

路径参数

条目	描述
	（必需，字符串）要删除的查询的标识符。对于未在等待时间内完成的查询，ES\|QL 异步查询 API 的响应中会提供查询 id。如果请求的 keep_on_completion 参数为 true，也会提供查询 ID。

条目

描述

（必需，字符串）要删除的查询的标识符。

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

一	二	三	四	五	六	日
						1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30

ES|QL query API

请求

前提条件

查询参数

请求正文

响应正文

ES|Q async query API

请求

前提条件

路径参数

请求正文

响应正文

ES|QL async query get API

请求

前提条件

路径参数

查询参数

响应正文

ES|QL async query delete API

请求

前提条件

路径参数

admin 钻石

相关推荐