🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
Guides / Algolia AI

Dynamic Synonym Suggestions

Synonyms are a powerful tool for tweaking the relevance of your search. They tell Algolia to treat different words as equal so that it’s easier for your users to find what they’re looking for. For example, if your records contain the keyword “pants”, but your users search for “trousers”, adding the synonym trousers ⇔ pants ensures that your users find relevant search results.

Identifying the synonyms you should add can involve many manual steps. You have to check the queries that return no or almost no results, find the closest synonym that would match the records you expect, and then create these synonyms.

The Dynamic Synonym Suggestions feature automates this process for you. Using AI, Algolia identifies queries your users often change and proposes synonyms for them. For example, if Algolia AI detects that users search for “trousers” and then change their query to “pants”, it can suggest the synonym trousers ⇔ pants. All you have to do is accept or decline the suggested synonym. You can also tweak the suggestion before accepting it, if you think there’s a better alternative.

Dynamic Synonym Suggestions is available on the Build and Premium pricing plans.

Getting started

To get started with Dynamic Synonym Suggestions, go to the AI Synonyms page in the dashboard’s sidebar. From here, you can review, modify, accept, and decline the synonyms that Algolia AI suggests.

Reviewing synonyms

Ready-for-review synonym suggestions appear in the Suggested Synonyms tab. Initially, you may not find any suggestions there: your app needs a certain amount of search traffic for Algolia AI to generate synonyms reliably. It may take some time to reach this threshold, depending on your usage. The dashboard warns if you don’t have enough traffic to generate synonym suggestions.

By default, the Suggested Synonyms tab shows only the newest synonym suggestions. You can review older suggestions by turning off the Show only new synonyms toggle at the top of the suggestions list.

Each suggestion has an explanation that provides context on why Algolia AI suggests it. For example, if the algorithm proposes a synonym for trousers ⇔ pants, it tells you that users often rewrite the query “blue trousers” as “blue pants”. Each suggestion also displays a confidence score. This score measures how certain the AI is that this is a useful synonym (on a scale of 0 to 100). For instance, any suggestion with a score of 90 is likely to be an excellent synonym.

A synonym with a confidence score of 90

While Algolia AI can suggest synonyms based on your users’ searches, it doesn’t decide the best type of synonym. It’s up to you to decide which type works best for the suggested synonym. By default, the AI proposes a two-way synonym. You can change this to a one-way synonym or alternative correction using the drop-down menu between the two terms of the synonym.

Changing the type of the suggested synonym

Tweaking synonyms

You can also change suggested synonyms. For example, if Algolia AI finds that users rewrite the query “card holder” to “card wallet”, a suggested synonym could be holder ⇔ wallet. If you enable this suggestion as is, if your users search for “holder”, they will also find wallets, but this might not be the desired outcome. To see alternative suggestions for this synonym, click More options at the right of the suggestion. This reveals a menu with other suggestions, such as card holder ⇔ card wallet.

A list with other suggestions for this synonym

You can also tweak synonyms by clicking the edit button and replacing the initial suggestion with what you think will have more impact.

Editing suggested synonyms manually

Accepting or rejecting synonyms

If you’re happy with the suggested synonym, accept it by clicking the checkmark (✓) button. To reject the synonym, click the cross (x) button.

If your index has replicas and you don’t want to copy accepted synonyms to these replicas, turn off the Forward to replicas setting at the top of the AI Optimization page.

Once you accept a synonym, you should only change it from the dashboard. Changing these synonyms with an API client can lead to data inconsistencies and should be avoided.

You can view all the synonyms you’ve accepted in the past in the Accepted Synonyms tab. All your rejected synonyms show up on the Declined Synonyms tab.

Set up Dynamic Synonym Suggestions

For Dynamic Synonym Suggestions to work, the algorithm needs to identify the rewrite patterns of individual users. This requires a unique identifier in the search parameters for each user in the form of the userToken parameter.

Did you find this page helpful?