ES|QL query API

ES|QL query API

New API reference

For the most up-to-date API details, refer to ES|QL APIs.

Returns 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

POST _query

Prerequisites

• 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

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 Response formats.

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.

Request body

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 Columnar results.

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 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 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 EXPLAIN ANALYZE or EXPLAIN PLAN.

query

(Required, string) ES|QL query to run. For syntax, refer to Syntax reference.

Response body

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 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.