From 4e540ae34f2922717a86cf0599e66acc3dd6c4d6 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 22 Apr 2025 15:59:03 +0200 Subject: [PATCH 1/3] =?UTF-8?q?[E&A]=20Spruce=20up=20ESQL=20landing=20page?= =?UTF-8?q?=20=E2=80=A2=20removed=20gerund=20forms=20("using",=20"getting"?= =?UTF-8?q?)=20from=20all=20titles=20=E2=80=A2=20shortened=20navigation=20?= =?UTF-8?q?titles=20(kibana=20=E2=86=92=20{{kib}},=20elastic=20security=20?= =?UTF-8?q?=E2=86=92=20{{elastic-sec}})=20=E2=80=A2=20added=20two=20new=20?= =?UTF-8?q?parent=20pages=20(esql-where.md,=20esql-multi.md)=20for=20logic?= =?UTF-8?q?al=20grouping=20=E2=80=A2=20updated=20toc.yml=20to=20reflect=20?= =?UTF-8?q?new=20hierarchical=20structure=20=E2=80=A2=20marked=20cross-clu?= =?UTF-8?q?sters=20feature=20as=20unavailable=20for=20serverless=20?= =?UTF-8?q?=E2=80=A2=20expanded=20esql=20landing=20page=20with=20clearer?= =?UTF-8?q?=20structure=20and=20examples=20=E2=80=A2=20reorganized=20refer?= =?UTF-8?q?ence=20documentation=20into=20visual=20groups=20=E2=80=A2=20add?= =?UTF-8?q?ed=20section=20on=20user=20interfaces=20with=20programmatic=20v?= =?UTF-8?q?s=20interactive=20options=20=E2=80=A2=20added=20more=20cross-li?= =?UTF-8?q?nks=20between=20related=20docs=20=E2=80=A2=20improved=20consist?= =?UTF-8?q?ency=20in=20capitalization=20and=20terminology?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../languages/esql-cross-clusters.md | 6 +- .../languages/esql-elastic-security.md | 7 +- .../query-filter/languages/esql-examples.md | 2 - .../languages/esql-getting-started.md | 5 +- .../query-filter/languages/esql-kibana.md | 4 +- .../languages/esql-multi-index.md | 7 +- .../query-filter/languages/esql-multi.md | 13 +++ .../query-filter/languages/esql-rest.md | 10 +- .../query-filter/languages/esql-where.md | 14 +++ .../query-filter/languages/esql.md | 103 ++++++++++++------ explore-analyze/toc.yml | 16 ++- 11 files changed, 121 insertions(+), 66 deletions(-) create mode 100644 explore-analyze/query-filter/languages/esql-multi.md create mode 100644 explore-analyze/query-filter/languages/esql-where.md 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..fdcb7a1155 --- /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 expand your queries beyond single 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..e4f7afdb36 --- /dev/null +++ b/explore-analyze/query-filter/languages/esql-where.md @@ -0,0 +1,14 @@ +--- +applies_to: + stack: ga + serverless: ga +navigation_title: "ES|QL 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..28d8fe0f5b 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,90 @@ 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. +If you want to emphasize the distinction between programmatic access and user interface access, here's a refined version: -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. +### User interfaces -Learn more about using {{esql}} for Search use cases in this tutorial: [Search and filter with {{esql}}](/solutions/search/esql-search-tutorial.md). +You can interact with {{esql}} in two ways: -## Next steps +- **Programmatic access**: Use {{esql}} syntax with the {{es}} `_query` endpoint. -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) +- **Interactive interfaces**: Work with {{esql}} through Elastic user interfaces including Kibana Discover, Dashboards, Dev Tools, and analysis tools in Elastic Security and Observability. +## Documentation -- 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). +### 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) +### Reference documentation -- [Limitations](elasticsearch://reference/query-languages/esql/limitations.md): The current limitations of {{esql}}. +:::{note} +The {{esql}} reference documentation lives in the {{es}} reference section of the Elastic docs. +::: -- [Examples](/explore-analyze/query-filter/languages/esql.md): A few examples of what you can do with {{esql}}. +#### Core references +* [{{esql}} reference](elasticsearch://reference/query-languages/esql.md) +* [{{esql}} syntax](elasticsearch://reference/query-languages/esql/esql-syntax.md) -To get started, you can also try [our ES|QL training course](https://www.elastic.co/training/introduction-to-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) + +#### 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 From 1921dbaf58dcc6b8a2c2c48c40e2f0b4177fc395 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 22 Apr 2025 16:03:26 +0200 Subject: [PATCH 2/3] Fix imprecise verbiage, delete slop --- explore-analyze/query-filter/languages/esql-multi.md | 2 +- explore-analyze/query-filter/languages/esql.md | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/explore-analyze/query-filter/languages/esql-multi.md b/explore-analyze/query-filter/languages/esql-multi.md index fdcb7a1155..39750df515 100644 --- a/explore-analyze/query-filter/languages/esql-multi.md +++ b/explore-analyze/query-filter/languages/esql-multi.md @@ -7,7 +7,7 @@ navigation_title: "Query multiple sources" # Query multiple indices or clusters with {{esql}} -{{esql}} allows you to expand your queries beyond single indices or clusters. Learn more in the following sections: +{{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.md b/explore-analyze/query-filter/languages/esql.md index 28d8fe0f5b..fcdeaeb3a9 100644 --- a/explore-analyze/query-filter/languages/esql.md +++ b/explore-analyze/query-filter/languages/esql.md @@ -34,8 +34,6 @@ Note that each line in the query represents a step in the data processing pipeli - The `SORT` clause sorts the data by the `@timestamp` field in descending order - The `LIMIT` clause restricts the output to the top 3 results -If you want to emphasize the distinction between programmatic access and user interface access, here's a refined version: - ### User interfaces You can interact with {{esql}} in two ways: From 1528eec23af470d2b462a1caa5045ed0bd0e9535 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 22 Apr 2025 16:12:24 +0200 Subject: [PATCH 3/3] Simplify interfaces nav title --- explore-analyze/query-filter/languages/esql-where.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/explore-analyze/query-filter/languages/esql-where.md b/explore-analyze/query-filter/languages/esql-where.md index e4f7afdb36..0abe00b5b0 100644 --- a/explore-analyze/query-filter/languages/esql-where.md +++ b/explore-analyze/query-filter/languages/esql-where.md @@ -2,7 +2,7 @@ applies_to: stack: ga serverless: ga -navigation_title: "ES|QL interfaces" +navigation_title: "Interfaces" --- # Where can I use {{esql}}?