Reorganize search-speed.md by optimization type by georgewallace · Pull Request #8276 · elastic/docs-content

georgewallace · 2026-09-11T13:13:37Z

Made structural changes based on the issue suggestion. Decided to break it up into 3 sections because some of the query guidance is relevant to all query languages and some for Query DSL only. Did an SEO pass on the page and also validated the context in the doc with information from the elasticsearch repo to ensure it is correct.

What changed

search-speed.md: restructured from a flat list of ~20 H2 sections into three labeled groups:

Cluster and hardware tuning: applies to all query languages
Index design and maintenance: applies to all query languages, including ES|QL
Query DSL optimizations: Query DSL only

All 28 original anchors preserved verbatim (two are load-bearing cross-repo references from elasticsearch/node-settings.md and elasticsearch/copy-to.md).

Additional fixes made while restructuring:

applies_to validated against the elasticsearch repo; added ece: all to the filesystem cache section
Four correctness fixes: preload warning language, index_phrases terminology, index_prefixes scope, added diversified_sampler to the global ordinals aggregation list
H1 updated to "Tune Elasticsearch for search speed" (Pattern A per title guidance); navigation_title added to keep the sidebar label unchanged
Updated description frontmatter for SEO (leads with top-ranking queries: "elasticsearch performance tuning", "query optimization")
Style fixes throughout: active voice, present tense, contractions, wordiness, subjunctive mood

optimize-performance.md: removed the bullet and annotation for ES|QL. We already link to this topic from the search-speed page and other places, the annotation made the list render strangely. Looking at traffic data the vast majority of folks that landed on the es|ql performance page came from search-speed not from optimize performance.

Notes

Sibling pages (indexing-speed, disk-usage, etc.) still use "Tune for X" H1s without the product name, a follow-on will update those to Pattern A or Pattern B once meta_title ships in docs-builder.

🤖 Generated with Claude Code

…n type Resolves elastic#6943. The page was a flat list of ~20 H2 sections mixing infrastructure tuning, index design, and Query DSL-specific advice with no signal to readers using ES|QL or other query languages. Changes: - Add three H2 groups: Cluster and hardware tuning, Index design and maintenance (all query languages), and Query DSL optimizations (DSL only) - Demote existing H2s to H3; all existing anchor IDs carried over verbatim so inbound links from the elasticsearch repo are not broken - Add intro tip callout explaining which sections apply to which readers - Move index_phrases, constant_keyword, and index sorting to Index design group based on evidence from ES source that ES|QL benefits from them too - Move global ordinals to Query DSL group (ES|QL STATS BY uses its own impl) - Add cross-links to ES|QL and EQL performance guides in new Other query languages section - Add type and description frontmatter fields - Apply comprehensive style fixes: active voice, present tense, contractions, acronym expansions (JVM, LVM, SSD, ISBN, EQL), "in order to" → "to", "may" → "might" for possibility, directional "below" → "the following", "etc" → "and so on", fix broken Query DSL cross-link - Fix pre-existing "sharing strategies" typo → "sharding strategies" - Update parent optimize-performance.md annotation to reflect new structure Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ECE users configure JVM heap sizes directly (via --memory-settings and instance RAM selection), so this advice applies to ECE as well as self-managed and ECK. Verified against ece-jvm.md and resize-deployment.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Preload warning: rephrase from "too many files" to the actual condition (total preloaded data exceeds available RAM), per preloading docs - index_phrases: "2-shingles" -> "two-term word combinations (shingles)" to match ES source terminology in index-phrases.md - index_prefixes: clarify that only prefixes within the configured length range are indexed (2-5 chars by default), not all possible prefixes - Global ordinals: add diversified_sampler to the list of aggregations that use global ordinals, per eager-global-ordinals.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Rewrite the description to lead with the primary ranking queries (elasticsearch performance tuning, query optimization) and add latency/throughput signals to improve CTR from organic search. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- "in order to" → "to" (wordiness) - "what is" → "what's" (contraction) - "you'll write" → "you plan to write" (future tense → present) - "that is used" → "that's used" (contraction) - "should be mapped" → "needs to be mapped" (subjunctive) - "you could split" → "you can split" (subjunctive) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- H1: "Tune Elasticsearch for search speed" (includes product name per title guidance) - navigation_title: "Tune for search speed" (pins sidebar label, unchanged from before) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-09-11T13:18:12Z

Elastic Docs AI PR menu

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

Review docs changes (docs-review). Status: not started.

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

The annotation was redundant with the tip callout at the top of search-speed.md and read awkwardly as subordinate list text. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- "heavily relies" → "relies heavily" - Add missing comma after "For instance" Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions · 2026-09-11T13:37:14Z

🔍 Preview links for changed docs

github-actions · 2026-09-11T13:40:15Z

Elastic Docs Style Checker (Vale)

Summary: 3 warnings found

⚠️ Warnings (3): Fix when the suggestion improves clarity or correctness.

File	Line	Rule	Message
deploy-manage/production-guidance/optimize-performance/search-speed.md	385	Elastic.Spelling	'cacheable' is a possible misspelling.
deploy-manage/production-guidance/optimize-performance/search-speed.md	435	Elastic.Spelling	'cacheable' is a possible misspelling.
deploy-manage/production-guidance/optimize-performance/search-speed.md	435	Elastic.Spelling	'cacheable' is a possible misspelling.

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

shainaraskas

a very nice usability improvement! some thoughts around grouping and some stray things that I think might need small corrections

shainaraskas · 2026-09-22T18:48:55Z

-::::
+### Faster prefix queries with `index_prefixes` [faster-prefix-queries]

+The [`text`](elasticsearch://reference/elasticsearch/mapping-reference/text.md) field has an [`index_prefixes`](elasticsearch://reference/elasticsearch/mapping-reference/index-prefixes.md) option that indexes term prefixes within a configurable length range (two to five characters by default) and is automatically leveraged by query parsers to run prefix queries. If your use-case involves running lots of prefix queries, this can speed up queries significantly.


this is at index time, so even though it's most effective for querydsl, we might want to move it and just call it out as only helping for that language (I think we want to group by when/where the optimization is done)

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

- Add Search request tuning section (preference, timeout, open contexts) - Update tip to reference four groups with working links for all query languages - Make ES|QL and EQL heading names consistent - Add index_prefixes note clarifying Query DSL-only benefit - Restore ES|QL shortcut on optimize-performance.md, add EQL shortcut Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

georgewallace · 2026-09-23T14:50:25Z

@shainaraskas I made the changes you recommended .. Thank you for the thorough review.

shainaraskas

smallest little guys to think about before ship

shainaraskas · 2026-09-23T16:12:32Z



-## Warm up global ordinals [_warm_up_global_ordinals]
+### Warm up global ordinals [_warm_up_global_ordinals]


did you want to move this one to index time too or do you think it is better here?

So it is set per mapping which is index-y but it is focused on QueryDSL and hence why I kept it here due to aggregations.. But I could move it and just reference it is only for QueryDSL if you think that makes more sense.

I am not certain how people will use this page, but my guess is that they'd use it in stages - one stage when they're editing cluster settings, another when writing queries ... that's what I'm trying to optimize for. ultimately people might just be looking for specific tips at specific times though (e.g. guidance on using one setting) 🤷

I am going to leave it for now and ship and will ask the team after the merge so folks can see it in it's entirety and can discuss.

…speed.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

ECE does not allow independent allocation of filesystem cache memory — JVM heap is set automatically based on instance tier. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

georgewallace and others added 6 commits September 11, 2026 07:15

Update H1 to Pattern A and add navigation_title

11f47e1

- H1: "Tune Elasticsearch for search speed" (includes product name per title guidance) - navigation_title: "Tune for search speed" (pins sidebar label, unchanged from before) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

georgewallace force-pushed the gwallace/search-speed-reorg branch from 4b0f3d7 to 11f47e1 Compare September 11, 2026 13:17

georgewallace and others added 4 commits September 11, 2026 07:23

Remove annotation from search-speed bullet on parent page

4476269

The annotation was redundant with the tip callout at the top of search-speed.md and read awkwardly as subordinate list text. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Minor copy edits

a0c976f

- "heavily relies" → "relies heavily" - Add missing comma after "For instance" Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix broken anchor: other-query-languages → search-speed-other-languages

ecc2b92

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge branch 'main' into gwallace/search-speed-reorg

8a25a97

georgewallace marked this pull request as ready for review September 11, 2026 15:36

georgewallace requested a review from a team as a code owner September 11, 2026 15:36

shainaraskas approved these changes Sep 22, 2026

View reviewed changes

georgewallace and others added 3 commits September 23, 2026 08:16

Apply batched suggestions from code review

46d2adc

Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

Merge branch 'main' into gwallace/search-speed-reorg

65072a1

shainaraskas approved these changes Sep 23, 2026

View reviewed changes

georgewallace and others added 2 commits September 23, 2026 10:54

Update deploy-manage/production-guidance/optimize-performance/search-…

dc94cc3

…speed.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>

Remove ece applies_to tag from filesystem cache section

8a0d641

ECE does not allow independent allocation of filesystem cache memory — JVM heap is set automatically based on instance tier. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

georgewallace added this pull request to the merge queue Sep 23, 2026

Merged via the queue into elastic:main with commit 11f9628 Sep 23, 2026
12 checks passed

georgewallace deleted the gwallace/search-speed-reorg branch September 23, 2026 19:25



		## Warm up global ordinals [_warm_up_global_ordinals]
		### Warm up global ordinals [_warm_up_global_ordinals]

Conversation

georgewallace commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Notes

Uh oh!

github-actions Bot commented Sep 11, 2026

Elastic Docs AI PR menu

Uh oh!

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

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Sep 11, 2026

Elastic Docs Style Checker (Vale)

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shainaraskas Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

georgewallace commented Sep 23, 2026

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

shainaraskas Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

georgewallace Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

shainaraskas Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

georgewallace Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

georgewallace commented Sep 11, 2026 •

edited

Loading

github-actions Bot commented Sep 11, 2026 •

edited

Loading