IMPORTANT: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
current release documentation.
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. -
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.
-
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.