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}) provides a powerful way to filter, transform, and analyze data stored in {es}.
Users can author {esql} queries to find specific events, perform statistical analysis, and generate visualizations.
It supports a wide range of commands and functions that enable users to perform various data operations,
such as filtering, aggregation, time-series analysis, and more.

The {es} Query Language ({esql}) makes use of "pipes" to manipulate and transform data in a step-by-step fashion.
This approach allows users to compose a series of operations, where the output of one operation becomes the input for the next,
enabling complex data transformations and analysis.

A simple example of an {esql} query is shown below:
[source,esql]
----
FROM employees
| EVAL age = DATE_DIFF(NOW(), birth_date, 'Y')
| STATS AVG(age) BY department
| SORT age DESC
----

Each {esql} query starts with a <<esql-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-commands,processing commands>>. Processing commands change an
input table by adding, removing, or changing rows and columns.
Processing commands can perform filtering, projection, aggregation, and more.

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]
=== The {esql} Compute Engine

{esql} is more than a language. It represents a significant investment in new compute capabilities within {es}.
To achieve both the functional and performance requirements for {esql}, it was necessary to build an entirely new
compute architecture. {esql} search, aggregation, and transformation functions are directly executed within Elasticsearch
itself. Query expressions are not transpiled to Query DSL for execution. This approach allows {esql} to be extremely performant and versatile.

The new {esql} execution engine was designed with performance in mind — it operates on blocks at a time instead of per row, targets vectorization and cache locality, and embraces specialization and multi-threading. It is a separate component from the existing Elasticsearch aggregation framework with different performance characteristics.

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

include::esql-language.asciidoc[]

include::esql-rest.asciidoc[]

include::esql-kibana.asciidoc[]

include::task-management.asciidoc[]

include::esql-limitations.asciidoc[]

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