elasticsearch/docs/reference/esql/esql-query-api.asciidoc

[[esql-query-api]]
=== {esql} query API
++++
<titleabbrev>{esql} query API</titleabbrev>
++++

Returns search results for an <<esql,ES|QL ({es} query language)>> query.

[source,console]
----
POST /_query
{
  "query": """
    FROM library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "version": "2024.04.01"
}
----
// TEST[setup:library]

[discrete]
[[esql-query-api-request]]
==== {api-request-title}

`POST _query`

[discrete]
[[esql-query-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `read`
<<privileges-list-indices,index privilege>> for the data stream, index,
or alias you search.

[discrete]
[[esql-query-api-query-params]]
==== {api-query-parms-title}

`delimiter`::
(Optional, string) Separator for CSV results. Defaults to `,`. The API only
supports this parameter for CSV responses.

`drop_null_columns`::
(Optional, boolean) Should columns that are entirely `null` be removed from
the `columns` and `values` portion of the results? Defaults to `false`. If
`true` the the response will include an extra section under the name
`all_columns` which has the name of all columns.

`format`::
(Optional, string) Format for the response. For valid values, refer to
<<esql-rest-format>>.
+
You can also specify a format using the `Accept` HTTP header. If you specify
both this parameter and the `Accept` HTTP header, this parameter takes
precedence.

[discrete]
[role="child_attributes"]
[[esql-query-api-request-body]]
==== {api-request-body-title}

`columnar`::
(Optional, Boolean) If `true`, returns results in a columnar format. Defaults to
`false`. The API only supports this parameter for CBOR, JSON, SMILE, and YAML
responses. See <<esql-rest-columnar>>.

`locale`::
(Optional, string) Returns results (especially dates) formatted per the conventions of the locale.
For syntax, refer to <<esql-locale-param>>.

`params`::
(Optional, array) Values for parameters in the `query`. For syntax, refer to
<<esql-rest-params>>.

`query`::
(Required, string) {esql} query to run. For syntax, refer to <<esql-syntax>>.

`version`::
(Required, string) {esql} language version. Can be sent in short or long form, e.g.
`2024.04.01` or `2024.04.01.🚀`. See <<esql-version>> for details.

[discrete]
[role="child_attributes"]
[[esql-query-api-response-body]]
==== {api-response-body-title}

`columns`::
(array of objects)
Column `name` and `type` for each column returned in `values`. Each object is a single column.

`all_columns`::
(array of objects)
Column `name` and `type` for each queried column. Each object is a single column. This is only
returned if `drop_null_columns` is sent with the request.

`rows`::
(array of arrays)
Values for the search results.