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.

Query parameters

  • The character to use between values within a CSV row. It is valid only for the CSV format.

  • 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.

  • 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.

  • 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.

  • 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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • columns object

      Additional properties are allowed.

    • id string

      A query identifier that is provided only when one of the following conditions is met:

      • A query request does not return complete results during the period specified in the wait_for_completion_timeout parameter.
      • The keep_on_completion parameter value is true.

      You can use this ID with the GET /_query/async/<id> API to get the current status and available results for the query.

    • is_running boolean Required

      Indicates whether the query is still running. If the value is false, the async query has finished and the results are returned.

POST /_query/async
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}"'
Request example
{
  "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"
}
Response examples (200)
{
  "columns": {},
  "id": "string",
  "is_running": true
}