Run an async ES|QL query Added in 8.13.0
Asynchronously run an ES|QL (Elasticsearch query language) query, 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.
Query parameters
-
delimiter string
The character to use between values within a CSV row. It is valid only for the CSV format.
-
drop_null_columns boolean
Indicates whether columns that are entirely
null
will be removed from thecolumns
andvalues
portion of the results. Iftrue
, the response will include an extra section under the nameall_columns
which has the name of all the columns. -
format string
A short version of the Accept header, for example
json
oryaml
.Values are
csv
,json
,tsv
,txt
,yaml
,cbor
,smile
, orarrow
. -
keep_alive string
The period for which the query and its results are stored in the cluster. The default period is 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 thewait_for_completion_timeout
parameter, regardless of this value. -
keep_on_completion boolean
Indicates whether 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. -
wait_for_completion_timeout string
The period to wait for the request to finish. By default, the request waits for 1 second for the query results. If the query completes during this period, results are returned Otherwise, a query ID is returned that can later be used to retrieve the results.
Body Required
-
columnar boolean
By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
-
filter object
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Additional properties are allowed.
-
locale string
-
params array[number | string | boolean | null | object]
To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.
-
profile boolean
If provided and
true
the response will include an extraprofile
object with information on how the query was executed. This information is for human debugging and its format can change at any time but it can give some insight into the performance of each part of the query. -
The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
-
tables object
Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
curl \
-X POST http://api.example.com/_query/async \
-H "Content-Type: application/json" \
-d '"{\n \"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 \"\"\",\n \"wait_for_completion_timeout\": \"2s\"\n}"'
{
"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"
}
{
"columns": {},
"id": "string",
"is_running": true
}