Elasticsearch 查询语言 (ES|QL) 提供了一种强大的方法来过滤、转换和分析存储在 Elasticsearch 中以及将来在其他运行时中的数据。有关 ES|QL 和相关教程的概述,请参阅 ES|QL。在今天的文章中,我们将介绍 ES|QL 的同步及异步操作。
ES|QL query API
和下面的异步请求相对应,以示区别,这个请求也称作为 ES|QL 的同步请求。
例子:
python
1. POST /_query
2. {
3. "query": """
4. FROM library
5. | EVAL year = DATE_TRUNC(1 YEARS, release_date)
6. | STATS MAX(page_count) BY year
7. | SORT year
8. | LIMIT 5
9. """
10. }
返回 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 查询。有关语法,请参阅语法参考。 |
响应正文
条目 | 描述 |
---|---|
columns |
(对象数组)值中返回的每一列的列名和类型。每个对象都是一列。 |
all_columns | (对象数组)每个查询列的列名和类型。每个对象都是一个单独的列。仅当 drop_null_columns 与请求一起发送时才会返回。 |
rows | (数组的数组)搜索结果的值。 |
ES|Q async query API
用于返回异步 ES|QL 查询
异步查询 API 允许你异步执行查询请求、监控其进度并在结果可用时检索结果。
该 API 接受与同步查询 API (也就是上面描述的 ES|QL query API)相同的参数和请求正文,以及如下所述的其他异步相关属性。
python
1. POST /_query/async
2. {
3. "query": """
4. FROM library
5. | EVAL year = DATE_TRUNC(1 YEARS, release_date)
6. | STATS MAX(page_count) BY year
7. | SORT year
8. | LIMIT 5
9. """,
10. "wait_for_completion_timeout": "2s"
11. }
如果在给定的超时期限(本例中为 2 秒)内未获得结果,则不会返回任何结果,而是返回包含以下内容的响应:
- 查询 ID
- is_running 值为 true,表示查询正在进行中
查询将继续在后台运行,而不会阻止其他请求。
json
1. {
2. "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
3. "is_running": true
4. }
否则,如果响应的 is_running 值为 false,则异步查询已完成并返回结果。
json
1. {
2. "is_running": false,
3. "columns": ...
4. }
请求
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: * 查询请求在 wait_for_completion_timeout 参数的超时期限内未返回完整结果。 * 查询请求的 keep_on_completion 参数为 true。 你可以将此 ID 与 ES|QL 异步查询获取 API 一起使用,以获取查询的当前状态和可用结果。 |
is_running | (布尔值)如果为真,则查询请求仍在执行。 |
ES|QL async query get API
返回 ES|QL 异步查询或存储结果的当前状态和可用结果。
vbnet
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 手动删除异步查询。如果查询仍在运行,则查询将被取消。否则,将删除存储的结果。
bash
DELETE /query/async/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=
请求
DELETE /_query/async/<query_id>
前提条件
- 如果启用了 Elasticsearch 安全功能,则只有以下用户可以使用此 API 删除查询:
- 提交原始查询请求的经过身份验证的用户
- 具有 cancel_task 集群权限的用户
路径参数
条目 | 描述 |
---|---|
<query_id> | (必需,字符串)要删除的查询的标识符。 对于未在等待时间内完成的查询,ES|QL 异步查询 API 的响应中会提供查询 id。如果请求的 keep_on_completion 参数为 true,也会提供查询 ID。 |