Run an async ES|QL query

POST /_query/async

Auth

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.

More about ES|QL reference

Query parameters

allow_partial_results boolean · default: true

If true, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards. If false, the query will fail if there are any failures.

To override the default behavior, you can set the esql.query.allow_partial_results cluster setting to false.

delimiter string · default: ,

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

drop_null_columns boolean · default: false

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 enum

A short version of the Accept header, e.g. json, yaml.

csv, tsv, and txt formats will return results in a tabular format, excluding other metadata fields from the response.

For async requests, nothing will be returned if the async query doesn't finish within the timeout. The query ID and running status are available in the X-Elasticsearch-Async-Id and X-Elasticsearch-Async-Is-Running HTTP headers of the response, respectively.

Values: csv json tsv txt yaml cbor smile arrow

Request body

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 {} Query: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.
time_zone string: Sets the default timezone of the query.
locale string: Returns results (especially dates) formatted per the conventions of the locale.
params union oneOf: 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.; One of: union[] or object[]
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 map string to string to 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.
include_ccs_metadata boolean · default: false: When set to true and performing a cross-cluster/cross-project 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.
include_execution_metadata boolean · default: false: When set to true, 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. This is similar to include_ccs_metadata, but it also returns metadata when the query is not CCS/CPS
wait_for_completion_timeout string · default: 1s: 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.
keep_alive string · default: 5d: 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 · default: false: 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.
settings object: Per-query settings, the request-body equivalent of the in-query SET command. For example, time_zone can be supplied here instead of as a top-level field.

Response

application/json

took number

is_partial boolean

all_columns object[]

name string required
type string required

columns object[] required

name string required
type string required

values union oneOf[] required

One of: number or string or boolean

_clusters object

Cross-cluster search information. Present if include_ccs_metadata was true in the request and a cross-cluster search was performed.

total number required
successful number required
running number required
skipped number required
partial number required
failed number required
details map string to object required

profile object

Profiling information. Present if profile was true in the request. The contents of this field are currently unstable.

id string

The ID of the async query, to be used in subsequent requests to check the status or retrieve results.

Also available in the X-Elasticsearch-Async-Id HTTP header.

is_running boolean required

Indicates whether the async query is still running or has completed.

Also available in the X-Elasticsearch-Async-Is-Running HTTP header.

Required authorization

Query parameters

Request body { }

Response

Request body