diff --git a/explore-analyze/query-filter/languages/esql-cross-clusters.md b/explore-analyze/query-filter/languages/esql-cross-clusters.md index 812ee7a35e..1dc6f83304 100644 --- a/explore-analyze/query-filter/languages/esql-cross-clusters.md +++ b/explore-analyze/query-filter/languages/esql-cross-clusters.md @@ -1,15 +1,15 @@ --- applies_to: stack: ga - serverless: ga -navigation_title: "Using {{esql}} across clusters" + serverless: unavailable +navigation_title: "Query across clusters" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-cross-clusters.html --- -# Using ES|QL across clusters [esql-cross-clusters] +# Use ES|QL across clusters [esql-cross-clusters] ::::{warning} diff --git a/explore-analyze/query-filter/languages/esql-elastic-security.md b/explore-analyze/query-filter/languages/esql-elastic-security.md index 270037a268..c66b952bce 100644 --- a/explore-analyze/query-filter/languages/esql-elastic-security.md +++ b/explore-analyze/query-filter/languages/esql-elastic-security.md @@ -2,15 +2,12 @@ applies_to: stack: ga serverless: ga -navigation_title: "Using {{esql}} in {{elastic-sec}}" +navigation_title: "{{elastic-sec}}" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-elastic-security.html --- - - -# Using ES|QL in Elastic Security [esql-elastic-security] - +# Use ES|QL in {{elastic-sec}} [esql-elastic-security] You can use {{esql}} in {{elastic-sec}} to investigate events in Timeline and create detection rules. Use the Elastic AI Assistant to build {{esql}} queries, or answer questions about the {{esql}} query language. diff --git a/explore-analyze/query-filter/languages/esql-examples.md b/explore-analyze/query-filter/languages/esql-examples.md index e179213f43..fa16e09c29 100644 --- a/explore-analyze/query-filter/languages/esql-examples.md +++ b/explore-analyze/query-filter/languages/esql-examples.md @@ -7,8 +7,6 @@ navigation_title: "Examples" # {{esql}} examples [esql-examples] - - ## Aggregating and enriching windows event logs [_aggregating_and_enriching_windows_event_logs] ```esql diff --git a/explore-analyze/query-filter/languages/esql-getting-started.md b/explore-analyze/query-filter/languages/esql-getting-started.md index 76895ea451..e59e280965 100644 --- a/explore-analyze/query-filter/languages/esql-getting-started.md +++ b/explore-analyze/query-filter/languages/esql-getting-started.md @@ -2,11 +2,10 @@ applies_to: stack: ga serverless: ga -navigation_title: "Getting started" +navigation_title: "Get started" --- -# Getting started with {{esql}} queries [esql-getting-started] - +# Get started with {{esql}} queries [esql-getting-started] This guide shows how you can use {{esql}} to query and aggregate your data. diff --git a/explore-analyze/query-filter/languages/esql-kibana.md b/explore-analyze/query-filter/languages/esql-kibana.md index 13d4811625..f229fc6437 100644 --- a/explore-analyze/query-filter/languages/esql-kibana.md +++ b/explore-analyze/query-filter/languages/esql-kibana.md @@ -2,12 +2,12 @@ applies_to: stack: ga serverless: ga -navigation_title: "Using {{esql}} in {{kib}}" +navigation_title: "{{kib}}" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-kibana.html --- -# Using ES|QL in Kibana [esql-kibana] +# Use ES|QL in Kibana [esql-kibana] You can use {{esql}} in {{kib}} to query and aggregate your data, create visualizations, and set up alerts. diff --git a/explore-analyze/query-filter/languages/esql-multi-index.md b/explore-analyze/query-filter/languages/esql-multi-index.md index 6be3cab600..e5ca7aae7e 100644 --- a/explore-analyze/query-filter/languages/esql-multi-index.md +++ b/explore-analyze/query-filter/languages/esql-multi-index.md @@ -2,15 +2,12 @@ applies_to: stack: ga serverless: ga -navigation_title: "Using {{esql}} to query multiple indices" +navigation_title: "Query multiple indices" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-multi-index.html --- - - -# Using ES|QL to query multiple indices [esql-multi-index] - +# Use ES|QL to query multiple indices [esql-multi-index] With {{esql}}, you can execute a single query across multiple indices, data streams, or aliases. To do so, use wildcards and date arithmetic. The following example uses a comma-separated list and a wildcard: diff --git a/explore-analyze/query-filter/languages/esql-multi.md b/explore-analyze/query-filter/languages/esql-multi.md new file mode 100644 index 0000000000..39750df515 --- /dev/null +++ b/explore-analyze/query-filter/languages/esql-multi.md @@ -0,0 +1,13 @@ +--- +applies_to: + stack: ga + serverless: ga +navigation_title: "Query multiple sources" +--- + +# Query multiple indices or clusters with {{esql}} + +{{esql}} allows you to query across multiple indices or clusters. Learn more in the following sections: + +* [Query multiple indices](esql-multi-index.md) +* [Query across clusters](esql-cross-clusters.md) \ No newline at end of file diff --git a/explore-analyze/query-filter/languages/esql-rest.md b/explore-analyze/query-filter/languages/esql-rest.md index 3e3b0900b0..5f4cda712a 100644 --- a/explore-analyze/query-filter/languages/esql-rest.md +++ b/explore-analyze/query-filter/languages/esql-rest.md @@ -2,16 +2,16 @@ applies_to: stack: ga serverless: ga -navigation_title: "{{esql}} query API" +navigation_title: "{{esql}} `_query` API" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-rest.html --- +# Use the {{esql}} `_query` API [esql-rest] - -# {{esql}} query API [esql-rest] - - +::::{tip} +The [Search and filter with {{esql}}](/solutions/search/esql-search-tutorial.md) tutorial provides a hands-on introduction to the {{esql}} query API. +:::: ## Overview [esql-rest-overview] diff --git a/explore-analyze/query-filter/languages/esql-where.md b/explore-analyze/query-filter/languages/esql-where.md new file mode 100644 index 0000000000..0abe00b5b0 --- /dev/null +++ b/explore-analyze/query-filter/languages/esql-where.md @@ -0,0 +1,14 @@ +--- +applies_to: + stack: ga + serverless: ga +navigation_title: "Interfaces" +--- + +# Where can I use {{esql}}? + +You can use {{esql}} in the following contexts: + +* [REST API](esql-rest.md) +* [Kibana](esql-kibana.md) +* [Elastic Security](esql-elastic-security.md) diff --git a/explore-analyze/query-filter/languages/esql.md b/explore-analyze/query-filter/languages/esql.md index d75d5a8367..fcdeaeb3a9 100644 --- a/explore-analyze/query-filter/languages/esql.md +++ b/explore-analyze/query-filter/languages/esql.md @@ -1,7 +1,4 @@ --- -applies_to: - stack: ga - serverless: ga mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-getting-started.html @@ -10,54 +7,88 @@ mapped_pages: - https://www.elastic.co/guide/en/kibana/current/esql.html --- -# ES|QL [esql] +# {{esql}} [esql] + +**Elasticsearch Query Language ({{esql}})** is a piped query language for filtering, transforming, and analyzing data. ## What's {{esql}}? [_the_esql_compute_engine] -**Elasticsearch Query Language ({{esql}})** is a piped query language for filtering, transforming, and analyzing data. +You can author {{esql}} queries to find specific events, perform statistical analysis, and create visualizations. It supports a wide range of commands, functions, and operators to perform various data operations, such as filter, aggregation, time-series analysis, and more. It initially supported a subset of the features available in Query DSL, but it is rapidly evolving with every {{serverless-full}} and Stack release. -You can author {{esql}} queries to find specific events, perform statistical analysis, and generate visualizations. It supports a wide range of [commands](elasticsearch://reference/query-languages/esql/esql-commands.md), [functions, and operators](elasticsearch://reference/query-languages/esql/esql-functions-operators.md) to perform various data operations, such as filtering, aggregation, time-series analysis, and more. Today, it supports a subset of the features available in Query DSL, but it is rapidly evolving. +{{esql}} is designed to be easy to read and write, making it accessible for users with varying levels of technical expertise. It is particularly useful for data analysts, security professionals, and developers who need to work with large datasets in Elasticsearch. -::::{note} -**{{esql}}'s compute architecture** +## How does it work? [search-analyze-data-esql] -{{esql}} is built on top of a new compute architecture within {{es}}, designed to achieve high functional and performance requirements for {{esql}}. {{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. +{{esql}} uses pipes (`|`) to manipulate and transform data in a step-by-step fashion. This approach allows you to compose a series of operations, where the output of one operation becomes the input for the next, enabling complex data transformations and analysis. -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. -:::: +Here's a simple example of an {{esql}} query: -## How does it work? [search-analyze-data-esql] +```esql +FROM sample_data +| SORT @timestamp DESC +| LIMIT 3 +``` + +Note that each line in the query represents a step in the data processing pipeline: +- The `FROM` clause specifies the index or data stream to query +- The `SORT` clause sorts the data by the `@timestamp` field in descending order +- The `LIMIT` clause restricts the output to the top 3 results -The {{es}} Query Language ({{esql}}) makes use of "pipes" (|) to manipulate and transform data in a step-by-step fashion. This approach allows you to compose a series of operations, where the output of one operation becomes the input for the next, enabling complex data transformations and analysis. +### User interfaces -You can use it: -- In your queries to {{es}} APIs, using the [`_query` endpoint](/explore-analyze/query-filter/languages/esql-rest.md) that accepts queries written in {{esql}} syntax. -- Within various {{kib}} tools such as Discover and Dashboards, to explore your data and build powerful visualizations. +You can interact with {{esql}} in two ways: -Learn more about using {{esql}} for Search use cases in this tutorial: [Search and filter with {{esql}}](/solutions/search/esql-search-tutorial.md). +- **Programmatic access**: Use {{esql}} syntax with the {{es}} `_query` endpoint. -## Next steps +- **Interactive interfaces**: Work with {{esql}} through Elastic user interfaces including Kibana Discover, Dashboards, Dev Tools, and analysis tools in Elastic Security and Observability. -Find more details about {{esql}} in the following documentation pages: -- [{{esql}} reference](elasticsearch://reference/query-languages/esql.md): - - Reference documentation for the [{{esql}} syntax](elasticsearch://reference/query-languages/esql/esql-syntax.md): - - Reference for [commands](elasticsearch://reference/query-languages/esql/esql-commands.md), and [functions and operators](elasticsearch://reference/query-languages/esql/esql-functions-operators.md) - - How to work with [metadata fields](elasticsearch://reference/query-languages/esql/esql-metadata-fields.md) and [multivalued fields](elasticsearch://reference/query-languages/esql/esql-multivalued-fields.md) - - How to work with [DISSECT and GROK](elasticsearch://reference/query-languages/esql/esql-process-data-with-dissect-grok.md), [ENRICH](elasticsearch://reference/query-languages/esql/esql-enrich-data.md), and [LOOKUP join](elasticsearch://reference/query-languages/esql/esql-lookup-join.md) +## Documentation +### Usage guides +- **Get started** + - [Get started in docs](/explore-analyze/query-filter/languages/esql-getting-started.md) + - [Training course](https://www.elastic.co/training/introduction-to-esql) +- **{{esql}} interfaces** + - [Use the query API](/explore-analyze/query-filter/languages/esql-rest.md) + - [Use {{esql}} in Kibana](/explore-analyze/query-filter/languages/esql-kibana.md) + - [Use {{esql}} in Elastic Security](/explore-analyze/query-filter/languages/esql-elastic-security.md) +- **{{esql}} for search use cases** + - [{{esql}} for search landing page](/solutions/search/esql-for-search.md) + - [{{esql}} for search tutorial](/solutions/search/esql-search-tutorial.md) +- **Query multiple sources** + - [Query multiple indices](/explore-analyze/query-filter/languages/esql-multi-index.md) + - [Query across clusters](/explore-analyze/query-filter/languages/esql-cross-clusters.md) -- Using {{esql}}: - - An overview of using the [`_query` API endpoint](/explore-analyze/query-filter/languages/esql-rest.md). - - [Using {{esql}} for search](/solutions/search/esql-for-search.md). - - [Using {{esql}} in {{kib}}](../../../explore-analyze/query-filter/languages/esql-kibana.md). - - [Using {{esql}} in {{elastic-sec}}](/explore-analyze/query-filter/languages/esql-elastic-security.md). - - [Using {{esql}} with multiple indices](/explore-analyze/query-filter/languages/esql-multi-index.md). - - [Using {{esql}} across clusters](/explore-analyze/query-filter/languages/esql-cross-clusters.md). - - [Task management](/explore-analyze/query-filter/languages/esql-task-management.md). +### Reference documentation +:::{note} +The {{esql}} reference documentation lives in the {{es}} reference section of the Elastic docs. +::: -- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md): The current limitations of {{esql}}. +#### Core references +* [{{esql}} reference](elasticsearch://reference/query-languages/esql.md) +* [{{esql}} syntax](elasticsearch://reference/query-languages/esql/esql-syntax.md) -- [Examples](/explore-analyze/query-filter/languages/esql.md): A few examples of what you can do with {{esql}}. +#### Commands, functions, and operators +* [Commands](elasticsearch://reference/query-languages/esql/esql-commands.md) +* [Functions and operators](elasticsearch://reference/query-languages/esql/esql-functions-operators.md) -To get started, you can also try [our ES|QL training course](https://www.elastic.co/training/introduction-to-esql). +#### Field types +* [Metadata fields](elasticsearch://reference/query-languages/esql/esql-metadata-fields.md) +* [Multivalued fields](elasticsearch://reference/query-languages/esql/esql-multivalued-fields.md) + +#### Advanced features +* [DISSECT and GROK](elasticsearch://reference/query-languages/esql/esql-process-data-with-dissect-grok.md) +* [ENRICH](elasticsearch://reference/query-languages/esql/esql-enrich-data.md) +* [LOOKUP JOIN](elasticsearch://reference/query-languages/esql/esql-lookup-join.md) + +#### Limitations +* [Limitations](elasticsearch://reference/query-languages/esql/limitations.md) + +::::{note} +**{{esql}}'s compute architecture** + +{{esql}} is built on top of a new compute architecture within {{es}}, designed to achieve high functional and performance requirements for {{esql}}. {{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. +:::: \ No newline at end of file diff --git a/explore-analyze/toc.yml b/explore-analyze/toc.yml index ba04dba75b..387a17f958 100644 --- a/explore-analyze/toc.yml +++ b/explore-analyze/toc.yml @@ -9,13 +9,17 @@ toc: - file: query-filter/languages/esql.md children: - file: query-filter/languages/esql-getting-started.md - - file: query-filter/languages/esql-rest.md - - file: query-filter/languages/esql-kibana.md - - file: query-filter/languages/esql-elastic-security.md - - file: query-filter/languages/esql-multi-index.md - - file: query-filter/languages/esql-cross-clusters.md - - file: query-filter/languages/esql-task-management.md + - file: query-filter/languages/esql-where.md + children: + - file: query-filter/languages/esql-rest.md + - file: query-filter/languages/esql-kibana.md + - file: query-filter/languages/esql-elastic-security.md + - file: query-filter/languages/esql-multi.md + children: + - file: query-filter/languages/esql-multi-index.md + - file: query-filter/languages/esql-cross-clusters.md - file: query-filter/languages/esql-examples.md + - file: query-filter/languages/esql-task-management.md - file: query-filter/languages/sql.md children: - file: query-filter/languages/sql-overview.md