Run an ES|QL query
- POST /_query
Get search results for an ES|QL (Elasticsearch query language) query.
More about ES|QL referenceRequired privileges
- Index privileges read
Query parameters
-
formatenum -
A short version of the Accept header, e.g. json, yaml.
csv,tsv, andtxtformats will return results in a tabular format, excluding other metadata fields from the response. -
Values:
csvjsontsvtxtyamlcborsmilearrow -
delimiterstring · default: , -
The character to use between values within a CSV row. Only valid for the CSV format.
-
drop_null_columnsboolean · default: false -
Should columns that are entirely
nullbe removed from thecolumnsandvaluesportion of the results? Defaults tofalse. Iftruethen the response will include an extra section under the nameall_columnswhich has the name of all columns. -
allow_partial_resultsboolean · 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. Iffalse, the query will fail if there are any failures.To override the default behavior, you can set the
esql.query.allow_partial_resultscluster setting tofalse.
Request body
-
columnarboolean -
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_zonestringThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Sets the default timezone of the query.
-
paramsunion 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[]orobject[] -
profileboolean -
If provided and
truethe response will include an extraprofileobject 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. -
querystringrequired -
The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
-
tablesmap 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_metadataboolean · default: false -
When set to
trueand performing a cross-cluster/cross-project query, the response will include an extra_clustersobject with information about the clusters that participated in the search along with info such as shards count. -
include_execution_metadataboolean · default: false -
When set to
true, the response will include an extra_clustersobject with information about the clusters that participated in the search along with info such as shards count. This is similar toinclude_ccs_metadata, but it also returns metadata when the query is not CCS/CPS -
settingsobjectThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Per-query settings, the request-body equivalent of the in-query
SETcommand. For example,time_zonecan be supplied here instead of as a top-level field. -
time_zonestringThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
The default timezone to be used in the query. It defaults to UTC and overrides the
time_zonerequest parameter. -
approximationunion oneOfThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Enables query approximation if possible for the query.
false(the default) disables query approximation andtrueenables it with default settings. A map value enables query approximation with custom settings. - One of:
-
column_metadataboolean | string · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Experimental since 9.5 This functionality is experimental and is not ready for production usage. Experimental features may change or be removed at any time. Elastic will work to fix any issues, but experimental features are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
When enabled, column metadata is added to the query response as additional
_metaproperties. Currently, only_meta.bucketis added for columns corresponding to theBUCKETfunction, containing the bucket interval and unit for queries where it can be determined.