Merge branch 'master' into v0.29

Author: guimachiavelli

.code-samples.meilisearch.yaml

@@ -965,6 +965,13 @@ settings_guide_faceting_1: |-
     --data-binary '{
       "maxValuesPerFacet": 5
     }'
+synonyms_guide_1: |-
+  curl \
+    -X PUT 'http://localhost:7700/indexes/movies/settings/synonyms' \
+    -H 'Content-Type: application/json' \
+    --data-binary '{
+      "great": ["fantastic"], "fantastic": ["great"]
+    }'
 getting_started_faceting: |-
   curl \
     -X PATCH 'http://localhost:7700/indexes/movies/settings/faceting' \
@@ -979,4 +986,3 @@ getting_started_pagination: |-
     --data-binary '{
       "maxTotalHits": 500
     }'
-    

.vuepress/public/sample-template.yaml

@@ -148,6 +148,7 @@ get_faceting_settings_1: |-
 update_faceting_settings_1: |-
 reset_faceting_settings_1: |-
 settings_guide_faceting_1: |-
+synonyms_guide_1: |-
 getting_started_faceting: |-
 getting_started_pagination: |-
 getting_started_front_end_integration_md: |-

learn/configuration/settings.md

@@ -234,7 +234,7 @@ Suppose you would like to search `the mask` in a movie database. Since `the` is
 
 ## Synonyms
 
-A set of words defined for an index. Synonyms are **different words that have the same meaning**, and thus are treated similarly. If either of the associated words is searched, the same results will be displayed.
+A set of words defined for an index. Synonyms are **different words that have the same meaning**, and thus are treated similarly. When searching for one word, you will also get some of the same results as the other associated word.
 
 `synonyms=<Object>`
 

learn/configuration/synonyms.md

@@ -2,8 +2,15 @@
 
 If multiple words have an equivalent meaning in your dataset, you can [create a list of synonyms](/reference/api/settings.md#update-synonyms). This will make your search results more relevant.
 
-In general, **a search on a word will return the same results as a search on any of its synonyms**.
-There is one exception to this rule, [detailed below](#multi-word-phrases).
+Words set as synonyms won't always return the same results. With the default settings, the `movies` dataset should return 547 results for `great` and 66 for `fantastic`. Let's set them as synonyms:
+
+<CodeSamples id="synonyms_guide_1" />
+
+With the new settings, searching for `great` returns 595 results and `fantastic` returns 423 results. This is due to various factors like [typos](/learn/configuration/typo_tolerance.md#minwordsizefortypos) and [splitting the query](/learn/advanced/concat.md#split-queries) to find relevant documents. The search for `great` will allow only one typo (e.g. `create`) and take into account all variations of `great` (e.g. `greatest`) along with `fantastic`.
+
+::: warning
+The number of search results may vary depending on changes to the `movies` dataset.
+:::
 
 ## Normalization
 

learn/core_concepts/indexes.md

@@ -81,7 +81,7 @@ Designate the distinct attribute using the [update settings endpoint](/reference
 
 ### Synonyms
 
-Your dataset may contain words with similar meanings. For these, you can define a list of synonyms: words that will be treated as the same or similar for search purposes.
+Your dataset may contain words with similar meanings. For these, you can define a list of synonyms: words that will be treated as the same or similar for search purposes. Words set as synonyms won't always return the same results due to factors like typos and splitting the query.
 
 Since synonyms are defined for a given index, they won't apply to any other index on the same Meilisearch instance. You can create your list of synonyms using the [update settings endpoint](/reference/api/settings.md#update-settings) or the [update synonyms endpoint](/reference/api/settings.md#update-synonyms).
 

learn/getting_started/customizing_relevancy.md

@@ -126,7 +126,7 @@ The `synonyms` array lets you associate certain words in your dataset, telling M
 
 <CodeSamples id= "getting_started_synonyms" />
 
-This will set `winnie` and `piglet` as synonyms; searching for either word will show the same results.
+This will set `winnie` and `piglet` as synonyms. Searching for either won't always return the same results due to factors like typos and splitting the query.
 
 You can read more about it in our [dedicated guide](/learn/configuration/synonyms.md).