elasticsearch/docs/reference/esql/index.asciidoc

[[esql]]
= {esql}

:esql-tests: {xes-repo-dir}/../../plugin/esql/qa
:esql-specs: {esql-tests}/testFixtures/src/main/resources

[partintro]
--

preview::[]

The {es} Query Language ({esql}) is a query language that enables the iterative
exploration of data.

An {esql} query consists of a series of commands, separated by pipes. Each query
starts with a <<esql-source-commands,source command>>. A source command produces
a table, typically with data from {es}.

image::images/esql/source-command.svg[A source command producing a table from {es},align="center"]

A source command can be followed by one or more
<<esql-processing-commands,processing commands>>. Processing commands change an
input table by adding, removing, or changing rows and columns.

image::images/esql/processing-command.svg[A processing command changing an input table,align="center"]

You can chain processing commands, separated by a pipe character: `|`. Each
processing command works on the output table of the previous command.

image::images/esql/chaining-processing-commands.svg[Processing commands can be chained,align="center"]

The result of a query is the table produced by the final processing command.

[discrete]
[[esql-console]]
=== Run an {esql} query

[discrete]
==== The {esql} API

Use the `_query` endpoint to run an {esql} query:

[source,console]
----
POST /_query
{
  "query": """
    FROM library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """
}
----
// TEST[setup:library]

The results come back in rows:

[source,console-result]
----
{
  "columns": [
    { "name": "MAX(page_count)", "type": "integer"},
    { "name": "year"           , "type": "date"}
  ],
  "values": [
    [268, "1932-01-01T00:00:00.000Z"],
    [224, "1951-01-01T00:00:00.000Z"],
    [227, "1953-01-01T00:00:00.000Z"],
    [335, "1959-01-01T00:00:00.000Z"],
    [604, "1965-01-01T00:00:00.000Z"]
  ]
}
----

By default, results are returned as JSON. To return results formatted as text,
CSV, or TSV, use the `format` parameter:

[source,console]
----
POST /_query?format=txt
{
  "query": """
    FROM library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """
}
----
// TEST[setup:library]

The above query's `LIMIT` command limits results to 5 rows.

If not specified, `LIMIT` defaults to `500`. A single query will not return
more than 10,000 rows, regardless of the `LIMIT` value.

[discrete]
==== {kib}

Use {esql} in Discover to explore a data set. From the data view dropdown,
select *Try {esql}* to get started.

NOTE: {esql} queries in Discover and Lens are subject to the time range selected
with the time filter.

[discrete]
[[esql-limitations]]
=== Limitations

* {esql} currently supports the following <<mapping-types,field types>>:

** `alias`
** `boolean`
** `date`
** `double` (`float`, `half_float`, `scaled_float` are represented as `double`)
** `ip`
** `keyword` family including `keyword`, `constant_keyword`, and `wildcard`
** `int` (`short` and `byte` are represented as `int`)
** `long`
** `null`
** `text`
** `unsigned_long`
** `version`

* A single query will not return more than 10,000 rows, regardless of the
`LIMIT` command's value.
--

include::esql-get-started.asciidoc[]

include::esql-syntax.asciidoc[]

include::esql-source-commands.asciidoc[]

include::esql-processing-commands.asciidoc[]

include::esql-functions.asciidoc[]

include::aggregation-functions.asciidoc[]

include::multivalued-fields.asciidoc[]

include::metadata-fields.asciidoc[]

include::task-management.asciidoc[]

:esql-tests!:
:esql-specs!: