From b5fc7c81012f7e66a8e04cebe462697c3d9c3151 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:17:40 +0200 Subject: [PATCH 01/33] Standardize terminology, fix tense, and fix self-link - 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) --- .../search/full-text/search-with-synonyms.md | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 2beac16837..aa8fd77f38 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -55,8 +55,8 @@ sea biscuit, sea biscit => seabiscuit ``` With explicit mappings, the relationship is one-way. In the previous examples: -- `i-pod` and `i pod` will be replaced with `ipod`, but `ipod` will not be replaced with `i-pod` or `i pod` -- `sea biscuit` and `sea biscit` will be replaced with `seabiscuit`, but `seabiscuit` will not be replaced with `sea biscuit` or `sea biscit` +- `i-pod` and `i pod` are replaced with `ipod`, but `ipod` is not replaced with `i-pod` or `i pod`. +- `sea biscuit` and `sea biscit` are replaced with `seabiscuit`, but `seabiscuit` is not replaced with `sea biscuit` or `sea biscit`. This is different from equivalent synonyms, which can create bidirectional relationships when `expand=true`. @@ -104,14 +104,13 @@ To create a synonym set using the UI: - Add **Explicit rules** by adding multiple terms that map to a single term. For example: `i-pod, i pod => ipod` 5. Select **Save** to save your rules. -The UI supports the same synonym rule formats as the file-based approach. Changes made through the UI will automatically reload the associated analyzers. +The UI supports the same synonym rule formats as the [file-based approach](#synonyms-store-synonyms-file). Changes made through the UI automatically reload the associated analyzers. ### Method 2: REST API [synonyms-store-synonyms-api] -You can use the [synonyms APIs]({{es-apis}}group/endpoint-synonyms) to manage synonyms sets. This is the most flexible approach, as it allows you to dynamically define and modify synonyms sets. For examples of how to -create or update a synonym set with APIs, refer to the [Create or update synonyms set API examples](/solutions/search/full-text/create-update-synonyms-api-example.md) page. +You can use the [synonyms APIs]({{es-apis}}group/endpoint-synonyms) to manage synonym sets. This is the most flexible approach, as it allows you to dynamically define and modify synonym sets. For examples of how to create or update a synonym set with APIs, refer to the [Create or update synonym set API examples](/solutions/search/full-text/create-update-synonyms-api-example.md) page. -Changes in your synonyms sets will automatically reload the associated analyzers. +Changes to your synonym sets automatically reload the associated analyzers. ### Method 3: File-based [synonyms-store-synonyms-file] @@ -119,9 +118,9 @@ Changes in your synonyms sets will automatically reload the associated analyzers serverless: unavailable ``` -You can store your synonyms set in a file. +You can store your synonym set in a file. -Make sure you upload a synonyms set file for all your cluster nodes, to the configuration directory for your {{es}} distribution. If you're using {{ech}}, you can upload synonyms files using [custom bundles](../../../deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md). +Make sure you upload the synonym set file to all your cluster nodes, in the configuration directory for your {{es}} distribution. If you're using {{ech}}, you can upload synonyms files using [custom bundles](../../../deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md). An example of a synonyms file: @@ -159,11 +158,11 @@ foo => baz foo => foo bar, baz ``` -To update an existing synonyms set, upload new files to your cluster. Synonyms set files must be kept in sync on every cluster node. +To update an existing synonym set, upload new files to your cluster. Synonym set files must be kept in sync on every cluster node. -When a synonyms set is updated, search analyzers that use it need to be refreshed using the [reload search analyzers API]({{es-apis}}operation/operation-indices-reload-search-analyzers) +When a synonym set is updated, search analyzers that use it need to be refreshed using the [reload search analyzers API]({{es-apis}}operation/operation-indices-reload-search-analyzers). -This manual syncing and reloading makes this approach less flexible than using the [synonyms API](../../../solutions/search/full-text/search-with-synonyms.md#synonyms-store-synonyms-api). +This manual syncing and reloading makes this approach less flexible than using the [synonyms API](#synonyms-store-synonyms-api). ### Method 4: Inline [synonyms-store-synonyms-inline] @@ -175,10 +174,10 @@ Inline synonyms are not recommended for production usage. A large number of inli ## Step 2: Configure synonyms token filters and analyzers [synonyms-synonym-token-filters] -Once your synonyms sets are created, you can start configuring your token filters and analyzers to use them. +Once your synonym sets are created, you can start configuring your token filters and analyzers to use them. ::::{warning} -Synonyms sets must exist before they can be added to indices. If an index is created referencing a nonexistent synonyms set, the index will remain in a partially created and inoperable state. The only way to recover from this scenario is to ensure the synonyms set exists then either delete and re-create the index, or close and re-open the index. +Synonym sets must exist before they can be added to indices. If an index is created referencing a nonexistent synonym set, the index remains in a partially created and inoperable state. The only way to recover from this scenario is to ensure the synonym set exists then either delete and re-create the index, or close and re-open the index. :::: {{es}} uses synonyms as part of the [analysis process](../../../manage-data/data-store/text-analysis.md). You can use two types of [token filter](elasticsearch://reference/text-analysis/token-filter-reference.md) to include synonyms: @@ -239,10 +238,10 @@ You need to decide when to apply your synonyms: * **Index time**: Synonyms are applied when the documents are indexed into {{es}}. This is a less flexible alternative, as changes to your synonyms require [reindexing]({{es-apis}}operation/operation-reindex). * **Search time**: Synonyms are applied when a search is executed. This is a more flexible approach, which doesn't require reindexing. If token filters are configured with `"updateable": true`, search analyzers can be [reloaded]({{es-apis}}operation/operation-indices-reload-search-analyzers) when you make changes to your synonyms. :::{note} - Synonyms sets created using the synonyms API or the UI can only be used at search time. + Synonym sets created using the synonyms API or the UI can only be used at search time. ::: -You can specify the analyzer that contains your synonyms set as a [search time analyzer](../../../manage-data/data-store/text-analysis/specify-an-analyzer.md#specify-search-analyzer) or as an [index time analyzer](../../../manage-data/data-store/text-analysis/specify-an-analyzer.md#specify-index-time-analyzer). +You can specify the analyzer that contains your synonym set as a [search time analyzer](../../../manage-data/data-store/text-analysis/specify-an-analyzer.md#specify-search-analyzer) or as an [index time analyzer](../../../manage-data/data-store/text-analysis/specify-an-analyzer.md#specify-index-time-analyzer). The following example adds `my_analyzer` as a search analyzer to the `title` field in an index mapping: From bcc4467e3fca15c6d9c5ceb67e9520f1ba4c5a4b Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:18:12 +0200 Subject: [PATCH 02/33] Fix heading hierarchy and restructure page opening - 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 --- .../search/full-text/search-with-synonyms.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index aa8fd77f38..6de093adb4 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -31,21 +31,26 @@ Synonyms are words or phrases that share the same or similar meaning. Searching * Make domain-specific vocabulary more user-friendly. * Define misspellings and typos to transparently handle common mistakes. +## Prerequisites + +To manage synonym sets using the API or {{kib}} UI, you need the `manage_search_synonyms` [cluster privilege](elasticsearch://reference/elasticsearch/security-privileges.md). + ## How synonyms work in Elasticsearch To use synonyms in {{es}}, follow this workflow: -1. **Create synonym sets and rules**: Define which terms are equivalent and where to store your synonym sets. -2. **Configure analyzers**: Configure your token filters and analyzers to use them. -3. **Test and apply**: Verify your configuration works correctly. +1. [**Create synonym sets and rules**](#synonyms-store-synonyms): Define which terms are equivalent and how to store your synonym sets. +2. [**Configure token filters and analyzers**](#synonyms-synonym-token-filters): Set up synonym token filters and add them to your analyzers. +3. [**Test your analyzer**](#synonyms-test-analyzer): Verify your synonym configuration produces the expected tokens. +4. [**Apply synonyms at index or search time**](#synonyms-apply-synonyms): Specify your analyzer in your index mapping. ## Synonym rule formats Synonym rules define which terms should be treated as equivalent during search and indexing. -There are two main formats for synonym rules: explicit mappings and equivalent mappings. +Synonym rules use one of the following formats: -#### Explicit mappings +### Explicit mappings Explicit mappings use `=>` to specify exact replacements: @@ -60,7 +65,7 @@ With explicit mappings, the relationship is one-way. In the previous examples: This is different from equivalent synonyms, which can create bidirectional relationships when `expand=true`. -#### Equivalent mappings +### Equivalent mappings Equivalent synonyms use commas to group interchangeable terms: From 5ed44f4d9f9dc7da8a34b1a32c4618905f4b5d60 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:18:35 +0200 Subject: [PATCH 03/33] Fix applicability tags - 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) --- solutions/search/full-text/search-with-synonyms.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 6de093adb4..91962ffe9e 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -92,11 +92,6 @@ You have multiple options for creating synonym sets and rules. ### Method 1: {{kib}} UI -```yaml {applies_to} -serverless: - elasticsearch: -``` - You can create and manage synonym sets and synonym rules using the {{kib}} user interface. To create a synonym set using the UI: @@ -240,7 +235,7 @@ Analyzers can be applied at [index time or search time](../../../manage-data/dat You need to decide when to apply your synonyms: -* **Index time**: Synonyms are applied when the documents are indexed into {{es}}. This is a less flexible alternative, as changes to your synonyms require [reindexing]({{es-apis}}operation/operation-reindex). +* **Index time**: {applies_to}`serverless: unavailable` Synonyms are applied when the documents are indexed into {{es}}. This is a less flexible alternative, as changes to your synonyms require [reindexing]({{es-apis}}operation/operation-reindex). * **Search time**: Synonyms are applied when a search is executed. This is a more flexible approach, which doesn't require reindexing. If token filters are configured with `"updateable": true`, search analyzers can be [reloaded]({{es-apis}}operation/operation-indices-reload-search-analyzers) when you make changes to your synonyms. :::{note} Synonym sets created using the synonyms API or the UI can only be used at search time. From 4a5da0a99e7290788a21a20c65071d0c6a9cef48 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:19:05 +0200 Subject: [PATCH 04/33] Fix technical accuracy and unstick stacked admonitions - 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 --- .../search/full-text/search-with-synonyms.md | 27 ++++--------------- 1 file changed, 5 insertions(+), 22 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 91962ffe9e..4f414a7aa4 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -182,32 +182,15 @@ Synonym sets must exist before they can be added to indices. If an index is crea {{es}} uses synonyms as part of the [analysis process](../../../manage-data/data-store/text-analysis.md). You can use two types of [token filter](elasticsearch://reference/text-analysis/token-filter-reference.md) to include synonyms: -* [Synonym graph](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md): Recommended as it can correctly handle multi-word synonyms. -* [Synonym](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md): Not recommended if you need to use multi-word synonyms. +* [Synonym graph](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md): Recommended for search analyzers. Correctly handles multi-word synonyms. This filter is designed for search-time use only. +* [Synonym](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md): Required for index-time synonyms. Not recommended if you need to use multi-word synonyms. -Check each synonym token filter documentation for configuration details and instructions on adding it to an analyzer. +Refer to each token filter's reference page for configuration details and instructions on adding it to an analyzer. -:::{note} -:applies_to: {"stack": "ga 9.4", "serverless": "ga"} - -When building the synonyms map, {{es}} checks available heap memory using a circuit breaker to prevent synonym token filters from causing out-of-memory errors when processing large numbers of synonym rules. The circuit breaker trips when more than 95% of heap memory is in use. - -The threshold is configurable using the [`indices.breaker.total.limit` parent circuit breaker setting](elasticsearch://reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#parent-circuit-breaker). {applies_to}`serverless: unavailable` - -When the circuit breaker trips, the behavior is determined by the `lenient` parameter: - -* If `lenient` is `true`, an empty synonyms map is used and the event is logged in the {{es}} logs. -* If `lenient` is `false`, the affected index enters a red state. -::: +{applies_to}`{"stack": "ga 9.4", "serverless": "ga"}` When processing synonym rules, {{es}} uses a [circuit breaker](elasticsearch://reference/elasticsearch/configuration-reference/circuit-breaker-settings.md) (a memory safety mechanism) to prevent out-of-memory errors. If the circuit breaker trips because heap usage exceeds 95%, the behavior depends on the `lenient` parameter. The `lenient` parameter defaults to the value of `updateable`. When `updateable` is `true` (recommended for search-time synonyms), {{es}} uses an empty synonym map and logs the event. When `lenient` is `false`, the affected index enters a red state. The threshold is configurable using the [`indices.breaker.total.limit` setting](elasticsearch://reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#parent-circuit-breaker). {applies_to}`serverless: unavailable` ::::{warning} -Invalid synonym rules can cause errors when applying analyzer changes. For reloadable analyzers, this prevents reloading and applying changes. You must correct errors in the synonym rules and reload the analyzer. - -An index with invalid synonym rules cannot be reopened, making it inoperable when: - -* A node containing the index starts -* The index is opened from a closed state -* A node restart occurs (which reopens the node assigned shards) +Invalid synonym rules can cause errors when applying analyzer changes and can prevent an index from being reopened. Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference for details. :::: ## Step 3: Test your analyzer [synonyms-test-analyzer] From 9e60910d3490c40acdcd1f4e34e24f85d0df1876 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:20:37 +0200 Subject: [PATCH 05/33] Trim duplicated content and defer to reference pages - 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 --- .../search/full-text/search-with-synonyms.md | 50 ++++++------------- 1 file changed, 14 insertions(+), 36 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 4f414a7aa4..3a2a0fdde3 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -63,8 +63,6 @@ With explicit mappings, the relationship is one-way. In the previous examples: - `i-pod` and `i pod` are replaced with `ipod`, but `ipod` is not replaced with `i-pod` or `i pod`. - `sea biscuit` and `sea biscit` are replaced with `seabiscuit`, but `seabiscuit` is not replaced with `sea biscuit` or `sea biscit`. -This is different from equivalent synonyms, which can create bidirectional relationships when `expand=true`. - ### Equivalent mappings Equivalent synonyms use commas to group interchangeable terms: @@ -77,19 +75,19 @@ lol, laughing out loud ``` The behavior of equivalent synonyms depends on the `expand` parameter in your token filter configuration: -- If `expand=true`: `ipod, i-pod, i pod` creates bidirectional mappings: - - `ipod` ↔ `i-pod` - - `ipod` ↔ `i pod` - - `i-pod` ↔ `i pod` -- If `expand=false`: `ipod, i-pod, i pod` maps all terms to the first term as canonical: - - `ipod` → `ipod` - - `i-pod` → `ipod` - - `i pod` → `ipod` +- If `expand=true` (the default): all terms are mapped to each other bidirectionally. +- If `expand=false`: all terms are mapped to the first term only. + +For details on how `expand` affects synonym rules, refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference. ## Step 1: Create synonym sets and rules [synonyms-store-synonyms] You have multiple options for creating synonym sets and rules. +::::{note} +Synonym sets created through the API or the {{kib}} UI can only be used at search time. For index-time synonyms, use a [file-based](#synonyms-store-synonyms-file) or [inline](#synonyms-store-synonyms-inline) approach with the [`synonym` token filter](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md). +:::: + ### Method 1: {{kib}} UI You can create and manage synonym sets and synonym rules using the {{kib}} user interface. @@ -122,42 +120,22 @@ You can store your synonym set in a file. Make sure you upload the synonym set file to all your cluster nodes, in the configuration directory for your {{es}} distribution. If you're using {{ech}}, you can upload synonyms files using [custom bundles](../../../deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md). -An example of a synonyms file: +An example of a synonym file: -```markdown +```text # Blank lines and lines starting with pound are comments. -# Explicit mappings match any token sequence on the left hand side of "=>" -# and replace with all alternatives on the right hand side. -# These types of mappings ignore the expand parameter in the schema. -# Examples: +# Explicit mappings i-pod, i pod => ipod sea biscuit, sea biscit => seabiscuit -# Equivalent synonyms may be separated with commas and give -# no explicit mapping. In this case the mapping behavior will -# be taken from the expand parameter in the token filter configuration. -# This allows the same synonym file to be used in different synonym handling strategies. -# Examples: +# Equivalent synonyms ipod, i-pod, i pod -foozball, foosball universe, cosmos -lol, laughing out loud - -# If expand==true in the synonym token filter configuration, -# "ipod, i-pod, i pod" is equivalent to the explicit mapping: -ipod, i-pod, i pod => ipod, i-pod, i pod -# If expand==false, "ipod, i-pod, i pod" is equivalent -# to the explicit mapping: -ipod, i-pod, i pod => ipod - -# Multiple synonym mapping entries are merged. -foo => foo bar -foo => baz -# is equivalent to -foo => foo bar, baz ``` +For the full synonym file format specification, including `expand` behavior and rule merging, refer to the [synonym token filter](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md) reference. + To update an existing synonym set, upload new files to your cluster. Synonym set files must be kept in sync on every cluster node. When a synonym set is updated, search analyzers that use it need to be refreshed using the [reload search analyzers API]({{es-apis}}operation/operation-indices-reload-search-analyzers). From db776edfe932cfd1e3fd56e3a341cac52183ecd0 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:21:12 +0200 Subject: [PATCH 06/33] Rewrite Step 4 example for consistency and completeness - 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 --- .../search/full-text/search-with-synonyms.md | 57 +++++++++++++++++-- 1 file changed, 51 insertions(+), 6 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 3a2a0fdde3..3f09940a38 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -204,9 +204,53 @@ You need to decide when to apply your synonyms: You can specify the analyzer that contains your synonym set as a [search time analyzer](../../../manage-data/data-store/text-analysis/specify-an-analyzer.md#specify-search-analyzer) or as an [index time analyzer](../../../manage-data/data-store/text-analysis/specify-an-analyzer.md#specify-index-time-analyzer). +Queries that support synonym expansion include [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md), [query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-query-string-query.md), and [simple_query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-simple-query-string-query.md). These queries support the `auto_generate_synonyms_phrase_query` parameter, which controls how multi-word synonyms are handled at query time. + The following example adds `my_analyzer` as a search analyzer to the `title` field in an index mapping: -```JSON +::::{tab-set} + +:::{tab-item} API or UI synonym set +```console +PUT /my-index +{ + "mappings": { + "properties": { + "title": { + "type": "text", + "search_analyzer": "my_analyzer" + } + } + }, + "settings": { + "analysis": { + "analyzer": { + "my_analyzer": { + "tokenizer": "standard", + "filter": ["lowercase", "synonyms_filter"] + } + }, + "filter": { + "synonyms_filter": { + "type": "synonym_graph", + "synonyms_set": "my-synonym-set", + "updateable": true + } + } + } + } +} +``` +::: + +:::{tab-item} File-based synonym set + +```{applies_to} +serverless: unavailable +``` + +```console +PUT /my-index { "mappings": { "properties": { @@ -220,15 +264,13 @@ The following example adds `my_analyzer` as a search analyzer to the `title` fie "analysis": { "analyzer": { "my_analyzer": { - "tokenizer": "whitespace", - "filter": [ - "synonyms_filter" - ] + "tokenizer": "standard", + "filter": ["lowercase", "synonyms_filter"] } }, "filter": { "synonyms_filter": { - "type": "synonym", + "type": "synonym_graph", "synonyms_path": "analysis/synonym-set.txt", "updateable": true } @@ -237,3 +279,6 @@ The following example adds `my_analyzer` as a search analyzer to the `title` fie } } ``` +::: + +:::: From db989388cba38c00a12398b0d80b3e9dcdba8658 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:21:36 +0200 Subject: [PATCH 07/33] Add search example and next steps sections - 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 --- .../search/full-text/search-with-synonyms.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 3f09940a38..7100e5fe26 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -282,3 +282,27 @@ PUT /my-index ::: :::: + +## Search with synonyms in action [synonyms-search-example] + +After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. For example, if you define `laptop, notebook` as equivalent synonyms and search for "laptop", {{es}} also matches documents containing "notebook". + +```console +GET /my-index/_search +{ + "query": { + "match": { + "title": "laptop" + } + } +} +``` + +This query matches documents where the `title` field contains "laptop" or "notebook", because the synonym rule treats them as equivalent. + +## Next steps + +* [Create or update synonym set API examples](/solutions/search/full-text/create-update-synonyms-api-example.md): Practical examples of managing synonym sets through the API. +* [Synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md): Full reference for the recommended synonym token filter. +* [Synonym token filter](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md): Reference for the standard synonym token filter, required for index-time synonyms. +* [Text analysis](../../../manage-data/data-store/text-analysis.md): Learn more about analyzers, tokenizers, and token filters. From 7027816f7b7b8cc587fac0c57a80ebed23c8193b Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:21:50 +0200 Subject: [PATCH 08/33] Add frontmatter meta description for SEO --- solutions/search/full-text/search-with-synonyms.md | 1 + 1 file changed, 1 insertion(+) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 7100e5fe26..04bb53df36 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -1,6 +1,7 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/search-with-synonyms.html +description: Learn how to define synonym sets, configure synonym token filters and analyzers, and apply synonyms at search time or index time in Elasticsearch. applies_to: stack: serverless: From 21d00528f88f15327b1bdabefc902ac3763b8ce9 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 15:26:59 +0200 Subject: [PATCH 09/33] Fix Vale warnings - Use backtick code formatting for search terms instead of quotation marks to avoid punctuation placement issues - Simplify 'A large number of' to 'Too many' --- solutions/search/full-text/search-with-synonyms.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 04bb53df36..a5b3ea669c 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -148,7 +148,7 @@ This manual syncing and reloading makes this approach less flexible than using t You can test your synonyms by adding them directly inline in your token filter definition. ::::{warning} -Inline synonyms are not recommended for production usage. A large number of inline synonyms increases cluster size unnecessarily and can lead to performance issues. +Inline synonyms are not recommended for production usage. Too many inline synonyms increases cluster size unnecessarily and can lead to performance issues. :::: ## Step 2: Configure synonyms token filters and analyzers [synonyms-synonym-token-filters] @@ -286,7 +286,7 @@ PUT /my-index ## Search with synonyms in action [synonyms-search-example] -After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. For example, if you define `laptop, notebook` as equivalent synonyms and search for "laptop", {{es}} also matches documents containing "notebook". +After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. For example, if you define `laptop, notebook` as equivalent synonyms and search for `laptop`, {{es}} also matches documents containing `notebook`. ```console GET /my-index/_search @@ -299,7 +299,7 @@ GET /my-index/_search } ``` -This query matches documents where the `title` field contains "laptop" or "notebook", because the synonym rule treats them as equivalent. +This query matches documents where the `title` field contains `laptop` or `notebook`, because the synonym rule treats them as equivalent. ## Next steps From d94498355c15c347ac4b61d7d26ebacfa79f991a Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:03:36 +0200 Subject: [PATCH 10/33] Rewrite page opening: title, intro, and structure - 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 --- .../search/full-text/search-with-synonyms.md | 23 ++++++------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index a5b3ea669c..3b4402f361 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -9,34 +9,25 @@ products: - id: elasticsearch --- -# Search with synonyms [search-with-synonyms] +# Set up and search with synonyms in {{es}} [search-with-synonyms] -$$$ece-add-custom-bundle-example-synonyms$$$ -::::{note} -Learn about [adding custom synonym bundles](../../../deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md) to your {{ece}} deployment. -:::: +Synonyms are words or phrases that have the same or similar meaning. When you configure synonyms in {{product.elasticsearch}}, a search for one term automatically matches documents that use an equivalent term. This improves relevance when users express the same concept with different words, makes domain-specific vocabulary more accessible, and handles common misspellings transparently. -% TODO: these bundle links do not belong here +This page walks you through defining synonym rules, grouping them into reusable synonym sets, configuring {{product.elasticsearch}} to apply them during text analysis, and verifying that queries return the expanded results you expect. -$$$ece-add-custom-bundle-example-LDA$$$ +% TODO: these bundle links do not belong here — migration artifacts kept to avoid broken builds +$$$ece-add-custom-bundle-example-synonyms$$$ +$$$ece-add-custom-bundle-example-LDA$$$ $$$ece-add-custom-bundle-example-SAML$$$ - $$$ece-add-custom-bundle-example-cacerts$$$ - $$$ece-add-custom-bundle-example-LDAP$$$ -Synonyms are words or phrases that share the same or similar meaning. Searching using synonyms allows you to: - -* Improve search relevance by finding relevant documents that use different terms to express the same concept. -* Make domain-specific vocabulary more user-friendly. -* Define misspellings and typos to transparently handle common mistakes. - ## Prerequisites To manage synonym sets using the API or {{kib}} UI, you need the `manage_search_synonyms` [cluster privilege](elasticsearch://reference/elasticsearch/security-privileges.md). -## How synonyms work in Elasticsearch +## How synonyms work in {{product.elasticsearch}} To use synonyms in {{es}}, follow this workflow: From 60139efeff5c64f8fa6f102f9a3f7a8b9f08f8a0 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:10:32 +0200 Subject: [PATCH 11/33] Use 'equivalent mappings' terminology consistently Replace 'equivalent synonyms' with 'equivalent mappings' throughout, matching the section heading and standard Elasticsearch terminology. --- solutions/search/full-text/search-with-synonyms.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 3b4402f361..970ab6bac4 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -57,7 +57,7 @@ With explicit mappings, the relationship is one-way. In the previous examples: ### Equivalent mappings -Equivalent synonyms use commas to group interchangeable terms: +Equivalent mappings use commas to group interchangeable terms: ``` ipod, i-pod, i pod @@ -66,7 +66,7 @@ universe, cosmos lol, laughing out loud ``` -The behavior of equivalent synonyms depends on the `expand` parameter in your token filter configuration: +The behavior of equivalent mappings depends on the `expand` parameter in your token filter configuration: - If `expand=true` (the default): all terms are mapped to each other bidirectionally. - If `expand=false`: all terms are mapped to the first term only. @@ -121,7 +121,7 @@ An example of a synonym file: i-pod, i pod => ipod sea biscuit, sea biscit => seabiscuit -# Equivalent synonyms +# Equivalent mappings ipod, i-pod, i pod universe, cosmos ``` @@ -277,7 +277,7 @@ PUT /my-index ## Search with synonyms in action [synonyms-search-example] -After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. For example, if you define `laptop, notebook` as equivalent synonyms and search for `laptop`, {{es}} also matches documents containing `notebook`. +After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. For example, if `laptop` and `notebook` are configured as equivalent terms and you search for `laptop`, {{es}} also matches documents containing `notebook`. ```console GET /my-index/_search From 2629fb9913f6580a8ed724a37122eb0d371a06e4 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:15:22 +0200 Subject: [PATCH 12/33] Replace redundant tabbed examples with annotated code 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. --- .../search/full-text/search-with-synonyms.md | 48 ++----------------- 1 file changed, 4 insertions(+), 44 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 970ab6bac4..02bd994843 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -198,11 +198,10 @@ You can specify the analyzer that contains your synonym set as a [search time an Queries that support synonym expansion include [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md), [query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-query-string-query.md), and [simple_query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-simple-query-string-query.md). These queries support the `auto_generate_synonyms_phrase_query` parameter, which controls how multi-word synonyms are handled at query time. -The following example adds `my_analyzer` as a search analyzer to the `title` field in an index mapping: +The following example adds `my_analyzer` as a search analyzer to the `title` field in an index mapping. The filter references a synonym set created through the API or {{kib}} UI. -::::{tab-set} +For [file-based synonym sets](#synonyms-store-synonyms-file), use `synonyms_path` instead of `synonyms_set`. {applies_to}`serverless: unavailable` -:::{tab-item} API or UI synonym set ```console PUT /my-index { @@ -225,7 +224,7 @@ PUT /my-index "filter": { "synonyms_filter": { "type": "synonym_graph", - "synonyms_set": "my-synonym-set", + "synonyms_set": "my-synonym-set", <1> "updateable": true } } @@ -233,47 +232,8 @@ PUT /my-index } } ``` -::: -:::{tab-item} File-based synonym set - -```{applies_to} -serverless: unavailable -``` - -```console -PUT /my-index -{ - "mappings": { - "properties": { - "title": { - "type": "text", - "search_analyzer": "my_analyzer" - } - } - }, - "settings": { - "analysis": { - "analyzer": { - "my_analyzer": { - "tokenizer": "standard", - "filter": ["lowercase", "synonyms_filter"] - } - }, - "filter": { - "synonyms_filter": { - "type": "synonym_graph", - "synonyms_path": "analysis/synonym-set.txt", - "updateable": true - } - } - } - } -} -``` -::: - -:::: +1. For file-based synonym sets, replace with `"synonyms_path": "analysis/synonym-set.txt"`. ## Search with synonyms in action [synonyms-search-example] From 02e2ea2b41df0e7168fd9e2fd33f77e528f8145d Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:18:11 +0200 Subject: [PATCH 13/33] Convert synonym set methods from headings to tab-set Replace four Method headings with a tab-set for cleaner navigation. Preserve BWC anchors using $$$ syntax for cross-repo links from elasticsearch reference pages. --- .../search/full-text/search-with-synonyms.md | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 02bd994843..1d013760fd 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -77,10 +77,12 @@ For details on how `expand` affects synonym rules, refer to the [synonym graph t You have multiple options for creating synonym sets and rules. ::::{note} -Synonym sets created through the API or the {{kib}} UI can only be used at search time. For index-time synonyms, use a [file-based](#synonyms-store-synonyms-file) or [inline](#synonyms-store-synonyms-inline) approach with the [`synonym` token filter](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md). +Synonym sets created through the API or the {{kib}} UI can only be used at search time. For index-time synonyms, use a file-based or inline approach with the [`synonym` token filter](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md). :::: -### Method 1: {{kib}} UI +::::::{tab-set} + +:::::{tab-item} {{kib}} UI You can create and manage synonym sets and synonym rules using the {{kib}} user interface. @@ -94,15 +96,23 @@ To create a synonym set using the UI: - Add **Explicit rules** by adding multiple terms that map to a single term. For example: `i-pod, i pod => ipod` 5. Select **Save** to save your rules. -The UI supports the same synonym rule formats as the [file-based approach](#synonyms-store-synonyms-file). Changes made through the UI automatically reload the associated analyzers. +The UI supports the same synonym rule formats as the file-based approach. Changes made through the UI automatically reload the associated analyzers. + +::::: + +:::::{tab-item} REST API -### Method 2: REST API [synonyms-store-synonyms-api] +$$$synonyms-store-synonyms-api$$$ You can use the [synonyms APIs]({{es-apis}}group/endpoint-synonyms) to manage synonym sets. This is the most flexible approach, as it allows you to dynamically define and modify synonym sets. For examples of how to create or update a synonym set with APIs, refer to the [Create or update synonym set API examples](/solutions/search/full-text/create-update-synonyms-api-example.md) page. Changes to your synonym sets automatically reload the associated analyzers. -### Method 3: File-based [synonyms-store-synonyms-file] +::::: + +:::::{tab-item} File-based + +$$$synonyms-store-synonyms-file$$$ ```{applies_to} serverless: unavailable @@ -132,9 +142,13 @@ To update an existing synonym set, upload new files to your cluster. Synonym set When a synonym set is updated, search analyzers that use it need to be refreshed using the [reload search analyzers API]({{es-apis}}operation/operation-indices-reload-search-analyzers). -This manual syncing and reloading makes this approach less flexible than using the [synonyms API](#synonyms-store-synonyms-api). +This manual syncing and reloading makes this approach less flexible than using the synonyms API. -### Method 4: Inline [synonyms-store-synonyms-inline] +::::: + +:::::{tab-item} Inline + +$$$synonyms-store-synonyms-inline$$$ You can test your synonyms by adding them directly inline in your token filter definition. @@ -142,6 +156,10 @@ You can test your synonyms by adding them directly inline in your token filter d Inline synonyms are not recommended for production usage. Too many inline synonyms increases cluster size unnecessarily and can lead to performance issues. :::: +::::: + +:::::: + ## Step 2: Configure synonyms token filters and analyzers [synonyms-synonym-token-filters] Once your synonym sets are created, you can start configuring your token filters and analyzers to use them. From 24f1ef28f90772ed5d0a8c0560e4d0da89327e51 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:21:19 +0200 Subject: [PATCH 14/33] Trim synonym rule formats to brief primer 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. --- .../search/full-text/search-with-synonyms.md | 35 +++---------------- 1 file changed, 4 insertions(+), 31 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 1d013760fd..14f30e40d8 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -38,39 +38,12 @@ To use synonyms in {{es}}, follow this workflow: ## Synonym rule formats -Synonym rules define which terms should be treated as equivalent during search and indexing. +Synonym rules define which terms should be treated as equivalent. Each rule uses one of two mapping types: -Synonym rules use one of the following formats: +- **Explicit mappings** use `=>` to specify one-way replacements (for example, `i-pod, i pod => ipod`). +- **Equivalent mappings** use commas to group interchangeable terms (for example, `ipod, i-pod, i pod`). -### Explicit mappings - -Explicit mappings use `=>` to specify exact replacements: - -``` -i-pod, i pod => ipod -sea biscuit, sea biscit => seabiscuit -``` - -With explicit mappings, the relationship is one-way. In the previous examples: -- `i-pod` and `i pod` are replaced with `ipod`, but `ipod` is not replaced with `i-pod` or `i pod`. -- `sea biscuit` and `sea biscit` are replaced with `seabiscuit`, but `seabiscuit` is not replaced with `sea biscuit` or `sea biscit`. - -### Equivalent mappings - -Equivalent mappings use commas to group interchangeable terms: - -``` -ipod, i-pod, i pod -foozball, foosball -universe, cosmos -lol, laughing out loud -``` - -The behavior of equivalent mappings depends on the `expand` parameter in your token filter configuration: -- If `expand=true` (the default): all terms are mapped to each other bidirectionally. -- If `expand=false`: all terms are mapped to the first term only. - -For details on how `expand` affects synonym rules, refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference. +For full format details, including `expand` behavior, WordNet format, and rule merging, refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference. ## Step 1: Create synonym sets and rules [synonyms-store-synonyms] From fd306519853c2a7feb425a2506e9d09ef393c16c Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:23:14 +0200 Subject: [PATCH 15/33] Trim circuit breaker prose, defer to reference Replace verbose inline circuit breaker explanation with a brief mention and linked reference to the synonym graph token filter page. --- solutions/search/full-text/search-with-synonyms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 14f30e40d8..66fc1eb787 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -148,7 +148,7 @@ Synonym sets must exist before they can be added to indices. If an index is crea Refer to each token filter's reference page for configuration details and instructions on adding it to an analyzer. -{applies_to}`{"stack": "ga 9.4", "serverless": "ga"}` When processing synonym rules, {{es}} uses a [circuit breaker](elasticsearch://reference/elasticsearch/configuration-reference/circuit-breaker-settings.md) (a memory safety mechanism) to prevent out-of-memory errors. If the circuit breaker trips because heap usage exceeds 95%, the behavior depends on the `lenient` parameter. The `lenient` parameter defaults to the value of `updateable`. When `updateable` is `true` (recommended for search-time synonyms), {{es}} uses an empty synonym map and logs the event. When `lenient` is `false`, the affected index enters a red state. The threshold is configurable using the [`indices.breaker.total.limit` setting](elasticsearch://reference/elasticsearch/configuration-reference/circuit-breaker-settings.md#parent-circuit-breaker). {applies_to}`serverless: unavailable` +{applies_to}`{"stack": "ga 9.4", "serverless": "ga"}` Large synonym sets can trigger a memory [circuit breaker](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker). Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker) reference for details on thresholds and `lenient` behavior. ::::{warning} Invalid synonym rules can cause errors when applying analyzer changes and can prevent an index from being reopened. Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference for details. From 17713d8ebec5238050512d7b3aea910055513020 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:29:53 +0200 Subject: [PATCH 16/33] Swap Steps 3/4 so test follows index creation 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. --- .../search/full-text/search-with-synonyms.md | 39 ++++++++----------- 1 file changed, 17 insertions(+), 22 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 66fc1eb787..a2db512770 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -33,8 +33,8 @@ To use synonyms in {{es}}, follow this workflow: 1. [**Create synonym sets and rules**](#synonyms-store-synonyms): Define which terms are equivalent and how to store your synonym sets. 2. [**Configure token filters and analyzers**](#synonyms-synonym-token-filters): Set up synonym token filters and add them to your analyzers. -3. [**Test your analyzer**](#synonyms-test-analyzer): Verify your synonym configuration produces the expected tokens. -4. [**Apply synonyms at index or search time**](#synonyms-apply-synonyms): Specify your analyzer in your index mapping. +3. [**Apply synonyms at index or search time**](#synonyms-apply-synonyms): Specify your analyzer in your index mapping. +4. [**Test your analyzer**](#synonyms-test-analyzer): Verify your synonym configuration produces the expected tokens. ## Synonym rule formats @@ -154,26 +154,7 @@ Refer to each token filter's reference page for configuration details and instru Invalid synonym rules can cause errors when applying analyzer changes and can prevent an index from being reopened. Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference for details. :::: -## Step 3: Test your analyzer [synonyms-test-analyzer] - -You can test an analyzer configuration without modifying your index settings. Use the [analyze API]({{es-apis}}operation/operation-indices-analyze) to test your analyzer chain: - -```console -GET /_analyze -{ - "tokenizer": "standard", - "filter" : [ - "lowercase", - { - "type": "synonym_graph", - "synonyms": ["pc => personal computer", "computer, pc, laptop"] - } - ], - "text" : "Check how PC synonyms work" -} -``` - -## Step 4: Apply synonyms at index or search time [synonyms-apply-synonyms] +## Step 3: Apply synonyms at index or search time [synonyms-apply-synonyms] Analyzers can be applied at [index time or search time](../../../manage-data/data-store/text-analysis/index-search-analysis.md). @@ -226,6 +207,20 @@ PUT /my-index 1. For file-based synonym sets, replace with `"synonyms_path": "analysis/synonym-set.txt"`. +## Step 4: Test your analyzer [synonyms-test-analyzer] + +After creating your index, use the [analyze API]({{es-apis}}operation/operation-indices-analyze) to verify that your synonym configuration produces the expected tokens: + +```console +GET /my-index/_analyze +{ + "analyzer": "my_analyzer", + "text": "laptop" +} +``` + +If your synonym set includes `laptop, notebook` as equivalent terms, the response contains tokens for both `laptop` and `notebook`. + ## Search with synonyms in action [synonyms-search-example] After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. For example, if `laptop` and `notebook` are configured as equivalent terms and you search for `laptop`, {{es}} also matches documents containing `notebook`. From 908cccf162c94dc4e393153144a1bffaf72c0a9f Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:31:31 +0200 Subject: [PATCH 17/33] Fix broken anchor after tab-set conversion Add BWC anchor to Kibana UI tab and update the inbound link from elasticsearch-solution-project.md. --- solutions/elasticsearch-solution-project.md | 2 +- solutions/search/full-text/search-with-synonyms.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/solutions/elasticsearch-solution-project.md b/solutions/elasticsearch-solution-project.md index 5745c84746..3f06cddc46 100644 --- a/solutions/elasticsearch-solution-project.md +++ b/solutions/elasticsearch-solution-project.md @@ -38,7 +38,7 @@ The {{es}} solution provides the following specialized UI tools and features to ### Synonyms UI -The [synonyms UI](/solutions/search/full-text/search-with-synonyms.md#method-1-kib-ui) enables managing synonym sets directly within {{kib}}. This makes it easier to improve search relevance without editing configuration files. +The [synonyms UI](/solutions/search/full-text/search-with-synonyms.md#synonyms-store-synonyms-kibana) enables managing synonym sets directly within {{kib}}. This makes it easier to improve search relevance without editing configuration files. ### Query Rules UI diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index a2db512770..2ddcadd175 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -57,6 +57,8 @@ Synonym sets created through the API or the {{kib}} UI can only be used at searc :::::{tab-item} {{kib}} UI +$$$synonyms-store-synonyms-kibana$$$ + You can create and manage synonym sets and synonym rules using the {{kib}} user interface. To create a synonym set using the UI: From 8ad243e6bf09f0cbc2bb57c188f0b80259464d95 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:33:14 +0200 Subject: [PATCH 18/33] Add stop token filter ordering note in Step 2 Mention that stop filter placement relative to synonym filters affects expansion, with a link to the reference section for details. --- solutions/search/full-text/search-with-synonyms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 2ddcadd175..0d7b0c3753 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -148,7 +148,7 @@ Synonym sets must exist before they can be added to indices. If an index is crea * [Synonym graph](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md): Recommended for search analyzers. Correctly handles multi-word synonyms. This filter is designed for search-time use only. * [Synonym](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md): Required for index-time synonyms. Not recommended if you need to use multi-word synonyms. -Refer to each token filter's reference page for configuration details and instructions on adding it to an analyzer. +Refer to each token filter's reference page for configuration details and instructions on adding it to an analyzer. If your analyzer chain includes a [stop token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-stop-token-filter), pay attention to ordering. Stop filters placed before or after a synonym filter affect synonym expansion differently. {applies_to}`{"stack": "ga 9.4", "serverless": "ga"}` Large synonym sets can trigger a memory [circuit breaker](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker). Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker) reference for details on thresholds and `lenient` behavior. From 368cf62ab802ae172d81d9f2b14e877a8975e2dd Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 16:40:13 +0200 Subject: [PATCH 19/33] Add applies_to for Kibana UI synonyms tab Scope to stack: ga 9.1 and serverless: ga instead of removing the tag entirely. --- solutions/search/full-text/search-with-synonyms.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 0d7b0c3753..7905df3c1b 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -59,6 +59,11 @@ Synonym sets created through the API or the {{kib}} UI can only be used at searc $$$synonyms-store-synonyms-kibana$$$ +```{applies_to} +stack: ga 9.1 +serverless: ga +``` + You can create and manage synonym sets and synonym rules using the {{kib}} user interface. To create a synonym set using the UI: From ac7502e2d555999a1fe78ffa4a5ba26d18ce6040 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 18:03:14 +0200 Subject: [PATCH 20/33] Fix Kibana UI applies_to to scope serverless correctly Use serverless: elasticsearch project type instead of bare serverless: ga. The synonyms UI is only available on serverless Elasticsearch (search) projects. --- solutions/search/full-text/search-with-synonyms.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 7905df3c1b..db56ce4db6 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -61,7 +61,8 @@ $$$synonyms-store-synonyms-kibana$$$ ```{applies_to} stack: ga 9.1 -serverless: ga +serverless: + elasticsearch: ``` You can create and manage synonym sets and synonym rules using the {{kib}} user interface. From 10d9da4ef6bc5d3de458f2730e3b41dcd815ef62 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 18:04:40 +0200 Subject: [PATCH 21/33] Improve inline synonyms tab with example and links Add a code snippet showing the synonyms parameter, and link the warning to the API and file-based alternatives. --- solutions/search/full-text/search-with-synonyms.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index db56ce4db6..b675fc0951 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -131,10 +131,17 @@ This manual syncing and reloading makes this approach less flexible than using t $$$synonyms-store-synonyms-inline$$$ -You can test your synonyms by adding them directly inline in your token filter definition. +You can define synonyms directly in your token filter using the `synonyms` parameter. This is useful for testing, but not recommended for production. + +```json +"synonyms_filter": { + "type": "synonym_graph", + "synonyms": ["laptop, notebook", "i-pod, i pod => ipod"] +} +``` ::::{warning} -Inline synonyms are not recommended for production usage. Too many inline synonyms increases cluster size unnecessarily and can lead to performance issues. +Too many inline synonyms increases cluster size unnecessarily and can lead to performance issues. For production workloads, use the [API](#synonyms-store-synonyms-api) or a [synonym file](#synonyms-store-synonyms-file) instead. :::: ::::: From 65e9e2f30e6253bfffbfc0ae3ff81b73c1bd6176 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 18:09:59 +0200 Subject: [PATCH 22/33] Move synonym set warning to end of Step 1 and trim The warning about creating sets before referencing them belongs in Step 1 where sets are created, not Step 2. --- solutions/search/full-text/search-with-synonyms.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index b675fc0951..55bf647034 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -146,16 +146,16 @@ Too many inline synonyms increases cluster size unnecessarily and can lead to pe ::::: +::::{warning} +Synonym sets must exist before you reference them in an index. An index that references a nonexistent synonym set becomes inoperable and must be deleted and re-created, or closed and re-opened. +:::: + :::::: ## Step 2: Configure synonyms token filters and analyzers [synonyms-synonym-token-filters] Once your synonym sets are created, you can start configuring your token filters and analyzers to use them. -::::{warning} -Synonym sets must exist before they can be added to indices. If an index is created referencing a nonexistent synonym set, the index remains in a partially created and inoperable state. The only way to recover from this scenario is to ensure the synonym set exists then either delete and re-create the index, or close and re-open the index. -:::: - {{es}} uses synonyms as part of the [analysis process](../../../manage-data/data-store/text-analysis.md). You can use two types of [token filter](elasticsearch://reference/text-analysis/token-filter-reference.md) to include synonyms: * [Synonym graph](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md): Recommended for search analyzers. Correctly handles multi-word synonyms. This filter is designed for search-time use only. From aaca240f7e6a85c124db9d4c557c9eb44cb9c0e3 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 19:01:54 +0200 Subject: [PATCH 23/33] Rename workflow heading to Synonyms workflow overview --- solutions/search/full-text/search-with-synonyms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 55bf647034..07795f54e1 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -27,7 +27,7 @@ $$$ece-add-custom-bundle-example-LDAP$$$ To manage synonym sets using the API or {{kib}} UI, you need the `manage_search_synonyms` [cluster privilege](elasticsearch://reference/elasticsearch/security-privileges.md). -## How synonyms work in {{product.elasticsearch}} +## Synonyms workflow overview To use synonyms in {{es}}, follow this workflow: From 3c4355d102e21dc4726c523d2bdcbfe82e6affda Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 19:39:49 +0200 Subject: [PATCH 24/33] Simplify synonym format reference link Drop unexplained concept names from the link-out sentence. --- solutions/search/full-text/search-with-synonyms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 07795f54e1..c5fc646da3 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -43,7 +43,7 @@ Synonym rules define which terms should be treated as equivalent. Each rule uses - **Explicit mappings** use `=>` to specify one-way replacements (for example, `i-pod, i pod => ipod`). - **Equivalent mappings** use commas to group interchangeable terms (for example, `ipod, i-pod, i pod`). -For full format details, including `expand` behavior, WordNet format, and rule merging, refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference. +For full format details, refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference. ## Step 1: Create synonym sets and rules [synonyms-store-synonyms] From 9fede187931777fe98431307354dcbc9f1095570 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 19:41:02 +0200 Subject: [PATCH 25/33] Move synonym set warning outside tab-set Place it after the closing tab-set delimiter so it renders as a standalone warning at the end of Step 1. --- solutions/search/full-text/search-with-synonyms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index c5fc646da3..6dfc60fdea 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -146,12 +146,12 @@ Too many inline synonyms increases cluster size unnecessarily and can lead to pe ::::: +:::::: + ::::{warning} Synonym sets must exist before you reference them in an index. An index that references a nonexistent synonym set becomes inoperable and must be deleted and re-created, or closed and re-opened. :::: -:::::: - ## Step 2: Configure synonyms token filters and analyzers [synonyms-synonym-token-filters] Once your synonym sets are created, you can start configuring your token filters and analyzers to use them. From b86a277c2883d97263055673ce4172460bcb0df4 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 19:43:25 +0200 Subject: [PATCH 26/33] Remove applies_to from circuit breaker mention The reference page already has proper version scoping on its circuit breaker section. No need to duplicate it on a brief pointer. --- solutions/search/full-text/search-with-synonyms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 6dfc60fdea..db382a7475 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -163,7 +163,7 @@ Once your synonym sets are created, you can start configuring your token filters Refer to each token filter's reference page for configuration details and instructions on adding it to an analyzer. If your analyzer chain includes a [stop token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-stop-token-filter), pay attention to ordering. Stop filters placed before or after a synonym filter affect synonym expansion differently. -{applies_to}`{"stack": "ga 9.4", "serverless": "ga"}` Large synonym sets can trigger a memory [circuit breaker](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker). Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker) reference for details on thresholds and `lenient` behavior. +Large synonym sets can trigger a memory [circuit breaker](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker). Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker) reference for details on thresholds and `lenient` behavior. ::::{warning} Invalid synonym rules can cause errors when applying analyzer changes and can prevent an index from being reopened. Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference for details. From 6c537c2cf356f315e55bdb421df6c6cfc7b87b61 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 19:45:22 +0200 Subject: [PATCH 27/33] Make search example Step 5 in the workflow Rename heading and add jump link in the workflow overview so the search example is part of the continuous thread. --- solutions/search/full-text/search-with-synonyms.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index db382a7475..b50e68ed6f 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -35,6 +35,7 @@ To use synonyms in {{es}}, follow this workflow: 2. [**Configure token filters and analyzers**](#synonyms-synonym-token-filters): Set up synonym token filters and add them to your analyzers. 3. [**Apply synonyms at index or search time**](#synonyms-apply-synonyms): Specify your analyzer in your index mapping. 4. [**Test your analyzer**](#synonyms-test-analyzer): Verify your synonym configuration produces the expected tokens. +5. [**Search with synonyms**](#synonyms-search-example): Run a search query and confirm synonym expansion works. ## Synonym rule formats @@ -236,7 +237,7 @@ GET /my-index/_analyze If your synonym set includes `laptop, notebook` as equivalent terms, the response contains tokens for both `laptop` and `notebook`. -## Search with synonyms in action [synonyms-search-example] +## Step 5: Search with synonyms [synonyms-search-example] After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. For example, if `laptop` and `notebook` are configured as equivalent terms and you search for `laptop`, {{es}} also matches documents containing `notebook`. From afc56229b61083050288fbaa4a6d127fd5340672 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Thu, 13 Aug 2026 19:48:43 +0200 Subject: [PATCH 28/33] Clean up Step 3 and move query references to Step 5 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). --- .../search/full-text/search-with-synonyms.md | 24 ++++++------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index b50e68ed6f..6aa543e8c9 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -33,7 +33,7 @@ To use synonyms in {{es}}, follow this workflow: 1. [**Create synonym sets and rules**](#synonyms-store-synonyms): Define which terms are equivalent and how to store your synonym sets. 2. [**Configure token filters and analyzers**](#synonyms-synonym-token-filters): Set up synonym token filters and add them to your analyzers. -3. [**Apply synonyms at index or search time**](#synonyms-apply-synonyms): Specify your analyzer in your index mapping. +3. [**Create an index with your synonym analyzer**](#synonyms-apply-synonyms): Apply your analyzer to an index mapping. 4. [**Test your analyzer**](#synonyms-test-analyzer): Verify your synonym configuration produces the expected tokens. 5. [**Search with synonyms**](#synonyms-search-example): Run a search query and confirm synonym expansion works. @@ -170,23 +170,11 @@ Large synonym sets can trigger a memory [circuit breaker](elasticsearch://refere Invalid synonym rules can cause errors when applying analyzer changes and can prevent an index from being reopened. Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference for details. :::: -## Step 3: Apply synonyms at index or search time [synonyms-apply-synonyms] +## Step 3: Create an index with your synonym analyzer [synonyms-apply-synonyms] -Analyzers can be applied at [index time or search time](../../../manage-data/data-store/text-analysis/index-search-analysis.md). +Synonyms can be applied at [search time or index time](../../../manage-data/data-store/text-analysis/index-search-analysis.md). Search time is recommended because you can update your synonym sets without [reindexing]({{es-apis}}operation/operation-reindex). If token filters are configured with `"updateable": true`, search analyzers can be [reloaded]({{es-apis}}operation/operation-indices-reload-search-analyzers) when you make changes. -You need to decide when to apply your synonyms: - -* **Index time**: {applies_to}`serverless: unavailable` Synonyms are applied when the documents are indexed into {{es}}. This is a less flexible alternative, as changes to your synonyms require [reindexing]({{es-apis}}operation/operation-reindex). -* **Search time**: Synonyms are applied when a search is executed. This is a more flexible approach, which doesn't require reindexing. If token filters are configured with `"updateable": true`, search analyzers can be [reloaded]({{es-apis}}operation/operation-indices-reload-search-analyzers) when you make changes to your synonyms. - :::{note} - Synonym sets created using the synonyms API or the UI can only be used at search time. - ::: - -You can specify the analyzer that contains your synonym set as a [search time analyzer](../../../manage-data/data-store/text-analysis/specify-an-analyzer.md#specify-search-analyzer) or as an [index time analyzer](../../../manage-data/data-store/text-analysis/specify-an-analyzer.md#specify-index-time-analyzer). - -Queries that support synonym expansion include [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md), [query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-query-string-query.md), and [simple_query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-simple-query-string-query.md). These queries support the `auto_generate_synonyms_phrase_query` parameter, which controls how multi-word synonyms are handled at query time. - -The following example adds `my_analyzer` as a search analyzer to the `title` field in an index mapping. The filter references a synonym set created through the API or {{kib}} UI. +The following example creates an index with `my_analyzer` as a search analyzer on the `title` field. For [file-based synonym sets](#synonyms-store-synonyms-file), use `synonyms_path` instead of `synonyms_set`. {applies_to}`serverless: unavailable` @@ -239,7 +227,9 @@ If your synonym set includes `laptop, notebook` as equivalent terms, the respons ## Step 5: Search with synonyms [synonyms-search-example] -After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. For example, if `laptop` and `notebook` are configured as equivalent terms and you search for `laptop`, {{es}} also matches documents containing `notebook`. +After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. Queries that support synonym expansion include [match](elasticsearch://reference/query-languages/query-dsl/query-dsl-match-query.md), [query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-query-string-query.md), and [simple_query_string](elasticsearch://reference/query-languages/query-dsl/query-dsl-simple-query-string-query.md). + +For example, if `laptop` and `notebook` are configured as equivalent terms and you search for `laptop`, {{es}} also matches documents containing `notebook`: ```console GET /my-index/_search From 96295312aaa3c0bf18cb669106305c605f80a9ba Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 14 Aug 2026 11:46:08 +0200 Subject: [PATCH 29/33] Polish: rename title, analyzer, tab order, annotations - 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 --- .../search/full-text/search-with-synonyms.md | 41 +++++++++---------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 6aa543e8c9..9698a0c067 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -1,4 +1,5 @@ --- +navigation_title: Synonyms mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/search-with-synonyms.html description: Learn how to define synonym sets, configure synonym token filters and analyzers, and apply synonyms at search time or index time in Elasticsearch. @@ -9,7 +10,7 @@ products: - id: elasticsearch --- -# Set up and search with synonyms in {{es}} [search-with-synonyms] +# Configure synonyms in {{es}} [search-with-synonyms] Synonyms are words or phrases that have the same or similar meaning. When you configure synonyms in {{product.elasticsearch}}, a search for one term automatically matches documents that use an equivalent term. This improves relevance when users express the same concept with different words, makes domain-specific vocabulary more accessible, and handles common misspellings transparently. @@ -50,12 +51,20 @@ For full format details, refer to the [synonym graph token filter](elasticsearch You have multiple options for creating synonym sets and rules. -::::{note} Synonym sets created through the API or the {{kib}} UI can only be used at search time. For index-time synonyms, use a file-based or inline approach with the [`synonym` token filter](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md). -:::: ::::::{tab-set} +:::::{tab-item} REST API + +$$$synonyms-store-synonyms-api$$$ + +You can use the [synonyms APIs]({{es-apis}}group/endpoint-synonyms) to manage synonym sets. This is the most flexible approach, as it allows you to dynamically define and modify synonym sets. For examples of how to create or update a synonym set with APIs, refer to the [Create or update synonym set API examples](/solutions/search/full-text/create-update-synonyms-api-example.md) page. + +Changes to your synonym sets automatically reload the associated analyzers. + +::::: + :::::{tab-item} {{kib}} UI $$$synonyms-store-synonyms-kibana$$$ @@ -82,16 +91,6 @@ The UI supports the same synonym rule formats as the file-based approach. Change ::::: -:::::{tab-item} REST API - -$$$synonyms-store-synonyms-api$$$ - -You can use the [synonyms APIs]({{es-apis}}group/endpoint-synonyms) to manage synonym sets. This is the most flexible approach, as it allows you to dynamically define and modify synonym sets. For examples of how to create or update a synonym set with APIs, refer to the [Create or update synonym set API examples](/solutions/search/full-text/create-update-synonyms-api-example.md) page. - -Changes to your synonym sets automatically reload the associated analyzers. - -::::: - :::::{tab-item} File-based $$$synonyms-store-synonyms-file$$$ @@ -174,9 +173,7 @@ Invalid synonym rules can cause errors when applying analyzer changes and can pr Synonyms can be applied at [search time or index time](../../../manage-data/data-store/text-analysis/index-search-analysis.md). Search time is recommended because you can update your synonym sets without [reindexing]({{es-apis}}operation/operation-reindex). If token filters are configured with `"updateable": true`, search analyzers can be [reloaded]({{es-apis}}operation/operation-indices-reload-search-analyzers) when you make changes. -The following example creates an index with `my_analyzer` as a search analyzer on the `title` field. - -For [file-based synonym sets](#synonyms-store-synonyms-file), use `synonyms_path` instead of `synonyms_set`. {applies_to}`serverless: unavailable` +The following example creates an index with `synonyms_analyzer` as a search analyzer on the `title` field. ```console PUT /my-index @@ -185,14 +182,14 @@ PUT /my-index "properties": { "title": { "type": "text", - "search_analyzer": "my_analyzer" + "search_analyzer": "synonyms_analyzer" <2> } } }, "settings": { "analysis": { "analyzer": { - "my_analyzer": { + "synonyms_analyzer": { "tokenizer": "standard", "filter": ["lowercase", "synonyms_filter"] } @@ -201,7 +198,7 @@ PUT /my-index "synonyms_filter": { "type": "synonym_graph", "synonyms_set": "my-synonym-set", <1> - "updateable": true + "updateable": true <3> } } } @@ -209,7 +206,9 @@ PUT /my-index } ``` -1. For file-based synonym sets, replace with `"synonyms_path": "analysis/synonym-set.txt"`. +1. For [file-based synonym sets](#synonyms-store-synonyms-file), use `"synonyms_path": "analysis/synonym-set.txt"` instead. {applies_to}`serverless: unavailable` +2. Applies synonyms at search time only, not when indexing documents. +3. Allows the analyzer to be [reloaded]({{es-apis}}operation/operation-indices-reload-search-analyzers) when synonym sets change, without reindexing. ## Step 4: Test your analyzer [synonyms-test-analyzer] @@ -218,7 +217,7 @@ After creating your index, use the [analyze API]({{es-apis}}operation/operation- ```console GET /my-index/_analyze { - "analyzer": "my_analyzer", + "analyzer": "synonyms_analyzer", "text": "laptop" } ``` From 28227618273e9b0d41294d9052df95ed174ea273 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 14 Aug 2026 12:30:10 +0200 Subject: [PATCH 30/33] Reword intro to frame synonym use cases as deliberate Frame synonym benefits as things you can do by defining rules, not as automatic outcomes of enabling synonyms. --- solutions/search/full-text/search-with-synonyms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 9698a0c067..7fb206a9fd 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -12,7 +12,7 @@ products: # Configure synonyms in {{es}} [search-with-synonyms] -Synonyms are words or phrases that have the same or similar meaning. When you configure synonyms in {{product.elasticsearch}}, a search for one term automatically matches documents that use an equivalent term. This improves relevance when users express the same concept with different words, makes domain-specific vocabulary more accessible, and handles common misspellings transparently. +Synonyms are words or phrases that have the same or similar meaning. When you configure synonyms in {{product.elasticsearch}}, a search for one term automatically matches documents that use an equivalent term. For example, you can define synonym rules to match different terms for the same concept, surface results for domain-specific jargon, or handle common misspellings. This page walks you through defining synonym rules, grouping them into reusable synonym sets, configuring {{product.elasticsearch}} to apply them during text analysis, and verifying that queries return the expanded results you expect. From 8c5dff42a9abdaab2224ac4e33c1cf27abf2a71b Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 14 Aug 2026 12:30:48 +0200 Subject: [PATCH 31/33] Add navigation_title to synonym set API examples page --- solutions/search/full-text/create-update-synonyms-api-example.md | 1 + 1 file changed, 1 insertion(+) diff --git a/solutions/search/full-text/create-update-synonyms-api-example.md b/solutions/search/full-text/create-update-synonyms-api-example.md index 68aa8e4b19..5f504280ca 100644 --- a/solutions/search/full-text/create-update-synonyms-api-example.md +++ b/solutions/search/full-text/create-update-synonyms-api-example.md @@ -1,4 +1,5 @@ --- +navigation_title: Synonym set API examples mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonyms-set.html#put-synonyms-set-example applies_to: From b6a6eb2a8bf5b43444bb89c56ffec7d7c5b972b7 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 14 Aug 2026 12:38:46 +0200 Subject: [PATCH 32/33] Change invalid rules admonition from warning to important --- solutions/search/full-text/search-with-synonyms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 7fb206a9fd..b58ac04256 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -165,7 +165,7 @@ Refer to each token filter's reference page for configuration details and instru Large synonym sets can trigger a memory [circuit breaker](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker). Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md#synonym-graph-tokenizer-circuit-breaker) reference for details on thresholds and `lenient` behavior. -::::{warning} +::::{important} Invalid synonym rules can cause errors when applying analyzer changes and can prevent an index from being reopened. Refer to the [synonym graph token filter](elasticsearch://reference/text-analysis/analysis-synonym-graph-tokenfilter.md) reference for details. :::: From 9ef8e835208b80908112baa1dcfe0401d2ecd250 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 14 Aug 2026 16:21:04 +0200 Subject: [PATCH 33/33] Remove anchor links to tab content in inline warning --- solutions/search/full-text/search-with-synonyms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index b58ac04256..55f4edc0a8 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -141,7 +141,7 @@ You can define synonyms directly in your token filter using the `synonyms` param ``` ::::{warning} -Too many inline synonyms increases cluster size unnecessarily and can lead to performance issues. For production workloads, use the [API](#synonyms-store-synonyms-api) or a [synonym file](#synonyms-store-synonyms-file) instead. +Too many inline synonyms increases cluster size unnecessarily and can lead to performance issues. For production workloads, use the REST API or file-based approach instead. :::: :::::