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

Algolia’s prefix search feature means that even partial searches like “p”, “pa”, or “pan” will yield results for both “pants” and “trousers”.

However, synonyms can sometimes produce unexpected or unwanted outcomes.

The different types of synonyms

Algolia has these types of synonyms:

• Regular synonyms: use if you want a word or phrase to find its synonyms and vice versa. For example, if “motorcycle” and “bike” are regular synonyms, searching for either word will show results for both.
• One-way synonyms: use if you want a word or phrase to find its synonyms but not the reverse. For example, if “apple” is a one-way synonym for “iphone”:
  • Searching for “iphone” will show “apple” and “iphone” results
  • Searching for “apple” won’t show “iphone” results.
• Alternative corrections prioritize exact matches over synonym matches. If you search for a specific phrase, records that exactly match that phrase will rank higher than records that match a synonym.
• Placeholders are tokens that can take any value from a predefined list of words

How to add and manage synonyms

From Algolia’s dashboard, API, or the Algolia CLI, you can control your synonyms: add new ones, make changes to existing ones, or delete them. You can do this one at a time, in batches, or by uploading files in JSON or CSV format.

Synonyms and plurals

Algolia synonyms don’t recognize plural forms. For example, if you create a “boot” = “shoe” synonym:

• If you search for “boot”, it will show results for both “shoe” and “shoes”
• If you search for “boots”, it doesn’t show results for “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 mean that searches for those terms will return the same results.

For example, even if you made “swimwear” and “swimsuit” synonyms, you might still get different results when you search for each term. This is because, for a “swimsuit” query, Algolia searches for “swimsuit” and for typos, synonyms, plurals, and other variations 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 example, if you want “swimwear” to produce the same results as “swimsuit”, create a rule that changes the query “swimwear” to “swimsuit”.

Algolia doesn’t provide a synonym 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 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 can be helpful, but they can also sometimes cause unexpected or unwanted results. It’s best to use them sparingly.

You might have set up synonyms that yielded ambiguous results and then tried to correct them with other adjustments, like adding more synonyms, creating rules or optional filters, or tweaking 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