IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« ES|QL query API ES|QL async query get API »
Elastic Docs ›Elasticsearch Guide [8.16] ›REST APIs ›ES|QL APIs

ES|QL async query API

edit

ES|QL async query API

edit

Runs an async ES|QL query.

The async query API lets you asynchronously execute a query request, monitor its progress, and retrieve results when they become available.

The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties as outlined below.

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.transport.request({
  method: "POST",
  path: "/_query/async",
  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"
}

If the results are not available within the given timeout period, 2 seconds in this case, no results are returned but rather a response that includes:

  • A query ID
  • An is_running value of true, indicating the query is ongoing

The query continues to run in the background without blocking other requests.

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

Otherwise, if the response’s is_running value is false, the async query has finished and the results are returned.

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

Request

edit

POST /_query/async

Prerequisites

edit
  • If the Elasticsearch security features are enabled, you must have the read index privilege for the data stream, index, or alias you query.

Path parameters

edit

The API accepts the same parameters as the synchronous query API.

Request body

edit

The API accepts the same request body as the synchronous query API, along with the following parameters:

wait_for_completion_timeout

(Optional, time value) Timeout duration to wait for the request to finish. Defaults to a 1 second, meaning the request waits for 1 second for the query results.

If the query completes during this period then results will be returned. Otherwise, a query id is returned that can later be used to retrieve the results.

If the request does not complete during this period, a query id is returned.

keep_on_completion

(Optional, Boolean) If true, the query and its results are stored in the cluster.

If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the wait_for_completion_timeout parameter. Defaults to false.

keep_alive

(Optional, time value) Period for which the query and its results are stored in the cluster. Defaults to 5d (five days).

When this period expires, the query and its results are deleted, even if the query is still ongoing.

If the keep_on_completion parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the wait_for_completion_timeout parameter, regardless of this value.

Response body

edit

The API returns the same response body as the synchronous query API, along with the following properties:

id

(string) Identifier for the query.

This query ID is only provided if one of the following conditions is met:

You can use this ID with the ES|QL async query get API to get the current status and available results for the query.

is_running

(Boolean) If true, the query request is still executing.

« ES|QL query API ES|QL async query get API »