Search optimization page should be broken down by type of optimization

[shainaraskas]

inspired by #6932 (comment)

language-specific optimizations are mixed in with hardware optimizations. let's reorg this page so we have the hardware optimizations, a clearly language-identified section, and links to other language-specific optimization sections like the ES|QL optimizations page. this will stop people who use other languages/endpoints from starting wild goose chases

---

Elastic Docs AI Scoping 🤖

Docs issue scope

Summary

The issue asks for a structural reorganization of the "Tune for search speed" page (deploy-manage/production-guidance/optimize-performance/search-speed.md) to separate hardware/infrastructure tuning from language-specific (Query DSL) optimizations, and to add cross-links to language-specific performance guides. The linked PR #6932 adds a minimal cross-link to the upcoming ES|QL query performance guide (elasticsearch#150360, not yet merged) but doesn't reorganize the page; the issue was opened after the reviewer noted at line 370 that ES|QL (and other non-DSL) users have no signal for which sections apply to them.

Request accuracy

Accurate — the current page mixes infrastructure-level tuning (filesystem cache, readahead, hardware, replicas) that applies to all query languages with Query DSL-specific techniques (document modeling, index_phrases, index_prefixes, constant_keyword, avoid scripts, search rounded dates, pre-index data) that do not apply to ES|QL or other query interfaces.

Next action for author

Restructure search-speed.md under clearly labeled H2 groups (e.g., "Infrastructure and hardware" and "Query DSL optimizations"), and add a language-specific callout or section near the top that links to ES|QL and other language-specific performance pages.

Impact: Medium

Scope boundary

The ES|QL performance content itself is out of scope here — that lives in elasticsearch#150360. This issue is only about reorganizing the existing search-speed.md page structure and adding cross-links.

Recommended documentation targets

Page	URL	Action	Impact	Confidence	Why this page?
Tune for search speed	https://www.elastic.co/docs/deploy-manage/production-guidance/optimize-performance/search-speed	Update existing page	Medium	High	This is the page with the structural problem — needs H2 grouping separating infrastructure from Query DSL-specific sections, plus a language-specific callout or intro blurb
ES performance optimizations (parent)	https://www.elastic.co/docs/deploy-manage/production-guidance/optimize-performance	Review only	Low	Medium	The parent page lists search-speed.md alongside indexing-speed.md; a short annotation noting that search-speed.md covers infrastructure tuning and Query DSL may improve navigation

Recommendations

1. Update search-speed.md: Add H2 grouping headers to separate the ~10 infrastructure/hardware sections from the ~10 Query DSL-specific sections. Suggested groups:
   • "Infrastructure and hardware tuning" (filesystem cache, readahead, faster hardware, force-merge, warm-up, index sorting, replicas, preference, timeout, open search contexts)
   • "Query DSL optimizations" (document modeling, search-as-few-fields, pre-index data, keyword mapping, avoid scripts, search rounded dates, Search Profiler, index_phrases, index_prefixes, constant_keyword)
2. Add a language-specific callout or intro blurb near the top of search-speed.md explaining that the Query DSL-specific section applies to Query DSL and is not relevant to ES|QL, and linking to the ES|QL performance guide (`(reference/redacted) once elasticsearch#150360 is merged.
3. Coordinate with PR Link to ES|QL query performance guide #6932: The ES|QL cross-link section already being added at line 370 by PR Link to ES|QL query performance guide #6932 may be superseded by or incorporated into this structural reorganization; the two changes should be reconciled.

Notes

• The infrastructure sections already carry {applies_to} YAML blocks for self-managed/ECK — those should be preserved during the restructuring.
• The "Query DSL optimizations" grouping sets a pattern for future language-specific sections (e.g., if a Painless or EQL perf guide is added later).
• The Search Profiler section works for Query DSL queries; ES|QL has its own profiling approach in the ES|QL guide — this is worth noting in a callout.
• Dependency: the ES|QL cross-link in recommendation 2 is blocked until elasticsearch#150360 merges, but the structural reorganization (recommendation 1) is independent and can proceed now.

Generated by Issue Scope Analyzer for issue #6943 · 184.9 AIC · ⌖ 18.2 AIC · ⊞ 29.3K · ◷

[github-actions]

Elastic Docs AI Menu

Check one box to run an AI workflow for this issue.

• Triage (docs-triage). Status: not started.
• Scope the docs work (docs-issue-scope). Status: completed. View progress.

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