mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
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, object) {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.
|