ES|QL async query API
editES|QL async query API
editRuns 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.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" }
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
editPOST /_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.
Request body
editThe 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 thewait_for_completion_timeout
parameter. Defaults tofalse
. -
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 isfalse
, Elasticsearch only stores async queries that do not complete within the period set by thewait_for_completion_timeout
parameter, regardless of this value.
Response body
editThe 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:
-
A query request does not return complete results during the
wait_for_completion_timeout
parameter’s timeout period. -
The query request’s
keep_on_completion
parameter istrue
.
You can use this ID with the ES|QL async query get API to get the current status and available results for the query.
-
A query request does not return complete results during the
-
is_running
-
(Boolean) If
true
, the query request is still executing.