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

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

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-esql[ES|QL APIs].
--

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.

`allow_partial_results`::
(Optional, boolean) If `true`, partial results will be returned if there are shard failures, but
the query can continue to execute on other clusters and shards. This defaults to `true`, unless
the cluster setting `esql.query.allow_partial_results` is set to `false`, in which case it also
defaults to `false`.

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

`is_partial`::
(boolean)
Indicates whether the response is partial. Partial responses can happen due to partial shard failures,
failures in remote clusters, or if the async query was stopped by calling the <<esql-async-query-stop-api,async query stop API>>.

`_clusters`::
(object)
Metadata about clusters involved in the execution of a query. This field is present in the response in the following cases:
(1) for cross-cluster searches, when `include_ccs_metadata` is sent in the body and set to `true`;
(2) the result is partial (`is_partial` is `true`) and there are failures on some clusters.
It is only returned if the `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].