Query parameters

  • delimiterstring

    The character to use between values within a CSV row. It is valid only for the CSV format.

  • drop_null_columnsboolean

    Indicates whether columns that are entirely null will be removed from the columns and values portion of the results. If true, the response will include an extra section under the name all_columns which has the name of all the columns.

  • formatstring

    A short version of the Accept header, for example json or yaml.

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

  • keep_alivestring

    The period for which the query and its results are stored in the cluster. The default period is five days. When this period expires, the query and its results are deleted, even if the query is still ongoing. If the keep_on_completion parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the wait_for_completion_timeout parameter, regardless of this value.

    Values are -1 or 0.

  • keep_on_completionboolean

    Indicates whether the query and its results are stored in the cluster. If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the wait_for_completion_timeout parameter.

  • wait_for_completion_timeoutstring

    The period to wait for the request to finish. By default, the request waits for 1 second for the query results. If the query completes during this period, results are returned Otherwise, a query ID is returned that can later be used to retrieve the results.

    Values are -1 or 0.

application/json

BodyRequired

  • columnarboolean

    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.

  • filterobject

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

    External documentation
  • localestring
  • paramsarray[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.

  • profileboolean

    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.

  • querystring Required

    The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.

  • tablesobject

    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
  • include_ccs_metadataboolean

    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.

  • wait_for_completion_timeoutstring

    A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object

    • Time unit for milliseconds

    • is_partialboolean
    • all_columnsarray[object]
      Hide all_columns attributes Show all_columns attributes object
    • columnsarray[object] Required
      Hide columns attributes Show columns attributes object
    • valuesarray[array] Required

      A field value.

      A field value.

    • _clustersobject
      Hide _clusters attributes Show _clusters attributes object
      • totalnumber Required
      • successfulnumber Required
      • runningnumber Required
      • skippednumber Required
      • partialnumber Required
      • failednumber Required
      • detailsobject Required
        Hide details attribute Show details attribute object
        • *object Additional properties
          Hide * attributes Show * attributes object
    • profileobject

      Profiling information. Present if profile was true in the request. The contents of this field are currently unstable.

    • idstring
    • is_runningboolean Required
POST /_query/async
POST /_query/async
{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s",
  "include_ccs_metadata": true
}
curl \
 --request POST 'http://api.example.com/_query/async' \
 --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  \"wait_for_completion_timeout\": \"2s\",\n  \"include_ccs_metadata\": true\n}"'
Request example
{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s",
  "include_ccs_metadata": true
}