Run an async ES|QL query | Elasticsearch API documentation

Run an async ES|QL query Added in 8.13.0

POST /_query/async

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.

External documentation

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 the columns and values portion of the results. If true, the response will include an extra section under the name all_columns which has the name of all the columns.
format string

A short version of the Accept header, for example json or yaml.

Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.
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 the wait_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.

application/json

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.

External documentation
locale string
params array[number | string | boolean | null]

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 extra profile 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.
query string Required

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.
Hide tables attribute Show tables attribute object
- * object Additional properties
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Additional properties are allowed.
  
  Hide * attributes Show * attributes object
  
  integer array[number | array]
  
  One of:
  _types:TableValuesIntegerValue number _types:TableValuesIntegerValue array[number]
  
  keyword array[string | array]
  
  One of:
  _types:TableValuesKeywordValue string _types:TableValuesKeywordValue array[string]
  
  long array[number | array]
  
  One of:
  _types:TableValuesLongValue number _types:TableValuesLongValue array[number]
  
  double array[number | array]
  
  One of:
  _types:TableValuesLongDouble number _types:TableValuesLongDouble array[number]
include_ccs_metadata boolean

When set to true and performing a cross-cluster query, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count.

Responses

200 application/json

Additional properties are allowed.

POST /_query/async

curl \
 --request POST http://api.example.com/_query/async \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": \"\"\"\n    FROM library,remote-*: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  \"include_ccs_metadata\": true\n}"'

Request example

{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s",
  "include_ccs_metadata": true
}

Response examples (200)

{}