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, then 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

Regular synonyms (default)

Synonyms are, by default, mutually equivalent; that is, each word signifies the other. “Pants” = “trousers” and “trousers” = “pants”. You can have groups. “Slacks” = “pants” = “trousers”.

Other types of synonyms

Algolia provides three other types of synonyms which can be helpful in specific contexts:

• One-way synonyms
• Alternative corrections
• Placeholders.

One-way synonyms

Use this when you want a word or phrase to find its synonyms, but not the reverse.

For example, you want “tablet” to find “iPad” so that iPads show up on all “tablet” searches. However, you don’t want the reverse: you don’t want an “iPad” search to find all tablets. For example, searching for “iPad” shouldn’t display “galaxy” tablets. You do this by using one-way synonyms.

Alternative corrections

Alternative corrections are similar to one-way synonyms but ranked differently: Algolia ranks matches on the corrected terms—the synonyms—lower than an exact match on a query term.

Use alternative corrections when you want records with an exact query match to rank higher than a synonym match. For example, consider the pants ⇔ trousers synonym. Although you want searches for “pants” or “trousers” to return all records with either “pants” or “trousers”, you might want a search for “trousers” to rank results with “dress trousers” higher than results with “casual pants”. This is helpful when you need to use alternative corrections: trousers → pants, typo 1, which means that the query “trousers” ranks records including “trousers” higher than records including “pants”.

Alternative corrections are thus just like one-way synonyms, except they generate matches with typos to create a different ranking between the synonyms. You can choose to have an alternative correction count as one typo or two.

Placeholders

Placeholders allow you to place not-yet-defined “tokens” that can take any value from a list of defined words.

For example, “iPhone <version>” can mean “iPhone 7” or “iPhone 5S”. Essentially “<version>” can be replaced by any of the following: “3G”, “3GS”, “4”, “4S”, “5”, “5C”, “5S”, “6”, “6S”, “7”, “8”, “X”.

Add and manage synonyms

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

What does “Forward to replica indices” mean?

You can apply any synonyms that you create, edit, or delete to an index’s replica indices. This is the default behavior. If you don’t want synonyms to apply to an index’s replicas, ensure the box is unchecked.

Important considerations

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 plural to be synonymous. For example, create a new synonym for “boots” that does the same as “boot”.

Synonyms 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 search for “swimsuit”, typos of “swimsuit”, synonyms of “swimsuit”, and 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 the process of generating synonyms 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” 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.

Importing synonyms from a file

If you have many synonyms, perhaps sourced by a merchandising team or pulled from an external dictionary, you probably don’t want to add them one by one. You can do this by uploading an entire file of synonyms at once from the dashboard or using the API.

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”.

Alternative to synonyms

As an alternative to synonyms, you can include an attribute with a list of relevant keywords. 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.

Ambiguous synonyms

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

• Look out for words with multiple meanings, like “baskets” in the synonym “sneakers = baskets”. When users type “sneaker”, they see an odd mix of high-top basketball sneakers and hand-knit storage baskets.
• Look out for common words. Take “photocopier = xerox”: a search for “photocopier” will be flooded with “xerox” results, and a search for “xerox” will be flooded with non-xerox photocopiers. What often happens in these situations is that a user creates many ambiguous synonyms and then tries to correct them with other settings, like adding extra synonyms, Rules, or optional filters, or changing engine settings like typo tolerance.

Multi-word synonym matching

Multi-word synonyms match by sequence expression, meaning 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.