Adding Synonyms

Synonyms tell the engine which words and expressions to consider equal - for example, pants ⇔ trousers, or mad ⇔ angry. A search for “trousers” also returns “pants”, and a search for “pants” also returns “trousers”.

You can also create synonym groups. For example, you can add “slacks” to the “pants, trousers” group: pants ⇔ trousers ⇔ slacks. In this case, a search for “slacks” finds “pants” and “trousers”, and “pants” finds “trousers” and “slacks”.

Finally, prefix search is also enabled on the synonym, so if your data includes “trousers”, and a user searches for pants, any searches for p, pa, pan would show results for both “pants” and “trousers”.

While synonyms are powerful, sometimes they can lead to surprising or undesirable results. Accordingly, you should use them sparingly.

The different types of synonyms

Algolia has four types of synonyms:

• Regular synonyms. Use them when you want a word or phrase to find its synonyms or the other way around.
• One-way synonyms. Use them when you want a word or phrase to find its synonyms, but not the reverse.
• Alternative corrections. Use them when you want records with an exact query match to rank higher than a synonym match.
• Placeholders. Use them to place not-yet-defined “tokens” (that can take any value from a list of defined words).

Add and manage synonyms

You can manage your synonyms (add, edit, delete) from Algolia’s Dashboard or the API. You can manage them individually, in batches, or by importing JSON or CSV files.

Synonyms and plurals

Synonyms don’t find plurals. For example, if you create a “boot” = “shoe” synonym, you get the following behavior:

• “boot” returns “shoe” and “shoes”
• The plural “boots” doesn’t return “shoe” or “shoes”

To find plurals, you must create a synonym for every word that you want both the singular and the plural to be synonymous. For example, create a new synonym for “boots” that does the same as “boot”.

Synonyms that don’t produce the same results

Creating synonyms between terms doesn’t ensure that searches for those terms will return the same results.

For example, it’s expected to have different results for the queries “swimwear” and “swimsuit” even when you have a synonym between those two words. When you perform the query “swimsuit”, Algolia searches for “swimsuit”, typos of “swimsuit”, synonyms of “swimsuit”, plurals and other alternatives of “swimsuit”.

In the end, having different results for synonyms is expected because the search for typos, plurals, and other alternatives isn’t performed on the same words.

If you want two queries to have the same results, it’s best to create a Rule that replaces one word in your query with another. For the previous example, if you want the query “swimwear” to produce the same results as “swimsuit”, you should create a Rule that replaces the query “swimwear” with “swimsuit”.

Algolia doesn’t provide a synonyms dictionary

Algolia doesn’t provide a built-in synonym dictionary because synonyms are very use-case dependent. Each customer has their own goals, relying on a unique vocabulary and language to describe their products and services, and no single dictionary can adequately cover this variety.

Create a personalized list from the dashboard or use one of the API clients.

One way to know which synonyms to add for your use-case is to use Algolia’s analytics feature. By looking at the top queries, especially those with little or no results, you can get a good idea of which synonyms you’ll need to configure.

Dynamic Synonym Suggestions

The Dynamic Synonym Suggestions feature automates synonym generation based on your users’ behavior.

Algolia’s AI identifies any queries your users enter (and subsequently alter) and suggests them as synonyms. For example, if the 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, edit, or decline the suggested synonym.

Cascading synonyms

Synonyms don’t ‘cascade’. This means that if you have two synonyms pairs-for example, pants ⇒ trouser and trouser ⇒ slacks, pants doesn’t match slacks.

The benefit of this non-cascading behavior is that it avoids unexpected side effects.

If you want a cascading behavior, you need to create a regular synonym group. For example, “slacks, pants, trousers”.

Ambiguous synonyms

Synonyms are powerful, but sometimes they can lead to surprising or undesirable results. Accordingly, you should use them sparingly.

You may have created ambiguous synonyms and then tried to correct them with other settings, like adding more synonyms, Rules, or optional filters, or changing engine settings such as typo tolerance. To avoid this, look out for:

• Words with multiple meanings, like “baskets” in the synonym “sneakers = baskets”. Users who type “sneaker” will see an odd mix of high-top basketball sneakers and hand-knit storage baskets.
• Common words. For example, if you create the synonym “photocopier = xerox”: a “photocopier” query will be flooded with “Xerox” results, and a “xerox” query will be flooded with non-Xerox photocopiers.

Multi-word synonym matching

Multi-word synonyms match by sequence expression, meaning they must be in the correct order with nothing in-between.

For example, assuming you have a synonym pair HD ⇔ High Definition and a query HD, that query:

• Matches records containing High Definition
• Doesn’t match records containing High degree Definition or Definition High.

Keywords attributes as alternative to synonyms

You can include an attribute with a list of relevant keywords as an alternative to synonyms. For example, instead of using the preceding synonyms (slacks, trousers, pants), you can add an other_words attribute to every record for “pants”, with the values other_words: trousers, slacks. By making other_words a searchable attribute, you get the same result as synonyms.