Elasticsearch:ES|QL 同步及 async 查询操作

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。
相关推荐
晨欣3 小时前
Elasticsearch和Lucene之间是什么关系?(ChatGPT回答)
elasticsearch·chatgpt·lucene
筱源源9 小时前
Elasticsearch-linux环境部署
linux·elasticsearch
Elastic 中国社区官方博客20 小时前
释放专利力量:Patently 如何利用向量搜索和 NLP 简化协作
大数据·数据库·人工智能·elasticsearch·搜索引擎·自然语言处理
Shenqi Lotus1 天前
ELK-ELK基本概念_ElasticSearch的配置
elk·elasticsearch
yeye198912241 天前
10-Query & Filtering 与多字符串多字段查询
elasticsearch
Narutolxy1 天前
精准优化Elasticsearch:磁盘空间管理与性能提升技巧20241106
大数据·elasticsearch·jenkins
谢小涛2 天前
ES管理工具Cerebro 0.8.5 Windows版本安装及启动
elasticsearch·es·cerebro
LKID体2 天前
Elasticsearch核心概念
大数据·elasticsearch·搜索引擎
晨欣2 天前
Elasticsearch里的索引index是什么概念?(ChatGPT回答)
大数据·elasticsearch·jenkins
许苑向上2 天前
最详细【Elasticsearch】Elasticsearch Java API + Spring Boot集成 实战入门(基础篇)
java·数据库·spring boot·elasticsearch