mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
71b276da90
Docs for https://github.com/elastic/elasticsearch/pull/106824. Does not cover the [REST API specs](https://github.com/elastic/elasticsearch/blob/main/rest-api-spec/src/main/resources/rest-api-spec/api/esql.query.json) as these don't cover the request body.
167 lines
4.6 KiB
Text
167 lines
4.6 KiB
Text
[[esql-async-query-api]]
|
|
=== {esql} async query API
|
|
++++
|
|
<titleabbrev>{esql} async query API</titleabbrev>
|
|
++++
|
|
|
|
Runs an async <<esql,{esql} 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
|
|
<<esql-query-api,query API>>, along with additional async related
|
|
properties as outlined below.
|
|
|
|
[source,console]
|
|
----
|
|
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",
|
|
"version": "2024.04.01"
|
|
}
|
|
----
|
|
// TEST[setup:library]
|
|
// TEST[skip:awaitsfix https://github.com/elastic/elasticsearch/issues/104013]
|
|
|
|
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.
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
|
|
"is_running": true
|
|
}
|
|
----
|
|
// TEST[skip: no access to query ID - may return response values]
|
|
|
|
Otherwise, if the response's `is_running` value is `false`, the async
|
|
query has finished and the results are returned.
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"is_running": false,
|
|
"columns": ...
|
|
}
|
|
----
|
|
// TEST[skip: no access to query ID - may return response values]
|
|
|
|
[[esql-async-query-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_query/async`
|
|
|
|
[[esql-async-query-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the `read`
|
|
<<privileges-list-indices,index privilege>> for the data stream, index,
|
|
or alias you query.
|
|
|
|
[[esql-async-query-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
The API accepts the same parameters as the synchronous
|
|
<<esql-query-api-query-params,query API>>.
|
|
|
|
[[esql-async-query-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
The API accepts the same request body as the synchronous
|
|
<<esql-query-api-request-body,query API>>, along with the following
|
|
parameters:
|
|
|
|
[[esql-async-query-api-wait-for-completion-timeout]]
|
|
`wait_for_completion_timeout`::
|
|
+
|
|
--
|
|
(Optional, <<time-units,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
|
|
<<esql-async-query-api-response-body-query-id,id>> is returned.
|
|
--
|
|
|
|
[[esql-async-query-api-keep-on-completion]]
|
|
`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
|
|
<<esql-async-query-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
|
|
parameter. Defaults to `false`.
|
|
--
|
|
|
|
`keep_alive`::
|
|
+
|
|
--
|
|
(Optional, <<time-units,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 <<esql-async-query-api-keep-on-completion,`keep_on_completion`>> parameter
|
|
is `false`, {es} only stores async queries that do not complete within the period
|
|
set by the <<esql-async-query-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
|
|
parameter, regardless of this value.
|
|
--
|
|
|
|
[[esql-async-query-api-response-body]]
|
|
==== {api-response-body-title}
|
|
|
|
The API returns the same response body as the synchronous
|
|
<<esql-query-api-response-body,query API>>, along with the following
|
|
properties:
|
|
|
|
[[esql-async-query-api-response-body-query-id]]
|
|
`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
|
|
<<esql-async-query-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
|
|
parameter's timeout period.
|
|
|
|
* The query request's <<esql-async-query-api-keep-on-completion,`keep_on_completion`>>
|
|
parameter is `true`.
|
|
|
|
You can use this ID with the <<esql-async-query-get-api,{esql} 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.
|
|
--
|