› › ›

ES|QL 异步查询 API

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

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

resp = client.esql.async_query(
    body={
        "query": "\n    FROM library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
        "wait_for_completion_timeout": "2s"
    },
)
print(resp)

const response = await client.esql.asyncQuery({
  body: {
    query:
      "\n    FROM library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    wait_for_completion_timeout: "2s",
  },
});
console.log(response);

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
值为 true 的 is_running，指示查询正在进行

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

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

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

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

请求

编辑

POST /_query/async

先决条件

编辑

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

路径参数

编辑

该 API 接受与同步查询 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

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

« ES|QL 查询 API ES|QL 异步查询获取 API »