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.

This feature is only available on Premium plans.

Getting started

To get started with Dynamic Synonym Suggestions, go to the AI Synonyms page in the sidebar of the dashboard. 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 application 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.

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 dropdown between the two terms of the 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 would also find wallets. This might not be the desired outcome. To see alternative suggestions for this synonym, click on More options at the right of the suggestion. This reveals a dropdown with other suggestions such as card holder ⇔ card wallet.

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

Accepting or rejecting synonyms

When you’re happy with the suggested synonym, you can accept the synonym by pressing the button with the checkmark (✓). If you want to reject the synonym, click the button with the cross (x).

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 be able 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.