Adding synonyms

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

You can also create synonym groups—for example, pants ⇔ trousers ⇔ slacks. In this case, a search for “slacks” finds “pants” and “trousers”, and “pants” finds “trousers” and “slacks”.

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

Sometimes using synonyms can lead to surprising or undesirable results.

The different types of synonyms

Algolia has these types of synonyms:

• Regular synonyms: if you want a word or phrase to find its synonyms and the other way around.
• One-way synonyms: if you want a word or phrase to find its synonyms but not the reverse.
• Alternative corrections: if you want records with an exact query match to rank higher than a synonym match.
• Placeholders: if you want 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 if you defined a synonym for these two words. When you search for “swimsuit”, Algolia searches for “swimsuit”, typos of “swimsuit”, synonyms of “swimsuit”, plurals, and other alternatives of “swimsuit”.

Different results for synonyms are 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 too use-case dependent.

You can use search analytics to investigate whether you need to add a synonym. Especially by looking at the search queries with little or no results, you can get a good idea of which synonyms you’ll need to configure.

Dynamic Synonym Suggestions

Dynamic Synonym Suggestions automate synonym generation based on your users’ behavior.

Algolia identifies any queries your users enter (and subsequently alter) and suggests them as synonyms. For example, if Algolia detects that users search for “trousers” and then change their query to “pants”, Dynamic Synonym Suggestions can suggest the synonym trousers ⇔ pants. If you accept the suggestion, a new synonym is added automatically.

Cascading synonyms

Synonyms don’t cascade. If you have two pairs of synonyms—for example, pants ⇔ trousers and trousers ⇒ slacks, a search for “pants” matches “trousers”, but doesn’t match “slacks”.

If you want a cascading behavior, create a regular synonyms group, such as pants ⇔ trousers ⇔ slacks. In this case, a search for “pants” matches “trousers” and “slacks”.

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 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” search will be flooded with “Xerox” results, and a search for “xerox” 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.

Keyword attributes as an 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.

Further reading