This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
ES|QL query API
editES|QL query API
editReturns search results for an ES|QL (Elasticsearch query language) query.
resp = client.esql.query( query="\n FROM library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ", ) print(resp)
const response = await client.esql.query({ query: "\n FROM library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ", }); console.log(response);
POST /_query { "query": """ FROM library | EVAL year = DATE_TRUNC(1 YEARS, release_date) | STATS MAX(page_count) BY year | SORT year | LIMIT 5 """ }
Request
editPOST _query
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
read
index privilege for the data stream, index, or alias you search.
Query parameters
edit-
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 thecolumns
andvalues
portion of the results? Defaults tofalse
. Iftrue
the the response will include an extra section under the nameall_columns
which has the name of all columns. -
format
-
(Optional, string) Format for the response. For valid values, refer to Response formats.
You can also specify a format using the
Accept
HTTP header. If you specify both this parameter and theAccept
HTTP header, this parameter takes precedence.
Request body
edit-
columnar
-
(Optional, Boolean) If
true
, returns results in a columnar format. Defaults tofalse
. The API only supports this parameter for CBOR, JSON, SMILE, and YAML responses. See Columnar results. -
include_ccs_metadata
-
(Optional, boolean) If
true
, cross-cluster searches will include metadata about the query on each cluster. Defaults tofalse
. The API only supports this parameter for CBOR, JSON, SMILE, and YAML responses. See Cross-cluster metadata. -
locale
- (Optional, string) Returns results (especially dates) formatted per the conventions of the locale. For syntax, refer to Returning localized results.
-
params
-
(Optional, array) Values for parameters in the
query
. For syntax, refer to Passing parameters to a query. -
profile
-
(Optional, boolean) If provided and
true
the response will include an extraprofile
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 EXPLAIN ANALYZE or EXPLAIN PLAN. -
query
- (Required, string) ES|QL query to run. For syntax, refer to Syntax reference.
-
table
-
(Optional, object) Named "table" parameters that can be referenced by the
LOOKUP
command.
Response body
edit-
columns
-
(array of objects)
Column
name
andtype
for each column returned invalues
. Each object is a single column. -
all_columns
-
(array of objects)
Column
name
andtype
for each queried column. Each object is a single column. This is only returned ifdrop_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 totrue
and (3) whenformat
of the response is set to JSON (the default), CBOR, SMILE, or YAML. See Cross-cluster metadata 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 EXPLAIN ANALYZE or EXPLAIN PLAN.