Run an ES|QL query

  • POST /_query
Auth

Get search results for an ES|QL (Elasticsearch query language) query.

More about ES|QL reference

Required authorization

Index privileges read

Query parameters

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.

Values: csv json tsv txt yaml cbor smile arrow
delimiter string · default: ,

The character to use between values within a CSV row. Only valid for the CSV format.

drop_null_columns boolean · default: false

Should columns that are entirely null be removed from the columns and values portion of the results? Defaults to false. If true then the response will include an extra section under the name all_columns which has the name of all columns.

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.

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

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.

time_zone string

The default timezone to be used in the query. It defaults to UTC and overrides the time_zone request parameter.

approximation union oneOf

Enables query approximation if possible for the query. false (the default) disables query approximation and true enables it with default settings. A map value enables query approximation with custom settings.

One of:
column_metadata boolean | string · default: false

When enabled, column metadata is added to the query response as additional _meta properties. Currently, only _meta.bucket is added for columns corresponding to the BUCKET function, containing the bucket interval and unit for queries where it can be determined.

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
<string> object
status enum required
Values: running successful partial skipped failed
indices string required
took number
_shards object
total number required
successful number
skipped number
failed number
failures object[]
shard number required
index union string required nullable
node string
reason object required
type string required

The type of error

reason union string nullable

A human-readable explanation of the error, in English.

One of: string
stack_trace string

The server stack trace. Present only if the error_trace=true parameter was sent with the request.

caused_by object
Same fields as reason in failures
root_cause object[]
Same fields as reason in failures
suppressed object[]
Same fields as reason in failures
profile object

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