From 146b4752d53bbdc82183e2aa92495e7924c18645 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 16 Jun 2026 13:03:17 +0200 Subject: [PATCH 1/9] Link to ES|QL query performance guide from relevant pages Cross-link the new ES|QL query performance guide (elastic/elasticsearch#150360) from six docs-content pages where readers are likely to need it: ES|QL in Kibana, ES|QL for search, query activity, search speed tuning, circuit breaker errors, and ES|QL for security. --- deploy-manage/monitor/query-activity.md | 1 + .../production-guidance/optimize-performance/search-speed.md | 4 ++++ explore-analyze/query-filter/languages/esql-kibana.md | 1 + solutions/search/esql-for-search.md | 4 ++++ solutions/security/esql-for-security.md | 3 ++- troubleshoot/elasticsearch/circuit-breaker-errors.md | 4 ++++ 6 files changed, 16 insertions(+), 1 deletion(-) diff --git a/deploy-manage/monitor/query-activity.md b/deploy-manage/monitor/query-activity.md index f37f71dfee..3f7eed9b2c 100644 --- a/deploy-manage/monitor/query-activity.md +++ b/deploy-manage/monitor/query-activity.md @@ -131,3 +131,4 @@ To change this threshold: - [](/deploy-manage/monitor/logging-configuration/query-logs.md) - [](/deploy-manage/monitor/logging-configuration/slow-logs.md) - [](/deploy-manage/production-guidance/optimize-performance/search-speed.md) +- [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) diff --git a/deploy-manage/production-guidance/optimize-performance/search-speed.md b/deploy-manage/production-guidance/optimize-performance/search-speed.md index afe69af135..dfda9e8c66 100644 --- a/deploy-manage/production-guidance/optimize-performance/search-speed.md +++ b/deploy-manage/production-guidance/optimize-performance/search-speed.md @@ -365,6 +365,10 @@ Now imagine that you have a 2-shards index and two nodes. In one case, the numbe So what is the right number of replicas? If you have a cluster that has `num_nodes` nodes, `num_primaries` primary shards *in total* and if you want to be able to cope with `max_failures` node failures at once at most, then the right number of replicas for you is `max(max_failures, ceil(num_nodes / num_primaries) - 1)`. +## Optimize {{esql}} queries [_optimize_esql_queries] + +For {{esql}}-specific performance guidance, including common anti-patterns and techniques for reducing scan size, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). + ## Tune your queries with the Search Profiler [_tune_your_queries_with_the_search_profiler] The [Profile API](elasticsearch://reference/elasticsearch/rest-apis/search-profile.md) provides detailed information about how each component of your queries and aggregations impacts the time it takes to process the request. diff --git a/explore-analyze/query-filter/languages/esql-kibana.md b/explore-analyze/query-filter/languages/esql-kibana.md index 46c347a53f..453e825aa1 100644 --- a/explore-analyze/query-filter/languages/esql-kibana.md +++ b/explore-analyze/query-filter/languages/esql-kibana.md @@ -401,3 +401,4 @@ The first time a query references an unmapped field, the editor shows a warning - [{{esql}} visualizations](/explore-analyze/visualize/esorql.md): Create and edit {{esql}}-based visualizations in dashboards. - [Dashboard controls](/explore-analyze/dashboards/add-controls.md): Add {{esql}}-powered controls to dashboards. - {applies_to}`stack: ga 9.4` {applies_to}`serverless: ga` [Custom Vega visualizations](/explore-analyze/visualize/custom-visualizations-with-vega.md#vega-esql-queries): Use {{esql}} queries as a data source in Vega and Vega-Lite visualizations. +- [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md): Techniques for writing fast queries and identifying slow ones. diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index d228ebfd40..1132f980d1 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -198,6 +198,10 @@ The [`MMR` command](elasticsearch://reference/query-languages/esql/commands/mmr. - [Search and filter with {{esql}}](elasticsearch://reference/query-languages/esql/esql-search-tutorial.md): Hands-on tutorial for getting started with search tools in {{esql}}, with concrete examples of the functionalities described in this page +### Performance [esql-for-search-performance] + +- [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md): Techniques for writing fast queries, including using full-text search functions instead of `LIKE` or `RLIKE` + ### Technical reference [esql-for-search-reference] - [Search functions](elasticsearch://reference/query-languages/esql/functions-operators/search-functions.md): Complete reference for all search functions diff --git a/solutions/security/esql-for-security.md b/solutions/security/esql-for-security.md index 7286270e9b..ae49e1ad8f 100644 --- a/solutions/security/esql-for-security.md +++ b/solutions/security/esql-for-security.md @@ -22,4 +22,5 @@ Learn how to: - [Generate and understand {{esql}} queries](/solutions/security/ai/generate-customize-learn-about-esorql-queries.md) using the AI Assistant - [Investigate events in Timeline](/solutions/security/investigate/timeline.md#esql-in-timeline) using {{esql}} - [Create detection rules](/solutions/security/detect-and-alert/esql.md) using {{esql}} -- [Convert Splunk SPL rules to {{esql}}](/solutions/security/get-started/automatic-migration.md) with Automatic Migration \ No newline at end of file +- [Convert Splunk SPL rules to {{esql}}](/solutions/security/get-started/automatic-migration.md) with Automatic Migration +- [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md): Write faster queries for threat hunting and detection rules \ No newline at end of file diff --git a/troubleshoot/elasticsearch/circuit-breaker-errors.md b/troubleshoot/elasticsearch/circuit-breaker-errors.md index 29808e30f3..390762a637 100644 --- a/troubleshoot/elasticsearch/circuit-breaker-errors.md +++ b/troubleshoot/elasticsearch/circuit-breaker-errors.md @@ -99,6 +99,10 @@ GET _nodes/stats/breaker High JVM memory pressure often causes circuit breaker errors. See [High JVM memory pressure](high-jvm-memory-pressure.md). +**Optimize {{esql}} queries** + +High-cardinality {{esql}} aggregations are a common trigger for circuit breaker errors. Refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for techniques to reduce memory usage, including avoiding high-cardinality `STATS BY` groupings. + **Avoid using fielddata on `text` fields** For high-cardinality `text` fields, fielddata can use a large amount of JVM memory. To avoid this, {{es}} disables fielddata on `text` fields by default. If you’ve enabled fielddata and triggered the [fielddata circuit breaker](elasticsearch://reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#fielddata-circuit-breaker), consider disabling it and using a `keyword` field instead. See [`fielddata` mapping parameter](elasticsearch://reference/elasticsearch/mapping-reference/text.md#fielddata-mapping-param). From 72ac49aeb2f721f98f0bd70d372d86c4a8bdaa97 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 16 Jun 2026 13:17:31 +0200 Subject: [PATCH 2/9] Add perf guide link to query logging related pages --- deploy-manage/monitor/logging-configuration/query-logs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/deploy-manage/monitor/logging-configuration/query-logs.md b/deploy-manage/monitor/logging-configuration/query-logs.md index 21c9f9c722..be6a68a089 100644 --- a/deploy-manage/monitor/logging-configuration/query-logs.md +++ b/deploy-manage/monitor/logging-configuration/query-logs.md @@ -358,3 +358,4 @@ Each query language may also include its own fields, prefixed with `elasticsearc - [Query activity](/deploy-manage/monitor/query-activity.md) - [Tune for search speed](/deploy-manage/production-guidance/optimize-performance/search-speed.md) +- [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) From f652602612b8e82cd86d271c2732fd0169e5dd6d Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 16 Jun 2026 13:20:10 +0200 Subject: [PATCH 3/9] Add perf guide link to AutoOps overview --- deploy-manage/monitor/autoops.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/deploy-manage/monitor/autoops.md b/deploy-manage/monitor/autoops.md index d817cbc24e..abdda2c083 100644 --- a/deploy-manage/monitor/autoops.md +++ b/deploy-manage/monitor/autoops.md @@ -76,3 +76,7 @@ In this section, you'll find the following information: * Which [views](/deploy-manage/monitor/autoops/views.md) AutoOps offers to gain insight into your deployment. * What AutoOps [events](/deploy-manage/monitor/autoops/ec-autoops-events.md) are and how you can configure [event settings](/deploy-manage/monitor/autoops/ec-autoops-event-settings.md) and [notifications](/deploy-manage/monitor/autoops/ec-autoops-notifications-settings.md). * [Frequently asked questions](/deploy-manage/monitor/autoops/ec-autoops-faq.md) about AutoOps. + +## Related pages + +* [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md): AutoOps detects common {{esql}} anti-patterns automatically. This guide covers the patterns and how to fix them. From e3e3d8258e0826aedd6f95ee94919d02afb72b9a Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 16 Jun 2026 13:22:18 +0200 Subject: [PATCH 4/9] Add perf guide links to slow logs, search troubleshooting, Timeline --- deploy-manage/monitor/logging-configuration/slow-logs.md | 2 +- solutions/security/investigate/timeline.md | 2 ++ troubleshoot/elasticsearch/troubleshooting-searches.md | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/deploy-manage/monitor/logging-configuration/slow-logs.md b/deploy-manage/monitor/logging-configuration/slow-logs.md index d006a4804b..66f91f7a00 100644 --- a/deploy-manage/monitor/logging-configuration/slow-logs.md +++ b/deploy-manage/monitor/logging-configuration/slow-logs.md @@ -263,4 +263,4 @@ Slow logging checks each event against the reporting threshold when the event is ## Learn more [_learn_more] -To learn about other ways to optimize your search and indexing requests, refer to [tune for search speed](/deploy-manage/production-guidance/optimize-performance/search-speed.md) and [tune for indexing speed](/deploy-manage/production-guidance/optimize-performance/indexing-speed.md). \ No newline at end of file +To learn about other ways to optimize your search and indexing requests, refer to [tune for search speed](/deploy-manage/production-guidance/optimize-performance/search-speed.md) and [tune for indexing speed](/deploy-manage/production-guidance/optimize-performance/indexing-speed.md). For {{esql}}-specific guidance, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). \ No newline at end of file diff --git a/solutions/security/investigate/timeline.md b/solutions/security/investigate/timeline.md index 10e72326a7..b0428bfbfe 100644 --- a/solutions/security/investigate/timeline.md +++ b/solutions/security/investigate/timeline.md @@ -284,3 +284,5 @@ You can use {{esql}} in Timeline by opening the **{{esql}}** tab. From there, yo To get started using {{esql}}, read the tutorial for [using {{esql}} in {{kib}}](/explore-analyze/query-filter/languages/esql-kibana.md). Much of the functionality available in {{kib}} is also available in Timeline. To find examples of using {{esql}} for threat hunting, check out [our blog](https://www.elastic.co/blog/introduction-to-esql-new-query-language-flexible-iterative-analytics). + +For tips on writing faster {{esql}} queries, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). diff --git a/troubleshoot/elasticsearch/troubleshooting-searches.md b/troubleshoot/elasticsearch/troubleshooting-searches.md index 9444b6f937..d6aa65afb8 100644 --- a/troubleshoot/elasticsearch/troubleshooting-searches.md +++ b/troubleshoot/elasticsearch/troubleshooting-searches.md @@ -243,3 +243,5 @@ xpack.security.audit.logfile.events.emit_request_body: true ``` Refer to [Advanced tuning: finding and fixing slow Elasticsearch queries](https://www.elastic.co/blog/advanced-tuning-finding-and-fixing-slow-elasticsearch-queries) for more information. + +For {{esql}}-specific slow query diagnosis and prevention, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). From 53d76b3aff957c37a47f4c91d70fe0c97d01f3a0 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 16 Jun 2026 13:23:23 +0200 Subject: [PATCH 5/9] Add inline perf guide links to ES|QL visualizations and AI Assistant --- explore-analyze/visualize/esorql.md | 2 +- .../ai/generate-customize-learn-about-esorql-queries.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/explore-analyze/visualize/esorql.md b/explore-analyze/visualize/esorql.md index d0677a69c1..3f05dcaa97 100644 --- a/explore-analyze/visualize/esorql.md +++ b/explore-analyze/visualize/esorql.md @@ -41,7 +41,7 @@ You can then **Save** and add it to an existing or a new dashboard using the sav 2. Choose **ES|QL** under **Visualizations**. An ES|QL editor appears and lets you configure your query and its associated visualization. The **Suggestions** panel can help you find alternative ways to configure the visualization. ::::{tip} - Check the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) to get familiar with the syntax and optimize your query. + Check the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) to get familiar with the syntax, and refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for tips on writing fast queries. :::: 3. When editing your query or its configuration, run the query to update the preview of the visualization. diff --git a/solutions/security/ai/generate-customize-learn-about-esorql-queries.md b/solutions/security/ai/generate-customize-learn-about-esorql-queries.md index 4c64c620c1..4435128adc 100644 --- a/solutions/security/ai/generate-customize-learn-about-esorql-queries.md +++ b/solutions/security/ai/generate-customize-learn-about-esorql-queries.md @@ -17,7 +17,7 @@ Elastic AI Assistant can help you learn about and leverage the Elasticsearch Que * **Education and training**: AI Assistant can serve as a powerful {{esql}} learning tool. Ask it for examples, explanations of complex queries, and best practices. * **Writing new queries**: Prompt AI Assistant to provide a query that accomplishes a particular task, and it will generate a query matching your description. For example: "Write a query to identify documents with `curl.exe` usage and calculate the sum of `destination.bytes`" or "What query would return all user logins to [a host] in the last six hours?" -* **Providing feedback to optimize existing queries**: Send AI Assistant a query you want to work on and ask it for improvements, refactoring, a general assessment, or to optimize the query’s performance with large data sets. +* **Providing feedback to optimize existing queries**: Send AI Assistant a query you want to work on and ask it for improvements, refactoring, a general assessment, or to optimize the query’s performance with large data sets. You can also refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for manual tuning techniques. * **Customizing queries for your environment**: Since each environment is unique, you may need to customize queries that you used in other contexts. AI Assistant can suggest necessary modifications based on contextual information you provide. * **Troubleshooting**: Having trouble with a query or getting unexpected results? Ask AI Assistant to help you troubleshoot. From 76ecbc690201422ce1ab09af8b79276e37dda683 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 16 Jun 2026 14:01:18 +0200 Subject: [PATCH 6/9] Add perf guide link to performance optimizations landing page --- deploy-manage/production-guidance/optimize-performance.md | 1 + 1 file changed, 1 insertion(+) diff --git a/deploy-manage/production-guidance/optimize-performance.md b/deploy-manage/production-guidance/optimize-performance.md index 1012ca025d..3fc3192c7a 100644 --- a/deploy-manage/production-guidance/optimize-performance.md +++ b/deploy-manage/production-guidance/optimize-performance.md @@ -26,6 +26,7 @@ Use the following topics to explore relevant strategies: * [Tune approximate kNN search](optimize-performance/approximate-knn-search.md) * [Tune for disk usage](optimize-performance/disk-usage.md) * [Size your shards](optimize-performance/size-shards.md) +* [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) ::::{note} Many {{es}} options come with different performance considerations and trade-offs. The best way to determine the optimal configuration for your use case is through [testing with your own data and queries](https://www.elastic.co/elasticon/conf/2016/sf/quantitative-cluster-sizing). From 3d31850773dc1912d32f7da31780bdbd7ce9a56d Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 16 Jun 2026 14:09:34 +0200 Subject: [PATCH 7/9] Add perf guide link to Using ES|QL tutorial --- explore-analyze/discover/try-esql.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/explore-analyze/discover/try-esql.md b/explore-analyze/discover/try-esql.md index 35d52ed270..9e60bfde20 100644 --- a/explore-analyze/discover/try-esql.md +++ b/explore-analyze/discover/try-esql.md @@ -20,7 +20,7 @@ Elasticsearch Query Language ({{esql}}) helps you explore and analyze your {{pro The examples on this page use the {{product.kibana}} sample web logs to explore data and create visualizations. You can install sample data by following [Add sample data](../index.md#gs-get-data-into-kibana). ::::{tip} -For the complete {{esql}} documentation, including all supported commands, functions, and operators, refer to the [{{esql}} reference](elasticsearch://reference/query-languages/esql/esql-syntax-reference.md). For a more detailed overview of {{esql}} in {{product.kibana}}, refer to [Use {{esql}} in Kibana](../query-filter/languages/esql-kibana.md). +For the complete {{esql}} documentation, including all supported commands, functions, and operators, refer to the [{{esql}} reference](elasticsearch://reference/query-languages/esql/esql-syntax-reference.md). For a more detailed overview of {{esql}} in {{product.kibana}}, refer to [Use {{esql}} in Kibana](../query-filter/languages/esql-kibana.md). For tips on writing fast queries, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). :::: From d354dfb41bbe7d827f3bde3ca364bd70758b7feb Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 17 Jun 2026 09:06:26 +0200 Subject: [PATCH 8/9] Address reviewer feedback on ES|QL performance guide cross-links - Fix esql-for-security.md link style to match sibling pattern - Remove autoops.md Related pages section (too prominent) - Nest ES|QL link under "Tune for search speed" in optimize-performance.md - Convert try-esql.md tip additions into dedicated Resources section - Simplify esorql.md link to use existing "optimize your query" text - Move perf link from standalone subsection to Tutorials in esql-for-search.md - Remove link from AI use cases page (generate-customize-learn-about-esorql-queries.md) - Move ES|QL item to end of circuit-breaker prevention list, generalize heading - Add ES|QL perf guide link to high-jvm-memory-pressure.md Co-Authored-By: Claude Opus 4.6 --- deploy-manage/monitor/autoops.md | 6 +----- .../production-guidance/optimize-performance.md | 4 +++- explore-analyze/discover/try-esql.md | 10 +++++++++- explore-analyze/visualize/esorql.md | 2 +- solutions/search/esql-for-search.md | 3 --- .../generate-customize-learn-about-esorql-queries.md | 2 +- solutions/security/esql-for-security.md | 2 +- troubleshoot/elasticsearch/circuit-breaker-errors.md | 8 ++++---- troubleshoot/elasticsearch/high-jvm-memory-pressure.md | 2 +- 9 files changed, 21 insertions(+), 18 deletions(-) diff --git a/deploy-manage/monitor/autoops.md b/deploy-manage/monitor/autoops.md index abdda2c083..ed1e952a82 100644 --- a/deploy-manage/monitor/autoops.md +++ b/deploy-manage/monitor/autoops.md @@ -75,8 +75,4 @@ In this section, you'll find the following information: * [Regions](/deploy-manage/monitor/autoops/ec-autoops-regions.md) where AutoOps is available. * Which [views](/deploy-manage/monitor/autoops/views.md) AutoOps offers to gain insight into your deployment. * What AutoOps [events](/deploy-manage/monitor/autoops/ec-autoops-events.md) are and how you can configure [event settings](/deploy-manage/monitor/autoops/ec-autoops-event-settings.md) and [notifications](/deploy-manage/monitor/autoops/ec-autoops-notifications-settings.md). -* [Frequently asked questions](/deploy-manage/monitor/autoops/ec-autoops-faq.md) about AutoOps. - -## Related pages - -* [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md): AutoOps detects common {{esql}} anti-patterns automatically. This guide covers the patterns and how to fix them. +* [Frequently asked questions](/deploy-manage/monitor/autoops/ec-autoops-faq.md) about AutoOps. \ No newline at end of file diff --git a/deploy-manage/production-guidance/optimize-performance.md b/deploy-manage/production-guidance/optimize-performance.md index 3fc3192c7a..d1b14fda40 100644 --- a/deploy-manage/production-guidance/optimize-performance.md +++ b/deploy-manage/production-guidance/optimize-performance.md @@ -23,10 +23,12 @@ Use the following topics to explore relevant strategies: * [General recommendations](general-recommendations.md) * [Tune for indexing speed](optimize-performance/indexing-speed.md) * [Tune for search speed](optimize-performance/search-speed.md) + + For additional guidance specific to {{esql}} queries, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). + * [Tune approximate kNN search](optimize-performance/approximate-knn-search.md) * [Tune for disk usage](optimize-performance/disk-usage.md) * [Size your shards](optimize-performance/size-shards.md) -* [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) ::::{note} Many {{es}} options come with different performance considerations and trade-offs. The best way to determine the optimal configuration for your use case is through [testing with your own data and queries](https://www.elastic.co/elasticon/conf/2016/sf/quantitative-cluster-sizing). diff --git a/explore-analyze/discover/try-esql.md b/explore-analyze/discover/try-esql.md index 9e60bfde20..d750b86a17 100644 --- a/explore-analyze/discover/try-esql.md +++ b/explore-analyze/discover/try-esql.md @@ -20,9 +20,17 @@ Elasticsearch Query Language ({{esql}}) helps you explore and analyze your {{pro The examples on this page use the {{product.kibana}} sample web logs to explore data and create visualizations. You can install sample data by following [Add sample data](../index.md#gs-get-data-into-kibana). ::::{tip} -For the complete {{esql}} documentation, including all supported commands, functions, and operators, refer to the [{{esql}} reference](elasticsearch://reference/query-languages/esql/esql-syntax-reference.md). For a more detailed overview of {{esql}} in {{product.kibana}}, refer to [Use {{esql}} in Kibana](../query-filter/languages/esql-kibana.md). For tips on writing fast queries, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). +For the complete {{esql}} documentation, including all supported commands, functions, and operators, refer to the [{{esql}} reference](elasticsearch://reference/query-languages/esql/esql-syntax-reference.md). For a more detailed overview of {{esql}} in {{product.kibana}}, refer to [Use {{esql}} in Kibana](../query-filter/languages/esql-kibana.md). :::: +## Resources + +This tutorial covers the basics of querying data with {{esql}} in Discover. For more information, refer to: + +* [{{esql}} reference](elasticsearch://reference/query-languages/esql/esql-syntax-reference.md): Complete list of commands, functions, and operators +* [Use {{esql}} in Kibana](../query-filter/languages/esql-kibana.md): Detailed overview of {{esql}} features in {{product.kibana}} +* [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md): Techniques for writing fast queries + ## Get started with {{esql}} in Discover [tutorial-try-esql] diff --git a/explore-analyze/visualize/esorql.md b/explore-analyze/visualize/esorql.md index 3f05dcaa97..f3c8ed96cb 100644 --- a/explore-analyze/visualize/esorql.md +++ b/explore-analyze/visualize/esorql.md @@ -41,7 +41,7 @@ You can then **Save** and add it to an existing or a new dashboard using the sav 2. Choose **ES|QL** under **Visualizations**. An ES|QL editor appears and lets you configure your query and its associated visualization. The **Suggestions** panel can help you find alternative ways to configure the visualization. ::::{tip} - Check the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) to get familiar with the syntax, and refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for tips on writing fast queries. + Check the [ES|QL reference](elasticsearch://reference/query-languages/esql.md) to get familiar with the syntax and [optimize your query](elasticsearch://reference/query-languages/esql/esql-query-performance.md). :::: 3. When editing your query or its configuration, run the query to update the preview of the visualization. diff --git a/solutions/search/esql-for-search.md b/solutions/search/esql-for-search.md index 1132f980d1..ac40c335ff 100644 --- a/solutions/search/esql-for-search.md +++ b/solutions/search/esql-for-search.md @@ -197,9 +197,6 @@ The [`MMR` command](elasticsearch://reference/query-languages/esql/commands/mmr. ### Tutorials and how-to guides [esql-for-search-tutorials] - [Search and filter with {{esql}}](elasticsearch://reference/query-languages/esql/esql-search-tutorial.md): Hands-on tutorial for getting started with search tools in {{esql}}, with concrete examples of the functionalities described in this page - -### Performance [esql-for-search-performance] - - [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md): Techniques for writing fast queries, including using full-text search functions instead of `LIKE` or `RLIKE` ### Technical reference [esql-for-search-reference] diff --git a/solutions/security/ai/generate-customize-learn-about-esorql-queries.md b/solutions/security/ai/generate-customize-learn-about-esorql-queries.md index 4435128adc..4c64c620c1 100644 --- a/solutions/security/ai/generate-customize-learn-about-esorql-queries.md +++ b/solutions/security/ai/generate-customize-learn-about-esorql-queries.md @@ -17,7 +17,7 @@ Elastic AI Assistant can help you learn about and leverage the Elasticsearch Que * **Education and training**: AI Assistant can serve as a powerful {{esql}} learning tool. Ask it for examples, explanations of complex queries, and best practices. * **Writing new queries**: Prompt AI Assistant to provide a query that accomplishes a particular task, and it will generate a query matching your description. For example: "Write a query to identify documents with `curl.exe` usage and calculate the sum of `destination.bytes`" or "What query would return all user logins to [a host] in the last six hours?" -* **Providing feedback to optimize existing queries**: Send AI Assistant a query you want to work on and ask it for improvements, refactoring, a general assessment, or to optimize the query’s performance with large data sets. You can also refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for manual tuning techniques. +* **Providing feedback to optimize existing queries**: Send AI Assistant a query you want to work on and ask it for improvements, refactoring, a general assessment, or to optimize the query’s performance with large data sets. * **Customizing queries for your environment**: Since each environment is unique, you may need to customize queries that you used in other contexts. AI Assistant can suggest necessary modifications based on contextual information you provide. * **Troubleshooting**: Having trouble with a query or getting unexpected results? Ask AI Assistant to help you troubleshoot. diff --git a/solutions/security/esql-for-security.md b/solutions/security/esql-for-security.md index ae49e1ad8f..e9d256f32d 100644 --- a/solutions/security/esql-for-security.md +++ b/solutions/security/esql-for-security.md @@ -23,4 +23,4 @@ Learn how to: - [Investigate events in Timeline](/solutions/security/investigate/timeline.md#esql-in-timeline) using {{esql}} - [Create detection rules](/solutions/security/detect-and-alert/esql.md) using {{esql}} - [Convert Splunk SPL rules to {{esql}}](/solutions/security/get-started/automatic-migration.md) with Automatic Migration -- [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md): Write faster queries for threat hunting and detection rules \ No newline at end of file +- [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) to write faster queries for threat hunting and detection rules \ No newline at end of file diff --git a/troubleshoot/elasticsearch/circuit-breaker-errors.md b/troubleshoot/elasticsearch/circuit-breaker-errors.md index 390762a637..77b1c659f3 100644 --- a/troubleshoot/elasticsearch/circuit-breaker-errors.md +++ b/troubleshoot/elasticsearch/circuit-breaker-errors.md @@ -99,10 +99,6 @@ GET _nodes/stats/breaker High JVM memory pressure often causes circuit breaker errors. See [High JVM memory pressure](high-jvm-memory-pressure.md). -**Optimize {{esql}} queries** - -High-cardinality {{esql}} aggregations are a common trigger for circuit breaker errors. Refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for techniques to reduce memory usage, including avoiding high-cardinality `STATS BY` groupings. - **Avoid using fielddata on `text` fields** For high-cardinality `text` fields, fielddata can use a large amount of JVM memory. To avoid this, {{es}} disables fielddata on `text` fields by default. If you’ve enabled fielddata and triggered the [fielddata circuit breaker](elasticsearch://reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#fielddata-circuit-breaker), consider disabling it and using a `keyword` field instead. See [`fielddata` mapping parameter](elasticsearch://reference/elasticsearch/mapping-reference/text.md#fielddata-mapping-param). @@ -115,6 +111,10 @@ If you’ve triggered the fielddata circuit breaker and can’t disable fielddat POST _cache/clear?fielddata=true ``` +**Optimize expensive queries** + +Both Query DSL and {{esql}} queries can trigger circuit breaker errors when they consume large amounts of memory. For {{esql}}, high-cardinality `STATS BY` groupings are a common cause. Refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for techniques to reduce memory usage. + ## Memory evaluation Circuit breakers may either directly evaluate memory usage estimates or indirectly limit operations that are likely to cause excessive memory consumption. For example, the `script` circuit breaker checks memory indirectly by rate-limiting Painless/Mustache script compilations. However, even with circuit breakers in place, nodes can still encounter out-of-memory (OOM) conditions. This can occur, for example, because: diff --git a/troubleshoot/elasticsearch/high-jvm-memory-pressure.md b/troubleshoot/elasticsearch/high-jvm-memory-pressure.md index d4e45ff428..3c2f622767 100644 --- a/troubleshoot/elasticsearch/high-jvm-memory-pressure.md +++ b/troubleshoot/elasticsearch/high-jvm-memory-pressure.md @@ -170,7 +170,7 @@ This section contains some common suggestions for reducing JVM memory pressure r Expensive searches can use large amounts of memory. To better track expensive searches on your cluster, enable [slow logs](/deploy-manage/monitor/logging-configuration/slow-logs.md). -Expensive searches may have a large [`size` argument](elasticsearch://reference/elasticsearch/rest-apis/paginate-search-results.md), use aggregations with a large number of buckets, or include [expensive queries](../../explore-analyze/query-filter/languages/querydsl.md#query-dsl-allow-expensive-queries). To prevent expensive searches, consider the following setting changes: +Expensive searches may have a large [`size` argument](elasticsearch://reference/elasticsearch/rest-apis/paginate-search-results.md), use aggregations with a large number of buckets, or include [expensive queries](../../explore-analyze/query-filter/languages/querydsl.md#query-dsl-allow-expensive-queries). For {{esql}}-specific guidance, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). To prevent expensive searches, consider the following setting changes: * Lower the `size` limit using the [`index.max_result_window`](elasticsearch://reference/elasticsearch/index-settings/index-modules.md#index-max-result-window) index setting. * Decrease the maximum number of allowed aggregation buckets using the [search.max_buckets](elasticsearch://reference/elasticsearch/configuration-reference/search-settings.md#search-settings-max-buckets) cluster setting. From c46245a87477d10e59c67e7da07324115250f9ea Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 18 Jun 2026 09:51:02 +0200 Subject: [PATCH 9/9] Address second round of reviewer feedback - try-esql.md: Remove duplicated links from tip (now only in Resources) - circuit-breaker-errors.md: Add Query DSL link to pair with ES|QL link - high-jvm-memory-pressure.md: Move ES|QL link after settings block as tip Co-Authored-By: Bad Claude --- explore-analyze/discover/try-esql.md | 4 ---- troubleshoot/elasticsearch/circuit-breaker-errors.md | 2 +- troubleshoot/elasticsearch/high-jvm-memory-pressure.md | 6 +++++- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/explore-analyze/discover/try-esql.md b/explore-analyze/discover/try-esql.md index d750b86a17..b44bb450a7 100644 --- a/explore-analyze/discover/try-esql.md +++ b/explore-analyze/discover/try-esql.md @@ -19,10 +19,6 @@ Elasticsearch Query Language ({{esql}}) helps you explore and analyze your {{pro - You must have data in {{product.elasticsearch}}. The examples on this page use the {{product.kibana}} sample web logs to explore data and create visualizations. You can install sample data by following [Add sample data](../index.md#gs-get-data-into-kibana). -::::{tip} -For the complete {{esql}} documentation, including all supported commands, functions, and operators, refer to the [{{esql}} reference](elasticsearch://reference/query-languages/esql/esql-syntax-reference.md). For a more detailed overview of {{esql}} in {{product.kibana}}, refer to [Use {{esql}} in Kibana](../query-filter/languages/esql-kibana.md). -:::: - ## Resources This tutorial covers the basics of querying data with {{esql}} in Discover. For more information, refer to: diff --git a/troubleshoot/elasticsearch/circuit-breaker-errors.md b/troubleshoot/elasticsearch/circuit-breaker-errors.md index 77b1c659f3..c2825f70e2 100644 --- a/troubleshoot/elasticsearch/circuit-breaker-errors.md +++ b/troubleshoot/elasticsearch/circuit-breaker-errors.md @@ -113,7 +113,7 @@ POST _cache/clear?fielddata=true **Optimize expensive queries** -Both Query DSL and {{esql}} queries can trigger circuit breaker errors when they consume large amounts of memory. For {{esql}}, high-cardinality `STATS BY` groupings are a common cause. Refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for techniques to reduce memory usage. +Both [Query DSL](../../explore-analyze/query-filter/languages/querydsl.md) and {{esql}} queries can trigger circuit breaker errors when they consume large amounts of memory. For {{esql}}, high-cardinality `STATS BY` groupings are a common cause. Refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md) for techniques to reduce memory usage. ## Memory evaluation diff --git a/troubleshoot/elasticsearch/high-jvm-memory-pressure.md b/troubleshoot/elasticsearch/high-jvm-memory-pressure.md index 3c2f622767..709fba26cc 100644 --- a/troubleshoot/elasticsearch/high-jvm-memory-pressure.md +++ b/troubleshoot/elasticsearch/high-jvm-memory-pressure.md @@ -170,7 +170,7 @@ This section contains some common suggestions for reducing JVM memory pressure r Expensive searches can use large amounts of memory. To better track expensive searches on your cluster, enable [slow logs](/deploy-manage/monitor/logging-configuration/slow-logs.md). -Expensive searches may have a large [`size` argument](elasticsearch://reference/elasticsearch/rest-apis/paginate-search-results.md), use aggregations with a large number of buckets, or include [expensive queries](../../explore-analyze/query-filter/languages/querydsl.md#query-dsl-allow-expensive-queries). For {{esql}}-specific guidance, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). To prevent expensive searches, consider the following setting changes: +Expensive searches may have a large [`size` argument](elasticsearch://reference/elasticsearch/rest-apis/paginate-search-results.md), use aggregations with a large number of buckets, or include [expensive queries](../../explore-analyze/query-filter/languages/querydsl.md#query-dsl-allow-expensive-queries). To prevent expensive searches, consider the following setting changes: * Lower the `size` limit using the [`index.max_result_window`](elasticsearch://reference/elasticsearch/index-settings/index-modules.md#index-max-result-window) index setting. * Decrease the maximum number of allowed aggregation buckets using the [search.max_buckets](elasticsearch://reference/elasticsearch/configuration-reference/search-settings.md#search-settings-max-buckets) cluster setting. @@ -193,6 +193,10 @@ PUT _cluster/settings } ``` +::::{tip} +For {{esql}}-specific guidance on writing efficient queries, refer to [Optimize {{esql}} query performance](elasticsearch://reference/query-languages/esql/esql-query-performance.md). +:::: + #### Prevent mapping explosion [reduce-jvm-memory-pressure-setup-mapping] Defining too many fields or nesting fields too deeply can lead to [mapping explosions](/troubleshoot/elasticsearch/mapping-explosion.md) that use large amounts of memory. To prevent mapping explosions, use the [mapping limit settings](elasticsearch://reference/elasticsearch/index-settings/mapping-limit.md) to limit the number of field mappings.