mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 15:47:23 -04:00
fd9d7335c8
Since Kibana only needs CCS metadata in ESQL responses from certain well-defined locations, we are making CCS metadata opt-in. This feature is patterned after ESQL profiling, where you specify "profile": true in the ESQL body and if you asked for it will be present in the response always (it will be written to the .async-search index and you can’t turn it off in later async-search requests against this particular query ID) and if you didn’t ask for it at the beginning it will never be present (it will NOT be written to the .async-search index when it is persisted). The new option is "include_ccs_metadata": true/false.
129 lines
4.1 KiB
Text
129 lines
4.1 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>>.
|
|
|
|
`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].
|