On this page
Synonyms tell the engine which words and expressions should be considered equal - for example,
pants ⇔ trousers or
mad ⇔ angry. A search for “trousers” will find “pants”, and “pants” will find “trousers”.
You can also create synonym groups. For example, you can add “slacks” to the “pants, trousers” group. So a search for slacks will find pants and trousers, and pants will find trousers and slacks, and so on.
Finally, prefix search is also enabled on the synonym, so if your data includes only trousers, but a user searches for pants, then searches for
pan would start showing results - for both “pants” and “trousers”.
While synonyms are powerful, sometimes they can lead to surprising or undesirable results. Accordingly, they should be used 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 3 other types of synonyms which can be useful in certain contexts:
1. 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 tablets. You do this by using one-way synonyms.
2. Alternative corrections
Records with the original term and records with the synonym all have the same ranking, all other things being equal.
If you would like records with the original term to be ranked higher than those with the synonym, alternative corrections are the solution. Alternative corrections are just like one-way synonyms, except they will generate matches with typos.
Placeholders allow you to place not-yet-defined “tokens” that can take any value from a list of defined words.
For example, “iPhone
Add and Manage Synonyms
You can manage your synonyms (add, edit, delete) via the Dashboard or the API. You can manage them one-by-one, or in batches, or by importing JSON or CSV files.
What does “Forward to replica indices” mean?
Any synonyms that you create, edit, or delete can be automatically propagated to an index’s replica indices. This is the default behavior. If you don’t want synonyms to apply to an index’s replicas, make sure the box is unchecked.
Synonyms and Plurals
Synonyms do not find plurals. So if you create a “boot” = “shoe” synonym, you’ll have the following behavior:
- “boot” will find “shoe” and “shoes”
- but the plural “boots” will not find “shoe” or “shoes”
You will need to create a new synonym for “boots” that does the same as “boot”. More generally, you’ll need a synonym for every word that you want both the singular and plural to be synonymous.
Algolia does not provide a Synonyms dictionary
Algolia does not provide any built-in synonym dictionary. The reasoning behind this is that synonyms are very use-case dependent. Each customer has its own goals, which relies on a unique vocabulary and language in describing its products and services. No single dictionary can adequately cover this variety.
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.
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. This can be done via the Dashboard or using the API.
Synonyms don’t cascade. This means that if you set two separate synonyms pairs — for example
pants ⇒ trouser and
trouser ⇒ slacks,
pants won’t match
slacks. We don’t allow cascading - to avoid unexpected side-effects and to give you full control over your synonym strategy. If you want this, you’ll need to create the regular synonym group “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 above 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’ll get the same result as synonyms.
Synonyms are powerful, but sometimes they can lead to surprising or undesirable results. Accordingly, they should be used sparingly.
Look out for words with multiple meanings, like “baskets” in the synonym “sneakers = baskets”. When users type “sneaker”, they will see an odd mix of high-top basketball sneakers and hand-knit storage baskets.
Look out for common words. Take “photocopier = xerox”, where a search for “photocopier” will be flooded with xerox, and a search for “xerox” will be flooded with non-xerox photocopiers.
What often happens in these situations is that a customer creates many ambiguous synonyms and then tries to correct them with other settings, like adding additional synonyms, or adding query rules or optional filters, or changing engine settings like typo tolerance.