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 <<esql-rest,`_query` endpoint>> to run an {esql} query:

// tag::esql-query-api-example[]
[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]
// end::esql-query-api-example[]

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. You can return data in other
<<esql-rest-format,response formats>> by specifying the `format` parameter in
the URL or by setting the `Accept` or `Content-Type` HTTP header.

By default, an {esql} query returns up to 500 rows. You can change this using
the <<esql-limit,`LIMIT` command>>. The previous query's `LIMIT` command limits
results to 5 rows. The maximum number of returned rows is 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.

--

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

include::esql-language.asciidoc[]

include::esql-commands.asciidoc[]

include::esql-functions-operators.asciidoc[]

include::esql-rest.asciidoc[]

include::esql-kibana.asciidoc[]

include::task-management.asciidoc[]

include::esql-limitations.asciidoc[]

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