Run an ES|QL query

POST /_query

Get search results for an ES|QL (Elasticsearch query language) query.

Required authorization

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Query parameters

Request body

columnar boolean: By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
filter {} Query: Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.
time_zone string: Sets the default timezone of the query.
locale string: Returns results (especially dates) formatted per the conventions of the locale.
params union: To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.
profile boolean: If provided and true the response will include an extra profile object with information on how the query was executed. This information is for human debugging and its format can change at any time but it can give some insight into the performance of each part of the query.
query string required: The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
tables map string to string to object: Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
include_ccs_metadata boolean · default: false: When set to true and performing a cross-cluster/cross-project query, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count.
include_execution_metadata boolean · default: false: When set to true, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count. This is similar to include_ccs_metadata, but it also returns metadata when the query is not CCS/CPS
settings object: Per-query settings, the request-body equivalent of the in-query SET command. For example, time_zone can be supplied here instead of as a top-level field.

Response

application/json

took number
is_partial boolean
all_columns object[]
columns object[] required
values union oneOf[] required: One of: number or string or boolean
_clusters object: Cross-cluster search information. Present if include_ccs_metadata was true in the request and a cross-cluster search was performed.
profile object: Profiling information. Present if profile was true in the request. The contents of this field are currently unstable.

Examples

Request Console 1 / 8 languages

Run POST /_query to get results for an ES|QL query.

Console Kibana Dev Tools

POST /_query
{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "include_ccs_metadata": true
}

JavaScript Elasticsearch JavaScript Client

const response = await client.esql.query({
  query:
    "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
  include_ccs_metadata: true,
});

Python Elasticsearch Python Client

resp = client.esql.query(
    query="\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    include_ccs_metadata=True,
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_query" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    "include_ccs_metadata": true
  }'

Java Elasticsearch Java Client

client.esql().query(q -> q
    .includeCcsMetadata(true)
    .query("""
        
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  
        """)
);

C# Elasticsearch .NET Client

var response = await client.Esql
    .QueryAsync(d1 => d1
        .IncludeCcsMetadata(true)
        .Query("\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ")
    );

PHP Elasticsearch PHP Client

$resp = $client->esql()->query([
    "body" => [
        "query" => "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
        "include_ccs_metadata" => true,
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.esql.query(
  body: {
    "query": "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    "include_ccs_metadata": true
  }
)

Response

No example

Required authorization

Authentication

Query parameters

Request body { }

Response

Request body