Run an ES|QL query

POST /_query

Api key auth

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

External documentation

Query parameters

format string

A short version of the Accept header, e.g. json, yaml.

Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.
delimiter string

The character to use between values within a CSV row. Only valid for the CSV format.
drop_null_columns boolean

Should columns that are entirely null be removed from the columns and values portion of the results? Defaults to false. If true then the response will include an extra section under the name all_columns which has the name of all columns.

application/json

Body Required

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 object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

Additional properties are allowed.

External documentation
locale string
params array[number | string | boolean | null]

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 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.
Hide tables attribute Show tables attribute object
- * object Additional properties
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Additional properties are allowed.
  
  Hide * attributes Show * attributes object
  
  integer array[number | array]
  
  One of:
  _types:TableValuesIntegerValue number _types:TableValuesIntegerValue array[number]
  
  keyword array[string | array]
  
  One of:
  _types:TableValuesKeywordValue string _types:TableValuesKeywordValue array[string]
  
  long array[number | array]
  
  One of:
  _types:TableValuesLongValue number _types:TableValuesLongValue array[number]
  
  double array[number | array]
  
  One of:
  _types:TableValuesLongDouble number _types:TableValuesLongDouble array[number]
include_ccs_metadata boolean

When set to true and performing a cross-cluster 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.

Responses

200 application/json

Additional properties are allowed.

POST /_query

curl \
 --request POST http://api.example.com/_query \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"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  \"\"\",\n  \"include_ccs_metadata\": true\n}"'

Request example

Run `POST /_query` to get results for an ES|QL 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
}