Link to ES|QL query performance guide by leemthompo · Pull Request #6932 · elastic/docs-content

leemthompo · 2026-06-16T11:04:09Z

Summary

Companion to elastic/elasticsearch#150360.

Cross-links the new ES|QL query performance guide from docs-content pages that the guide references or that readers are likely to navigate from. Adds links to related pages, next steps, and prevention sections where appropriate.

Warning

Links to elasticsearch://reference/query-languages/esql/esql-query-performance.md will not resolve until elastic/elasticsearch#150360 is merged.

🤖 Generated with Claude Code

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.

github-actions · 2026-06-16T11:04:52Z

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

Review docs changes (docs-review). Status: queued.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

github-actions

Docs review summary

Focus areas

Style and clarity: The link additions are clean and contextually appropriate throughout. One formatting inconsistency found in solutions/security/esql-for-security.md (inline comment).
Jargon: ES|QL is the actual product/feature name and is used consistently with context; no unexplained jargon introduced.
Frontmatter and applies_to: No frontmatter changes in this PR; not affected.
Content type fit: All cross-links are placed in contextually appropriate sections (related pages, learn more, see also, troubleshooting resolutions). Content types are not disrupted.
Parent issue satisfaction: Not applicable — this PR is a companion to elastic/elasticsearch#150360 with no linked docs-content issue.

Nits

deploy-manage/monitor/query-activity.md, line 134: The three existing "see also" items use auto-title syntax [](path), while the new ES|QL link uses explicit text [Optimize {{esql}} query performance](...). Cross-repo `(redacted) links may not support auto-title, so this inconsistency could be unavoidable — worth a quick check.
explore-analyze/discover/try-esql.md, line 24: The tip admonition now has three "For X, refer to..." sentences. Still readable, but on the longer side for a tip block.
Vale flagged pre-existing may/disable/some of the patterns in several files — all in untouched lines, not introduced by this PR.

Notes

All 15 eligible changed files were reviewed. Vale findings were on untouched lines only and are not reported here.
Links to `(reference/redacted) will not resolve until the companion PR merges, as noted in the PR description.

Generated by Docs review agent for issue #6932 · 128.1 AIC · ⌖ 18.4 AIC · ⊞ 32.8K

shainaraskas

overall, I think you need more links to this page on more pages!!

thanks in advance!

- 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 <noreply@anthropic.com>

leemthompo · 2026-06-17T07:23:19Z

thank you @shainaraskas, addressed all feedback and suggestions in d354dfb

shainaraskas · 2026-06-17T17:18:16Z

 ::::{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


this is now duplicative of itself ! <- as was this sentence

what the H??????

shainaraskas · 2026-06-17T17:19:46Z


+**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.


we need a paired Querydsl link here

shainaraskas · 2026-06-17T17:20:20Z

 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:


this para now makes less sense because the esql thing is jammed in the middle

shainaraskas

tell claude he needs to do better

- 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 <noreply@anthropic.com>

leemthompo · 2026-06-18T07:52:48Z

Oopsie, sorry about that

shainaraskas

2/3 ain't bad claude

unblocking but I think we still have one more fix here

shainaraskas · 2026-06-18T21:12:38Z

 **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.


😭 this is not what I think we're aiming for. we're providing a super helpful link for esql techniques here, and we haaave a similar page for querydsl, so we should provide it (not just a random generic page for querydsl). I think the best link is /troubleshoot/elasticsearch/high-jvm-memory-pressure.md#reduce-jvm-memory-pressure-setup-searches but that's linked quite close by (could try to integrate this section better into those other sections to defray this / remove need for repetitive link). alt is that we just link to the search speed page (/deploy-manage/production-guidance/optimize-performance/search-speed) but that seems too high level for this context perhaps

leemthompo requested review from a team as code owners June 16, 2026 11:04

leemthompo mentioned this pull request Jun 16, 2026

Add ESQL query performance guide elastic/elasticsearch#150360

Open

leemthompo self-assigned this Jun 16, 2026

leemthompo added 6 commits June 16, 2026 13:17

Add perf guide link to query logging related pages

72ac49a

Add perf guide link to AutoOps overview

f652602

Add perf guide links to slow logs, search troubleshooting, Timeline

e3e3d82

Add inline perf guide links to ES|QL visualizations and AI Assistant

53d76b3

Add perf guide link to performance optimizations landing page

76ecbc6

Add perf guide link to Using ES|QL tutorial

3d31850

github-actions Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread solutions/security/esql-for-security.md Outdated

Comment thread deploy-manage/monitor/autoops.md Outdated

shainaraskas approved these changes Jun 16, 2026

View reviewed changes

shainaraskas mentioned this pull request Jun 16, 2026

Search optimization page should be broken down by type of optimization #6943

Open

shainaraskas reviewed Jun 17, 2026

View reviewed changes

shainaraskas requested changes Jun 17, 2026

View reviewed changes

shainaraskas approved these changes Jun 18, 2026

View reviewed changes


		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.

Conversation

leemthompo commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

github-actions Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Elastic Docs AI PR menu

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Docs review summary

Focus areas

Nits

Notes

Uh oh!

Uh oh!

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

leemthompo commented Jun 17, 2026

Uh oh!

shainaraskas Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

shainaraskas Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

leemthompo Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

shainaraskas Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

leemthompo Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

leemthompo commented Jun 18, 2026

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

shainaraskas Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

leemthompo commented Jun 16, 2026 •

edited

Loading

github-actions Bot commented Jun 16, 2026 •

edited

Loading

shainaraskas Jun 17, 2026 •

edited

Loading

shainaraskas Jun 18, 2026 •

edited

Loading