From 62dc650521e49b3d271796972fd9caa299446732 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 22 Aug 2025 13:43:31 +0200 Subject: [PATCH 01/13] Update Synonyms page, mention UI option --- .../search/full-text/search-with-synonyms.md | 91 +++++++++++++------ 1 file changed, 61 insertions(+), 30 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 17484d5289..0faa2b8f37 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -8,14 +8,13 @@ products: - id: elasticsearch --- -# Search with synonyms +# Search with synonyms [search-with-synonyms] $$$ece-add-custom-bundle-example-synonyms$$$ ::::{note} Learn about [adding custom synonym bundles](/solutions/search/full-text/search-with-synonyms.md#ece-add-custom-bundle-example-synonyms) to your {{ece}} deployment. :::: - % TODO: these bundle links do not belong here $$$ece-add-custom-bundle-example-LDA$$$ @@ -26,8 +25,6 @@ $$$ece-add-custom-bundle-example-cacerts$$$ $$$ece-add-custom-bundle-example-LDAP$$$ -# Search with synonyms [search-with-synonyms] - Synonyms are words or phrases that have the same or similar meaning. They are an important aspect of search, as they can improve the search experience and increase the scope of search results. Synonyms allow you to: @@ -38,29 +35,75 @@ Synonyms allow you to: Synonyms are grouped together using **synonyms sets**. You can have as many synonyms sets as you need. -In order to use synonyms sets in {{es}}, you need to: +## How synonyms work in Elasticsearch + +To use synonyms in {{es}}, you need to follow this workflow: + +1. **Create synonym sets and rules** - Define which terms are equivalent and where to store your synonym sets +2. **Configure analyzers** - Apply synonyms during text analysis +3. **Test and apply** - Verify your configuration works correctly + +## Step 1: Create synonym sets and rules + +You can create synonym sets and rules using several methods: + +### Synonym rule formats -* [Store your synonyms set](#synonyms-store-synonyms) -* [Configure synonyms token filters and analyzers](#synonyms-synonym-token-filters) +Before creating synonym sets, you need to understand how to write synonym rules. Synonym rules define which terms should be treated as equivalent during search and indexing. +There are two main formats for synonym rules: -## Store your synonyms set [synonyms-store-synonyms] +**Explicit mappings** use `=>` to specify exact replacements: +``` +i-pod, i pod => ipod +sea biscuit, sea biscit => seabiscuit +``` -Your synonyms sets need to be stored in {{es}} so your analyzers can refer to them. There are three ways to store your synonyms sets: +**Equivalent synonyms** use commas to group interchangeable terms: +``` +ipod, i-pod, i pod +foozball, foosball +universe, cosmos +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` expands to `ipod, i-pod, i pod` +- If `expand=false`: `ipod, i-pod, i pod` maps to just `ipod` -### Synonyms API [synonyms-store-synonyms-api] +### Method 1: Kibana UI + +```yaml {applies_to} +serverless: + elasticsearch: +``` + +You can create and manage synonym sets and synonym rules using the Kibana user interface. This provides a user-friendly way to manage synonyms without using APIs or file uploads. + +To create a synonym set using the UI: + +1. Navigate to **Elasticsearch** > **Synonyms** or use the [global search field](docs-content://explore-analyze/query-filter/filtering.md#_finding_your_apps_and_objects) +2. Click **Get started** +3. Enter a name for your synonym set +4. Add your synonym rules in the editor using the formats above: + - Explicit mappings: `i-pod, i pod => ipod` + - Equivalent synonyms: `ipod, i-pod, i pod` +5. Click **Create** to save your synonym set + +The UI supports the same synonym rule formats as the file-based approach. Changes made through the UI will automatically reload the associated analyzers. + +### Method 2: REST API You can use the [synonyms APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-synonyms) to manage synonyms sets. This is the most flexible approach, as it allows 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/search-with-synonyms.md) page. Changes in your synonyms sets will automatically reload the associated analyzers. -### Synonyms File [synonyms-store-synonyms-file] +### Method 3: File-based You can store your synonyms set in a file. -A synonyms set file needs to be uploaded to all your cluster nodes, and be located 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). +A synonyms set file needs to be uploaded to all your cluster nodes, and be located 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 synonyms file: @@ -104,28 +147,22 @@ When a synonyms set is updated, search analyzers that use it need to be refreshe 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). - -### Inline [synonyms-store-synonyms-inline] +### Method 4: Inline 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. - :::: - - -### Configure synonyms token filters and analyzers [synonyms-synonym-token-filters] +## 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. ::::{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. - :::: - ::::{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. @@ -134,10 +171,8 @@ An index with invalid synonym rules cannot be reopened, making it inoperable whe * A node containing the index starts * The index is opened from a closed state * A node restart occurs (which reopens the node assigned shards) - :::: - {{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): It is recommended to use it, as it can correctly handle multi-word synonyms ("hurriedly", "in a hurry"). @@ -145,8 +180,7 @@ An index with invalid synonym rules cannot be reopened, making it inoperable whe Check each synonym token filter documentation for configuration details and instructions on adding it to an analyzer. - -### Test your analyzer [synonyms-test-analyzer] +## Step 3: Test your analyzer [synonyms-test-analyzer] You can test an analyzer configuration without modifying your index settings. Use the [analyze API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-analyze) to test your analyzer chain: @@ -165,17 +199,14 @@ GET /_analyze } ``` - -### Apply synonyms at index or search time [synonyms-apply-synonyms] +## Step 4: 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). 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](https://www.elastic.co/docs/api/doc/elasticsearch/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](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-reload-search-analyzers) when you make changes to your synonyms. - -Synonyms sets created using the [synonyms API](../../../solutions/search/full-text/search-with-synonyms.md#synonyms-store-synonyms-api) can only be used at search time. +* **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](https://www.elastic.co/docs/api/doc/elasticsearch/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](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-reload-search-analyzers) when you make changes to your synonyms. 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). From fd367a5316700b546622e8d68a8a39c8d20dd2cc Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 22 Aug 2025 13:46:03 +0200 Subject: [PATCH 02/13] Restore note about API/UI search time applicability --- solutions/search/full-text/search-with-synonyms.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 0faa2b8f37..1f8102579f 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -207,6 +207,9 @@ 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](https://www.elastic.co/docs/api/doc/elasticsearch/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](https://www.elastic.co/docs/api/doc/elasticsearch/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. + ::: 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). From deb0e0d0bffeb65276712fdf18063a66013fbe89 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 22 Aug 2025 13:54:06 +0200 Subject: [PATCH 03/13] clarify UI behaviors --- solutions/search/full-text/search-with-synonyms.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 1f8102579f..6d3a0a8a6f 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -71,24 +71,24 @@ The behavior of equivalent synonyms depends on the `expand` parameter in your to - If `expand=true`: `ipod, i-pod, i pod` expands to `ipod, i-pod, i pod` - If `expand=false`: `ipod, i-pod, i pod` maps to just `ipod` -### Method 1: Kibana UI +### Method 1: {{kib}} UI ```yaml {applies_to} serverless: elasticsearch: ``` -You can create and manage synonym sets and synonym rules using the Kibana user interface. This provides a user-friendly way to manage synonyms without using APIs or file uploads. +You can create and manage synonym sets and synonym rules using the {{kib}} user interface. This provides a user-friendly way to manage synonyms without using APIs or file uploads. To create a synonym set using the UI: 1. Navigate to **Elasticsearch** > **Synonyms** or use the [global search field](docs-content://explore-analyze/query-filter/filtering.md#_finding_your_apps_and_objects) 2. Click **Get started** 3. Enter a name for your synonym set -4. Add your synonym rules in the editor using the formats above: - - Explicit mappings: `i-pod, i pod => ipod` - - Equivalent synonyms: `ipod, i-pod, i pod` -5. Click **Create** to save your synonym set +4. Add your synonym rules in the editor by adding terms to match against: + - Add **Equivalent rules** by addings multiple equivalent terms. For example: `ipod, i-pod, i pod` + - Add **Explicit rules** by addings multiple terms that map to a single term. For example: `i-pod, i pod => ipod` +5. Click **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. From 1e40dead3c6cae471d2410fc5c74c08f0689db25 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 22 Aug 2025 13:57:44 +0200 Subject: [PATCH 04/13] restore IDs --- 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 6d3a0a8a6f..4bd3cb89e5 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -43,7 +43,7 @@ To use synonyms in {{es}}, you need to follow this workflow: 2. **Configure analyzers** - Apply synonyms during text analysis 3. **Test and apply** - Verify your configuration works correctly -## Step 1: Create synonym sets and rules +## Step 1: Create synonym sets and rules [synonyms-store-synonyms] You can create synonym sets and rules using several methods: @@ -92,14 +92,14 @@ To create a synonym set using the UI: The UI supports the same synonym rule formats as the file-based approach. Changes made through the UI will automatically reload the associated analyzers. -### Method 2: REST API +### Method 2: REST API [synonyms-store-synonyms-api] You can use the [synonyms APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-synonyms) to manage synonyms sets. This is the most flexible approach, as it allows 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/search-with-synonyms.md) page. Changes in your synonyms sets will automatically reload the associated analyzers. -### Method 3: File-based +### Method 3: File-based [synonyms-store-synonyms-file] You can store your synonyms set in a file. @@ -147,7 +147,7 @@ When a synonyms set is updated, search analyzers that use it need to be refreshe 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). -### Method 4: Inline +### Method 4: Inline [synonyms-store-synonyms-inline] You can test your synonyms by adding them directly inline in your token filter definition. From 4848e8117da6e39166124b518906f926ac4a2b3c Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 22 Aug 2025 13:58:41 +0200 Subject: [PATCH 05/13] typo --- 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 4bd3cb89e5..79e41b86dd 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -86,8 +86,8 @@ To create a synonym set using the UI: 2. Click **Get started** 3. Enter a name for your synonym set 4. Add your synonym rules in the editor by adding terms to match against: - - Add **Equivalent rules** by addings multiple equivalent terms. For example: `ipod, i-pod, i pod` - - Add **Explicit rules** by addings multiple terms that map to a single term. For example: `i-pod, i pod => ipod` + - Add **Equivalent rules** by adding multiple equivalent terms. For example: `ipod, i-pod, i pod` + - Add **Explicit rules** by adding multiple terms that map to a single term. For example: `i-pod, i pod => ipod` 5. Click **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. From a150daf297aa0a3a3b7f63ed6d9e8537bbb64b8d Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 22 Aug 2025 13:59:29 +0200 Subject: [PATCH 06/13] don't need cross-repo links when youre in that repo --- 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 79e41b86dd..e74de36130 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -82,7 +82,7 @@ You can create and manage synonym sets and synonym rules using the {{kib}} user To create a synonym set using the UI: -1. Navigate to **Elasticsearch** > **Synonyms** or use the [global search field](docs-content://explore-analyze/query-filter/filtering.md#_finding_your_apps_and_objects) +1. Navigate to **Elasticsearch** > **Synonyms** or use the [global search field](/explore-analyze/query-filter/filtering.md#_finding_your_apps_and_objects) 2. Click **Get started** 3. Enter a name for your synonym set 4. Add your synonym rules in the editor by adding terms to match against: From 08362e6abfc7dec21032b6198d9d826d0d3d12c0 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Fri, 22 Aug 2025 14:14:04 +0200 Subject: [PATCH 07/13] fix intro --- solutions/search/full-text/search-with-synonyms.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index e74de36130..1399cf7a66 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -25,15 +25,11 @@ $$$ece-add-custom-bundle-example-cacerts$$$ $$$ece-add-custom-bundle-example-LDAP$$$ -Synonyms are words or phrases that have the same or similar meaning. They are an important aspect of search, as they can improve the search experience and increase the scope of search results. +Synonyms are words or phrases that share the same or similar meaning. Synonyms allow you to: -Synonyms allow 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, allowing users to use search terms they are more familiar with. -* **Define common misspellings and typos** to transparently handle common mistakes. - -Synonyms are grouped together using **synonyms sets**. You can have as many synonyms sets as you need. +* Improve search relevance by finding relevant documents that use different terms to express the same concept. +* Make domain-specific vocabulary more user-friendly, allowing users to use search terms they are more familiar with. +* Define common misspellings and typos to transparently handle common mistakes. ## How synonyms work in Elasticsearch From ac1c995a073107aa35c324748586918b5e0479c8 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 25 Aug 2025 10:25:57 +0200 Subject: [PATCH 08/13] Fix some facts, cleanup link fixes: updated custom bundle link to external path fixed api examples link to dedicated page content improvements: clarified step 2 description for analyzer configuration enhanced expand parameter explanation with bidirectional vs canonical mapping examples removed redundant phrases and improved conciseness fixed spacing in synonym file examples reorganized token filter section for better flow streamlined synonym rules introduction --- .../search/full-text/search-with-synonyms.md | 40 +++++++++++-------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 1399cf7a66..18841af8c8 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -12,7 +12,7 @@ products: $$$ece-add-custom-bundle-example-synonyms$$$ ::::{note} -Learn about [adding custom synonym bundles](/solutions/search/full-text/search-with-synonyms.md#ece-add-custom-bundle-example-synonyms) to your {{ece}} deployment. +Learn about [adding custom synonym bundles](../../../deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles.md) to your {{ece}} deployment. :::: % TODO: these bundle links do not belong here @@ -36,16 +36,16 @@ Synonyms are words or phrases that share the same or similar meaning. Synonyms a To use synonyms in {{es}}, you need to follow this workflow: 1. **Create synonym sets and rules** - Define which terms are equivalent and where to store your synonym sets -2. **Configure analyzers** - Apply synonyms during text analysis +2. **Configure analyzers** - Configure your token filters and analyzers to use them 3. **Test and apply** - Verify your configuration works correctly ## Step 1: Create synonym sets and rules [synonyms-store-synonyms] -You can create synonym sets and rules using several methods: +You have multiple options for creating synonym sets and rules. ### Synonym rule formats -Before creating synonym sets, you need to understand how to write synonym rules. Synonym rules define which terms should be treated as equivalent during search and indexing. +Synonym rules define which terms should be treated as equivalent during search and indexing. There are two main formats for synonym rules: @@ -64,8 +64,14 @@ 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` expands to `ipod, i-pod, i pod` -- If `expand=false`: `ipod, i-pod, i pod` maps to just `ipod` +- 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` ### Method 1: {{kib}} UI @@ -74,7 +80,7 @@ serverless: elasticsearch: ``` -You can create and manage synonym sets and synonym rules using the {{kib}} user interface. This provides a user-friendly way to manage synonyms without using APIs or file uploads. +You can create and manage synonym sets and synonym rules using the {{kib}} user interface. To create a synonym set using the UI: @@ -91,7 +97,7 @@ The UI supports the same synonym rule formats as the file-based approach. Change ### Method 2: REST API [synonyms-store-synonyms-api] You can use the [synonyms APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-synonyms) to manage synonyms sets. This is the most flexible approach, as it allows 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/search-with-synonyms.md) page. +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. Changes in your synonyms sets will automatically reload the associated analyzers. @@ -119,8 +125,8 @@ sea biscuit, sea biscit => seabiscuit # This allows the same synonym file to be used in different synonym handling strategies. # Examples: ipod, i-pod, i pod -foozball , foosball -universe , cosmos +foozball, foosball +universe, cosmos lol, laughing out loud # If expand==true in the synonym token filter configuration, @@ -159,6 +165,13 @@ Once your synonyms sets are created, you can start configuring your token filter 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. :::: +{{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. + +Check each synonym token filter documentation for configuration details and instructions on adding it to an analyzer. + ::::{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. @@ -169,13 +182,6 @@ An index with invalid synonym rules cannot be reopened, making it inoperable whe * A node restart occurs (which reopens the node assigned shards) :::: -{{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): It is recommended to use it, as it can correctly handle multi-word synonyms ("hurriedly", "in a hurry"). -* [Synonym](elasticsearch://reference/text-analysis/analysis-synonym-tokenfilter.md): 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. - ## Step 3: Test your analyzer [synonyms-test-analyzer] You can test an analyzer configuration without modifying your index settings. Use the [analyze API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-analyze) to test your analyzer chain: From af28c8187b74c3c4ccf39b5941bf26a410405dad Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 25 Aug 2025 21:38:40 +0200 Subject: [PATCH 09/13] refactor per @kdedrusso's review --- .../search/full-text/search-with-synonyms.md | 36 ++++++++++++++----- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 18841af8c8..72250495a4 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -25,7 +25,7 @@ $$$ece-add-custom-bundle-example-cacerts$$$ $$$ece-add-custom-bundle-example-LDAP$$$ -Synonyms are words or phrases that share the same or similar meaning. Synonyms allow you to: +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, allowing users to use search terms they are more familiar with. @@ -39,23 +39,31 @@ To use synonyms in {{es}}, you need to follow this workflow: 2. **Configure analyzers** - Configure your token filters and analyzers to use them 3. **Test and apply** - Verify your configuration works correctly -## Step 1: Create synonym sets and rules [synonyms-store-synonyms] +## Synonym rule formats -You have multiple options for creating synonym sets and rules. +Synonym rules define which terms should be treated as equivalent during search and indexing. -### Synonym rule formats +There are two main formats for synonym rules: explicit mappings and equivalent mappings. -Synonym rules define which terms should be treated as equivalent during search and indexing. +#### Explicit mappings -There are two main formats for synonym rules: +Explicit mappings use `=>` to specify exact replacements: -**Explicit mappings** use `=>` to specify exact replacements: ``` i-pod, i pod => ipod sea biscuit, sea biscit => seabiscuit ``` -**Equivalent synonyms** use commas to group interchangeable terms: +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` + +This is different from equivalent synonyms, which can create bidirectional relationships when `expand=true`. + +#### Equivalent mappings + +Equivalent synonyms use commas to group interchangeable terms: + ``` ipod, i-pod, i pod foozball, foosball @@ -73,6 +81,10 @@ The behavior of equivalent synonyms depends on the `expand` parameter in your to - `i-pod` → `ipod` - `i pod` → `ipod` +## Step 1: Create synonym sets and rules [synonyms-store-synonyms] + +You have multiple options for creating synonym sets and rules. + ### Method 1: {{kib}} UI ```yaml {applies_to} @@ -103,6 +115,10 @@ Changes in your synonyms sets will automatically reload the associated analyzers ### Method 3: File-based [synonyms-store-synonyms-file] +```{applies_to} +serverless: unavailable +``` + You can store your synonyms set in a file. A synonyms set file needs to be uploaded to all your cluster nodes, and be located 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). @@ -143,6 +159,8 @@ foo => baz foo => foo bar, baz ``` +// ... existing content up to the end of Method 3 ... + To update an existing synonyms set, upload new files to your cluster. Synonyms 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](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-reload-search-analyzers) @@ -247,4 +265,4 @@ The following example adds `my_analyzer` as a search analyzer to the `title` fie } } } -``` +``` \ No newline at end of file From 64981c9645642bb3e3be31a21549dcd4320a965e Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Mon, 25 Aug 2025 21:39:51 +0200 Subject: [PATCH 10/13] delete slop --- solutions/search/full-text/search-with-synonyms.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 72250495a4..9803f2845a 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -159,8 +159,6 @@ foo => baz foo => foo bar, baz ``` -// ... existing content up to the end of Method 3 ... - To update an existing synonyms set, upload new files to your cluster. Synonyms 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](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-reload-search-analyzers) From afee7e29925a01e665675ed841aab82148830cb7 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Tue, 26 Aug 2025 16:37:42 +0200 Subject: [PATCH 11/13] Commit Marci's suggestions Co-authored-by: Marci W <333176+marciw@users.noreply.github.com> --- 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 9803f2845a..9a7cda15b0 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -28,12 +28,12 @@ $$$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, allowing users to use search terms they are more familiar with. -* Define common misspellings and typos to transparently handle common mistakes. +* Make domain-specific vocabulary more user-friendly. +* Define misspellings and typos to transparently handle common mistakes. ## How synonyms work in Elasticsearch -To use synonyms in {{es}}, you need to follow this workflow: +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 @@ -121,7 +121,7 @@ serverless: unavailable You can store your synonyms set in a file. -A synonyms set file needs to be uploaded to all your cluster nodes, and be located 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). +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). An example synonyms file: From d71a6a258126c647899fdcce05f3d2c89734c83b Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 26 Aug 2025 16:39:42 +0200 Subject: [PATCH 12/13] fix list punctuation --- solutions/search/full-text/search-with-synonyms.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/solutions/search/full-text/search-with-synonyms.md b/solutions/search/full-text/search-with-synonyms.md index 9a7cda15b0..7d1f0da467 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -35,9 +35,9 @@ Synonyms are words or phrases that share the same or similar meaning. Searching 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**: 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. ## Synonym rule formats @@ -97,8 +97,8 @@ You can create and manage synonym sets and synonym rules using the {{kib}} user To create a synonym set using the UI: 1. Navigate to **Elasticsearch** > **Synonyms** or use the [global search field](/explore-analyze/query-filter/filtering.md#_finding_your_apps_and_objects) -2. Click **Get started** -3. Enter a name for your synonym set +2. Click **Get started**. +3. Enter a name for your synonym set. 4. Add your synonym rules in the editor by adding terms to match against: - Add **Equivalent rules** by adding multiple equivalent terms. For example: `ipod, i-pod, i pod` - Add **Explicit rules** by adding multiple terms that map to a single term. For example: `i-pod, i pod => ipod` From be89d43d1a4ca05d58c740696ec61afcc2e76311 Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Tue, 26 Aug 2025 16:41:21 +0200 Subject: [PATCH 13/13] missed terminal period --- 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 7d1f0da467..0261a3e076 100644 --- a/solutions/search/full-text/search-with-synonyms.md +++ b/solutions/search/full-text/search-with-synonyms.md @@ -96,7 +96,7 @@ You can create and manage synonym sets and synonym rules using the {{kib}} user To create a synonym set using the UI: -1. Navigate to **Elasticsearch** > **Synonyms** or use the [global search field](/explore-analyze/query-filter/filtering.md#_finding_your_apps_and_objects) +1. Navigate to **Elasticsearch** > **Synonyms** or use the [global search field](/explore-analyze/query-filter/filtering.md#_finding_your_apps_and_objects). 2. Click **Get started**. 3. Enter a name for your synonym set. 4. Add your synonym rules in the editor by adding terms to match against: