Update synonyms documentation for Meilisearch by anujagnihotry · Pull Request #3579 · meilisearch/documentation

anujagnihotry · 2026-05-17T04:57:57Z

Clarified the behavior of synonym handling in Meilisearch, including limitations on term length and maximum synonyms per term.

Description

Checklist

For internal Meilisearch team member only:

I checked and followed our internal guidelines
⚠️ I updated the code samples according to our internal guidelines

For external maintainers

Did you use any AI tool while implementing this PR (code, tests, docs, etc.)? If yes, disclose it in the PR description and describe what it was used for. AI usage is allowed when it is disclosed.
Have you made sure that the title is accurate and descriptive of the changes?

Summary by CodeRabbit

Documentation
- Updated synonyms documentation with improved example formatting
- Added new section explaining synonym term length limitation (1-3 words supported)
- Included guidance on workarounds for longer synonym phrases

Clarified the behavior of synonym handling in Meilisearch, including limitations on term length and maximum synonyms per term.

coderabbitai · 2026-05-17T04:58:12Z

📝 Walkthrough

Walkthrough

Documentation in synonyms.mdx was updated to clarify Meilisearch synonym matching constraints. The multi-word synonym example was reformatted, and a new section was added explaining that synonym matches only work for terms of 1 to 3 words, with guidance to use shorter terms or split longer phrases.

Changes

Synonym documentation update

Layer / File(s)	Summary
Synonym term limitation documentation and reformatting `capabilities/full_text_search/relevancy/synonyms.mdx`	The multi-word synonym example text was reflowed for readability. A new section, "Synonym term length limitation," was added explaining that Meilisearch returns synonym matches only for 1–3 word terms, with an example of `"lord of the rings"` / `"lotr"` behavior and guidance to split longer phrases into shorter terms.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A bunny hops through docs so bright,
Adding limits, making things right,
Three words max for synonyms to sing,
"LOTR" and "Lord of the Ring,"
Clarity blooms—hop, hop, delight! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly describes the main change: updating documentation for Meilisearch synonyms functionality.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

🧹 Nitpick comments (1)

capabilities/full_text_search/relevancy/synonyms.mdx (1)
183-183: ⚡ Quick win

Split this sentence into two shorter sentences.

This line is dense and harder to scan in docs; splitting it would improve readability without changing meaning.

As per coding guidelines, "Prefer shorter sentences; if a sentence runs over approximately 40 words, consider splitting or simplifying".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@capabilities/full_text_search/relevancy/synonyms.mdx` at line 183, The
sentence explaining the synonym behavior (the example using "lord of the rings"
and "lotr") is too long; split it into two shorter, clearer sentences: first
state that setting "lord of the rings" as a synonym for "lotr" makes searches
for "lotr" return documents containing "lord of the rings", then in a separate
sentence note that searching for "lord of the rings" will not return documents
containing "lotr" because the search term has more than three words (keep the
wording about the 3-word limit). Ensure both sentences appear in the same
paragraph in capabilities/full_text_search/relevancy/synonyms.mdx where the
original line occurs.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@capabilities/full_text_search/relevancy/synonyms.mdx`:
- Line 183: The sentence explaining the synonym behavior (the example using
"lord of the rings" and "lotr") is too long; split it into two shorter, clearer
sentences: first state that setting "lord of the rings" as a synonym for "lotr"
makes searches for "lotr" return documents containing "lord of the rings", then
in a separate sentence note that searching for "lord of the rings" will not
return documents containing "lotr" because the search term has more than three
words (keep the wording about the 3-word limit). Ensure both sentences appear in
the same paragraph in capabilities/full_text_search/relevancy/synonyms.mdx where
the original line occurs.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a3291a1f-9616-42b1-b7e0-7063d6f71fb1

📥 Commits

Reviewing files that changed from the base of the PR and between 31660b4 and 0d47a81.

📒 Files selected for processing (1)

capabilities/full_text_search/relevancy/synonyms.mdx

CaroFG

Thanks a lot for adding this! It's a useful edge case that's easy to miss and good to have documented! I requested a few changes, specifically around the workaround suggestion. I also noticed an unrelated section had been accidentally split into two paragraphs, so I removed the extra spacing.

CaroFG · 2026-06-09T09:40:43Z

+
+For example, if you set `"lord of the rings"` as a synonym for `"lotr"`, searching for `"lotr"` will return documents containing `"lord of the rings"`. However, if you search for `"lord of the rings"`, Meilisearch will not return documents containing `"lotr"` because the search term has more than 3 words.
+
+This limitation applies regardless of how you configure your synonyms. To work around this, consider using shorter synonym terms or breaking longer phrases into multiple single-word synonyms.


Suggested change

This limitation applies regardless of how you configure your synonyms. To work around this, consider using shorter synonym terms or breaking longer phrases into multiple single-word synonyms.

The workaround as written would lead to odd configurations like mapping 'of the ring' → 'lotr', which isn't really meaningful. Also, breaking "lord of the rings" into lord, rings etc. as synonyms for 'lotr' would match completely unrelated documents.

I agree with you. I would prefer not to propose workarounds for now. I'll work on the synonyms storage this week if I have time, and maybe improve the situation around this limitation.

CaroFG · 2026-06-09T09:41:01Z


-If you input `SF` as a search query, Meilisearch will also return results containing the phrase `San Francisco`. However, depending on the ranking rules, they might be considered less [relevant](/capabilities/full_text_search/relevancy/relevancy) than those containing `SF`. The reverse is also true: if your query is `San Francisco`, documents containing `San Francisco` may rank higher than those containing `SF`.
+If you input `SF` as a search query, Meilisearch will also return results containing the phrase `San Francisco`. 
+


Suggested change

CaroFG · 2026-06-09T09:41:10Z

-If you input `SF` as a search query, Meilisearch will also return results containing the phrase `San Francisco`. However, depending on the ranking rules, they might be considered less [relevant](/capabilities/full_text_search/relevancy/relevancy) than those containing `SF`. The reverse is also true: if your query is `San Francisco`, documents containing `San Francisco` may rank higher than those containing `SF`.
+If you input `SF` as a search query, Meilisearch will also return results containing the phrase `San Francisco`. 
+
+


Suggested change

CaroFG · 2026-06-09T09:41:18Z

+If you input `SF` as a search query, Meilisearch will also return results containing the phrase `San Francisco`. 
+
+
+


Suggested change

Kerollmops

Hello @anujagnihotry 👋 Thanks for the PR, would you mind applying the suggestions, please? Have a nice day 🌵

Update synonyms documentation for Meilisearch

0d47a81

Clarified the behavior of synonym handling in Meilisearch, including limitations on term length and maximum synonyms per term.

coderabbitai Bot reviewed May 17, 2026

View reviewed changes

curquiza requested a review from Kerollmops May 18, 2026 12:26

CaroFG requested changes Jun 9, 2026

View reviewed changes

CaroFG mentioned this pull request Jun 9, 2026

Complete synonym documentation #3594

Open

3 tasks

Kerollmops requested changes Jun 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update synonyms documentation for Meilisearch#3579

Update synonyms documentation for Meilisearch#3579
anujagnihotry wants to merge 1 commit into
meilisearch:mainfrom
anujagnihotry:patch-1

anujagnihotry commented May 17, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 17, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

CaroFG left a comment

Uh oh!

CaroFG Jun 9, 2026

Uh oh!

Kerollmops Jun 15, 2026

Uh oh!

CaroFG Jun 9, 2026

Uh oh!

CaroFG Jun 9, 2026

Uh oh!

CaroFG Jun 9, 2026

Uh oh!

Kerollmops left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		For example, if you set `"lord of the rings"` as a synonym for `"lotr"`, searching for `"lotr"` will return documents containing `"lord of the rings"`. However, if you search for `"lord of the rings"`, Meilisearch will not return documents containing `"lotr"` because the search term has more than 3 words.

		This limitation applies regardless of how you configure your synonyms. To work around this, consider using shorter synonym terms or breaking longer phrases into multiple single-word synonyms.


		If you input `SF` as a search query, Meilisearch will also return results containing the phrase `San Francisco`. However, depending on the ranking rules, they might be considered less [relevant](/capabilities/full_text_search/relevancy/relevancy) than those containing `SF`. The reverse is also true: if your query is `San Francisco`, documents containing `San Francisco` may rank higher than those containing `SF`.
		If you input `SF` as a search query, Meilisearch will also return results containing the phrase `San Francisco`.

Conversation

anujagnihotry commented May 17, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

CaroFG left a comment

Choose a reason for hiding this comment

Uh oh!

CaroFG Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

Kerollmops Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

CaroFG Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

CaroFG Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

CaroFG Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

Kerollmops left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anujagnihotry commented May 17, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 17, 2026 •

edited

Loading