mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
8f93bd00f9
This adds some basic documentation for the `profile` option in ESQL but doesn't really explain the results beyond "this is for human debugging." We're not ready for any kind of specification for this thing, but it is useful to look at.
112 lines
3.2 KiB
Text
112 lines
3.2 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>>.
|
|
|
|
`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.
|
|
|
|
`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.
|
|
|
|
`rows`::
|
|
(array of arrays)
|
|
Values for the search results.
|
|
|
|
`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.
|