mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 01:44:36 -04:00
c5ac06a70c
Follow-up to https://github.com/elastic/elasticsearch/pull/108919. The latter needs to be merged first to have the docs tests pass, as it makes the version parameter optional in requests.
97 lines
2.5 KiB
Text
97 lines
2.5 KiB
Text
[[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>>.
|
|
|
|
`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>>.
|
|
|
|
[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.
|