Configure synonyms in Elasticsearch: post-review improvements - #7945
Open
leemthompo wants to merge 33 commits into
Open
Configure synonyms in Elasticsearch: post-review improvements#7945leemthompo wants to merge 33 commits into
leemthompo wants to merge 33 commits into
Conversation
- Standardize 'synonyms sets' to 'synonym sets' and 'synonyms set' to 'synonym set' throughout (matching the API spec convention) - Fix future tense to present tense: 'will be replaced' to 'are replaced', 'will automatically reload' to 'automatically reload', 'will remain' to 'remains' - Add missing terminal periods - Fix self-referencing full-relative-path link to a simple anchor - Add forward-link from Method 1 to Method 3 (file-based approach)
- Fix heading levels: H4 to H3 for 'Explicit mappings' and 'Equivalent mappings' (were skipping H3 under H2) - Remove hardcoded count from section intro - Rewrite overview to list 4 steps with jump links matching the body - Add prerequisites section with manage_search_synonyms privilege
- Remove section-level applies_to from Method 1 (Kibana UI) that wrongly restricted it to serverless only; the page-level tag already covers both stack and serverless - Add serverless: unavailable inline tag to the index-time bullet in Step 4 (serverless only supports search-time synonyms)
- Add synonym_graph search-only constraint: note that synonym_graph is for search analyzers only and synonym filter is required for index-time use - Fix circuit breaker accuracy: lenient defaults to the value of updateable, so the default behavior with updateable: true is to log and use an empty map, not to red-state the index - Convert circuit breaker note from admonition to inline prose with plain-language gloss, eliminating the stacked note+warning pattern - Trim invalid rules warning to essential sentence with reference link
- Remove forward-referencing sentence about equivalent synonyms - Simplify expand parameter detail to two-bullet summary with link to synonym graph token filter reference - Trim 30-line commented synonyms file example to short 8-line sample; link to reference for full format specification - Change code block language tag from markdown to text (Solr format where # is a comment, not a heading) - Surface search-time-only constraint in Step 1 as a note - Add link to synonyms API in Method 2
- Switch filter type from synonym to synonym_graph (consistent with the recommendation in Step 2) - Switch primary example from synonyms_path to synonyms_set so it works for API/UI users (the majority path) - Add file-based variant in a tab with serverless: unavailable tag - Add tokenizer: standard and lowercase filter for a realistic analyzer chain - Use console code blocks with PUT verb - Add query-time reference links for match, query_string, and simple_query_string queries with auto_generate_synonyms_phrase_query
- Add 'Search with synonyms in action' section with a match query example that demonstrates synonym expansion end-to-end - Add 'Next steps' section linking to API examples, token filter references, and text analysis overview
- Use backtick code formatting for search terms instead of quotation marks to avoid punctuation placement issues - Simplify 'A large number of' to 'Too many'
Contributor
Contributor
Elastic Docs Style Checker (Vale)Summary: 2 warnings, 1 suggestion found
|
| File | Line | Rule | Message |
|---|---|---|---|
| solutions/search/full-text/search-with-synonyms.md | 45 | Elastic.MenuArrows | Use '→' to separate menu items, not '' or '='. Example: Select Manage index → Add lifecycle policy. |
| solutions/search/full-text/search-with-synonyms.md | 45 | Elastic.MenuArrows | Use '→' to separate menu items, not '' or '='. Example: Select Manage index → Add lifecycle policy. |
💡 Suggestions (1): Optional style improvements. Apply when helpful.
| File | Line | Rule | Message |
|---|---|---|---|
| solutions/search/full-text/search-with-synonyms.md | 229 | Elastic.WordChoice | Consider using 'efficient, basic' instead of 'simple', unless the term is in the UI. |
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.
Contributor
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
- Rename H1 to 'Set up and search with synonyms in ES' - Replace bullet-list intro with two cohesive paragraphs: define synonyms, explain the value, frame the page scope - Move ECE custom-bundle note out of the opening (anchors kept as migration artifacts to avoid broken builds) - Use product substitution variables in headings
Replace 'equivalent synonyms' with 'equivalent mappings' throughout, matching the section heading and standard Elasticsearch terminology.
Collapse two near-identical tab panels into one example with a code annotation callout for the file-based variant. Add prose before the example calling out the synonyms_path alternative.
Replace four Method headings with a tab-set for cleaner navigation. Preserve BWC anchors using $$$ syntax for cross-repo links from elasticsearch reference pages.
Collapse detailed format examples and expand behavior into a two-bullet summary with a link to the synonym graph token filter reference for full details including WordNet format.
Replace verbose inline circuit breaker explanation with a brief mention and linked reference to the synonym graph token filter page.
Reorder so the index mapping (now Step 3) exists before testing the analyzer (now Step 4). Rewrite the test example to use the named my_analyzer on my-index instead of a throwaway inline filter chain. All examples verified end-to-end against a local ES cluster.
Add BWC anchor to Kibana UI tab and update the inbound link from elasticsearch-solution-project.md.
Mention that stop filter placement relative to synonym filters affects expansion, with a link to the reference section for details.
Scope to stack: ga 9.1 and serverless: ga instead of removing the tag entirely.
Use serverless: elasticsearch project type instead of bare serverless: ga. The synonyms UI is only available on serverless Elasticsearch (search) projects.
Add a code snippet showing the synonyms parameter, and link the warning to the API and file-based alternatives.
The warning about creating sets before referencing them belongs in Step 1 where sets are created, not Step 2.
Drop unexplained concept names from the link-out sentence.
Place it after the closing tab-set delimiter so it renders as a standalone warning at the end of Step 1.
The reference page already has proper version scoping on its circuit breaker section. No need to duplicate it on a brief pointer.
Rename heading and add jump link in the workflow overview so the search example is part of the continuous thread.
Rewrite Step 3 heading and trim to focus on creating the index. Move supported query types to Step 5 where the reader actually runs a search. Remove duplicated note about API/UI search-time constraint (already in Step 1).
- Rename H1 to 'Configure synonyms in ES' - Add navigation_title: Synonyms to frontmatter - Rename my_analyzer to synonyms_analyzer throughout - Move REST API tab first (recommended approach) - Add code annotations for search_analyzer and updateable - Consolidate file-based callout into annotation only - Convert search-time-only note to plain prose - Simplify synonym format reference link
Frame synonym benefits as things you can do by defining rules, not as automatic outcomes of enabling synonyms.
leemthompo
changed the title
leemthompo
marked this pull request as ready for review
August 14, 2026 14:24
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
solutions/search/full-text/search-with-synonyms.md
Summary
Addresses elastic/docs-content-internal#1624 — post-calibration review improvements to the Search with synonyms page.
Changes
Title and page opening
navigation_title: Synonymsnavigation_title: Synonym set API examplesto the child pagedescriptionfor SEOStructure and flow
manage_search_synonymscluster privilege)matchquery exampleTechnical accuracy
synonym_graph+synonyms_set(consistent with recommendation)my_analyzertosynonyms_analyzerthroughoutsynonyms_analyzeronmy-indexinstead of a throwaway inline filter chainlenientdefaults toupdateablevalue, trimmed to one sentence with reference linkmatch,query_string,simple_query_string) in Step 5Applicability
applies_to:stack: ga 9.1+serverless: elasticsearch:(was serverless-only)serverless: unavailableLanguage and style
markdown→text)importantadmonition<1>,<2>,<3>) instead of redundant tabbed examples in Step 3Companion PR
Follow-up
$$$anchor stubs (lines 20–25) are migration artifacts kept to prevent broken cross-repo references. Clean up separately once those references are resolved.Code verification
All code examples tested end-to-end against a local ES deployment:
synonym_graph+synonyms_setanalyzer ✅GET /my-index/_analyzewith namedsynonyms_analyzer) ✅