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
  """
}
----
// 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>>.

`include_ccs_metadata`::
(Optional, boolean) If `true`, cross-cluster searches will include metadata about the query
on each cluster. Defaults to `false`. The API only supports this parameter for CBOR, JSON, SMILE,
and YAML responses. See <<ccq-cluster-details>>.

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

`profile`::
(Optional, boolean) If provided and `true` the response will include an extra `profile` object
with information about how the query was executed. It provides insight into the performance
of each part of the query. This is for human debugging as the object's format might change at any time.
Think of this like https://www.postgresql.org/docs/current/sql-explain.html[EXPLAIN ANALYZE] or
https://en.wikipedia.org/wiki/Query_plan[EXPLAIN PLAN].

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


ifeval::["{release-state}"=="unreleased"]
`table`::
(Optional, object) Named "table" parameters that can be referenced by the <<esql-lookup>> command.
endif::[]

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

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

`_clusters`::
(object)
Metadata about clusters involved in the execution of a cross-cluster query. Only returned (1) for
cross-cluster searches and (2) when `include_ccs_metadata` is sent in the body and set to `true`
and (3) when `format` of the response is set to JSON (the default), CBOR, SMILE, or YAML.
See <<ccq-cluster-details>> for more information.

`profile`::
(object)
Profile describing the execution of the query. Only returned if `profile` was sent in the body.
The object itself is for human debugging and can change at any time. Think of this like
https://www.postgresql.org/docs/current/sql-explain.html[EXPLAIN ANALYZE] or
https://en.wikipedia.org/wiki/Query_plan[EXPLAIN PLAN].