Executes a SQL request Added in 6.3.0

POST /_sql

Query parameters

  • format string

    Format for the response.

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

application/json

Body Required

  • catalog string

    Default catalog (cluster) for queries. If unspecified, the queries execute on the data in the local cluster only.

  • columnar boolean

    If true, the results in a columnar fashion: one row represents all the values of a certain column from the current page of results.

  • cursor string

    Cursor used to retrieve a set of paginated results. If you specify a cursor, the API only uses the columnar and time_zone request body parameters. It ignores other request body parameters.

  • The maximum number of rows (or entries) to return in one response

  • filter object

    Additional properties are allowed.

  • query string

    SQL query to run.

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

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

  • Throw an exception when encountering multiple values for a field (default) or be lenient and return the first value from the list (without any guarantees of what that will be - typically the first in natural ascending order).

  • Hide runtime_mappings attribute Show runtime_mappings attribute object
    • * object Additional properties

      Additional properties are allowed.

      Hide * attributes Show * attributes object
      • fields object

        For type composite

        Hide fields attribute Show fields attribute object
        • * object Additional properties

          Additional properties are allowed.

          Hide * attribute Show * attribute object
          • type string Required

            Values are boolean, composite, date, double, geo_point, ip, keyword, long, or lookup.

      • fetch_fields array[object]

        For type lookup

        Hide fetch_fields attributes Show fetch_fields attributes object
        • field string Required

          Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • format string
      • format string

        A custom format for date type runtime fields.

      • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • script object

        Additional properties are allowed.

        Hide script attributes Show script attributes object
        • source string

          The script source.

        • id string
        • params object

          Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

          Hide params attribute Show params attribute object
          • * object Additional properties

            Additional properties are allowed.

        • lang string

          Any of:

          Values are painless, expression, mustache, or java.

        • options object
          Hide options attribute Show options attribute object
          • * string Additional properties
      • type string Required

        Values are boolean, composite, date, double, geo_point, ip, keyword, long, or lookup.

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

  • params object

    Values for parameters in the query.

    Hide params attribute Show params attribute object
    • * object Additional properties

      Additional properties are allowed.

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

  • If true, Elasticsearch stores synchronous searches if you also specify the wait_for_completion_timeout parameter. If false, Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout.

  • If true, the search can run on frozen indices. Defaults to false.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • id string
    • is_running boolean

      If true, the search is still running. If false, the search has finished. This value is only returned for async and saved synchronous searches. For CSV, TSV, and TXT responses, this value is returned in the Async-partial HTTP header.

    • is_partial boolean

      If true, the response does not contain complete search results. If is_partial is true and is_running is true, the search is still running. If is_partial is true but is_running is false, the results are partial due to a failure or timeout. This value is only returned for async and saved synchronous searches. For CSV, TSV, and TXT responses, this value is returned in the Async-partial HTTP header.

    • columns array[object]

      Column headings for the search results. Each object is a column.

      Hide columns attributes Show columns attributes object
    • cursor string

      Cursor for the next set of paginated results. For CSV, TSV, and TXT responses, this value is returned in the Cursor HTTP header.

    • rows array[array] Required

      Values for the search results.

      Additional properties are allowed.

POST /_sql
curl \
 -X POST http://api.example.com/_sql \
 -H "Content-Type: application/json" \
 -d '{"catalog":"string","columnar":true,"cursor":"string","fetch_size":42.0,"filter":{},"query":"string","request_timeout":"string","page_timeout":"string","time_zone":"string","field_multi_value_leniency":true,"runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"source":"string","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"":"painless","options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"wait_for_completion_timeout":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"keep_alive":"string","keep_on_completion":true,"index_using_frozen":true}'
Request examples
{
  "catalog": "string",
  "columnar": true,
  "cursor": "string",
  "fetch_size": 42.0,
  "filter": {},
  "query": "string",
  "request_timeout": "string",
  "page_timeout": "string",
  "time_zone": "string",
  "field_multi_value_leniency": true,
  "runtime_mappings": {
    "additionalProperty1": {
      "fields": {
        "additionalProperty1": {
          "type": "boolean"
        },
        "additionalProperty2": {
          "type": "boolean"
        }
      },
      "fetch_fields": [
        {
          "field": "string",
          "format": "string"
        }
      ],
      "format": "string",
      "input_field": "string",
      "target_field": "string",
      "target_index": "string",
      "script": {
        "source": "string",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "": "painless",
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "type": "boolean"
    },
    "additionalProperty2": {
      "fields": {
        "additionalProperty1": {
          "type": "boolean"
        },
        "additionalProperty2": {
          "type": "boolean"
        }
      },
      "fetch_fields": [
        {
          "field": "string",
          "format": "string"
        }
      ],
      "format": "string",
      "input_field": "string",
      "target_field": "string",
      "target_index": "string",
      "script": {
        "source": "string",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "": "painless",
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "type": "boolean"
    }
  },
  "wait_for_completion_timeout": "string",
  "params": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "keep_alive": "string",
  "keep_on_completion": true,
  "index_using_frozen": true
}
Response examples (200)
{
  "id": "string",
  "is_running": true,
  "is_partial": true,
  "columns": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "cursor": "string",
  "rows": [
    [
      {}
    ]
  ]
}