目录
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 标头，则此参数优先。 |
请求正文
| 条目 | 描述 |
|---|---|
| columnar | （可选，布尔值）如果为 true，则以列格式返回结果。默认为 false。API 仅支持 CBOR、JSON、SMILE 和 YAML 响应的此参数。请参阅列式结果。 |
| locale | （可选，字符串）返回按照语言环境惯例格式化的结果（尤其是日期）。有关语法，请参阅返回本地化结果。 |
| params | （可选，数组）查询中的参数值。有关语法，请参阅将参数传递给查询。 |
| query | （必需，字符串）要运行的 ES|QL 查询。有关语法，请参阅语法参考。 |
响应正文
| 条目 | 描述 |
|---|---|
|
| （对象数组）值中返回的每一列的列名和类型。每个对象都是一列。 |
| 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 参数设置的期限内未完成的异步查询，而不管此值是多少。 |
响应正文
该 API 返回与同步查询 API 相同的响应主体，以及以下属性：
| 条目 | 描述 |
|---|---|
| id | （字符串）查询的标识符。 仅当满足以下条件之一时才提供此查询 id：
你可以将此 ID 与 ES|QL 异步查询获取 API 一起使用，以获取查询的当前状态和可用结果。 |
| is_running | （布尔值）如果为真，则查询请求仍在执行。 |
ES|QL async query get API
返回 ES|QL 异步查询或存储结果的当前状态和可用结果。
GET /_query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=请求
GET /_query/async/<query_id>
前提条件
- 如果启用了 Elasticsearch 安全功能，则只有首先提交 ES|QL 查询的用户才能使用此 API 检索结果。
路径参数
| 条目 | 描述 |
|---|---|
| <query_id> | （必需，字符串）查询的标识符。 对于未在等待时间内完成的查询，ES|QL 异步查询 API 的响应中会提供查询 id。如果请求的 keep_on_completion 参数为 true，也会提供查询 ID。 |
查询参数
| 条目 | 描述 |
|---|---|
| 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/<query_id>
前提条件
- 如果启用了 Elasticsearch 安全功能，则只有以下用户可以使用此 API 删除查询：
- 提交原始查询请求的经过身份验证的用户
- 具有 cancel_task 集群权限的用户
路径参数
| 条目 | 描述 |
|---|---|
| <query_id> | （必需，字符串）要删除的查询的标识符。 对于未在等待时间内完成的查询，ES|QL 异步查询 API 的响应中会提供查询 id。如果请求的 keep_on_completion 参数为 true，也会提供查询 ID。 |
)
