On this page
- 1. The different types of synonyms
- 2. Add and manage synonyms
- 3. Synonyms and plurals
- 4. Synonyms that don’t produce the same results
- 5. Dynamic Synonym Suggestions
- 6. Cascading synonyms
- 7. Ambiguous synonyms
- 8. Multi-word synonym matching
- 9. Keyword attributes as an alternative to synonyms
- 10. Further reading
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
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.
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”.
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
- Doesn’t match records containing
High degree Definitionor
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.