mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 15:47:23 -04:00
c5ac06a70c
Follow-up to https://github.com/elastic/elasticsearch/pull/108919. The latter needs to be merged first to have the docs tests pass, as it makes the version parameter optional in requests.
166 lines
4.6 KiB
Text
166 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"
|
|
}
|
|
----
|
|
// 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.
|
|
--
|