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
edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.
ES|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. -
allow_partial_results
-
(Optional, boolean) If
true
, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards. This defaults totrue
, unless the cluster settingesql.query.allow_partial_results
is set tofalse
, in which case it also defaults tofalse
.
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.
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.
-
is_partial
- (boolean) Indicates whether the response is partial. Partial responses can happen due to partial shard failures, failures in remote clusters, or if the async query was stopped by calling the async query stop API.
-
_clusters
-
(object)
Metadata about clusters involved in the execution of a query. This field is present in the response in the following cases:
(1) for cross-cluster searches, when
include_ccs_metadata
is sent in the body and set totrue
; (2) the result is partial (is_partial
istrue
) and there are failures on some clusters. It is only returned if theformat
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.