Synonyms

Synonyms tell Algolia which words and expressions to consider equal. For example, if pants is a synonym for trousers, a search for “trousers” also returns “pants” and a search for “pants” also returns “trousers”.

Since Algolia uses prefix search, partial searches like “pa”, or “pan” return results for both “pants” and “trousers”.

Manage synonyms# Found an issue? Edit this guide A Edit this guide

You can add new synonyms, edit, or delete existing ones in the Algolia dashboard, the Search API, or the Algolia CLI.

Synonym types# Found an issue? Edit this guide A Edit this guide

Algolia supports different types of synonyms for different use cases.

Regular synonyms#

Each word in a list of regular synonyms can be replaced by others from the list. For example, in the list ["pants", "trousers", "slacks"], a search for “trousers” returns records with “pants” or “slacks”, and a search for “pants” returns records with “trousers” or “slacks”.

Regular synonyms can be represented by the following JSON:

1
2
3
4
5
6
7
8
9
{
   "objectID": "a-list-of-2-synonyms",
   "type": "synonym",
   "synonyms": [
      "pants",
      "trousers",
      "slacks"
   ]
}

One-way synonyms#

Use one-way synonyms 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 an “iPad” search to find all tablets. Searching for “iPad” shouldn’t display tablets from other brands.

One-way synonyms can be represented by the following JSON:

1
2
3
4
5
6
7
8
9
{
   "objectID": "a-unique-identifier",
   "type": "oneWaySynonym",
   "input": "tablet",
   "synonyms": [
      "ipad",
      "galaxy tab"
   ]
}

Alternative corrections#

Alternative corrections are synonyms that aren’t exact matches and are treated as words with one or two typos. Use them when you want to rank exact matches higher than synonym matches.

For example, compare one-way and alternative correction synonyms for cell <=> mobile:

• One-way. A query for “cell” returns records containing “mobile” as 0 typo results.
• Alternative correction (one typo). A query for “cell” returns records containing “cell” first (as 0 typo results), then records with “mobile” (as 1 typo results).
• Alternative correction (two typos). A query for “cell” returns records containing “cell” first (as 0 typo results), then records with “cel*” (as 1 typo results), then records with “mobile” (as 2 typo results).

An alternative correction synonym that accounts for one typo can be represented by the following JSON:

1
2
3
4
5
6
{
  "objectID": "a-unique-identifier",
  "type": "altCorrection1",
  "word": "trousers",
  "corrections": ["pants"]
}

An alternative correction that accounts for two typos can be represented by the following JSON:

1
2
3
4
5
6
{
  "objectID": "a-unique-identifier",
  "type": "altCorrection2",
  "word": "trousers",
  "corrections": ["pants"]
}

Placeholders#

A placeholder is a part of the search query that can be replaced by any value from a list of words as synonyms.

Consider a shop that sells iPhone cases. The iPhone 13 and 14 have similar dimensions, so some cases will fit both versions. Instead of duplicating the same record for each version it applies to, you can define a placeholder in your records:

1
2
3
4
5
6
[
  {
    "product_name": "Case for iPhone <model>",
    "sku": "123456"
  }
]

Then, you can define a placeholder synonym for the <model> placeholder:

1
2
3
4
5
{
   "type": "placeholder",
   "placeholder": "<model>",
   "replacements": ["13", "14"]
}

Now, searches for “case iphone 13” or “case iphone 14” return the correct record, with <model> replaced by the model from the search query.

Placeholder synonyms only work when one record applies to variations of the query. If you need to show different information for each variation, for example, different product information or images between versions, it’s better to use one record for each variation, and then using the distinct parameter to deduplicate the variations. For more information, see Grouping results.

Synonyms and plurals# Found an issue? Edit this guide A Edit this guide

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

• A search for “boot” shows results for both “shoe” and “shoes”
• A search for “boots” 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 don’t produce the same results# Found an issue? Edit this guide A Edit this guide

Creating synonyms between terms doesn’t mean that searches for those terms 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# Found an issue? Edit this guide A Edit this guide

Algolia doesn’t provide a built-in synonym dictionary because synonyms are too use-case dependent.

Use search analytics to investigate whether you need to add a synonym. Look for search queries with little or no results. To automate this, activate Dynamic Synonym Suggestions.

Cascading synonyms# Found an issue? Edit this guide A Edit this guide

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 cascading behavior, create a list of regular synonyms, such as pants ⇔ trousers ⇔ slacks. In this example, a search for “pants” matches “trousers” and “slacks”.

Ambiguous synonyms# Found an issue? Edit this guide A Edit this guide

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 settings such as typo tolerance.

To avoid this, look out for:

• Words with several meanings, like “baskets” in the synonym sneakers ⇔ baskets. Users searching for “sneaker” might 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 might show many “Xerox” results, and a search for “xerox” might show many non-Xerox photocopiers.

Multi-word synonym matching# Found an issue? Edit this guide A Edit this guide

Multi-word synonyms match by sequence expression: they must be in the correct order with nothing in-between.

For example, if you have a synonym pair HD ⇔ High Definition and search for HD, the search first matches records with “High Definition”, but doesn’t match records with “High Resolution Definition” or “Definition High”.

Keyword attributes as an alternative to synonyms# Found an issue? Edit this guide A Edit this guide

You can include an attribute with a list of relevant keywords as an alternative to synonyms. For example, instead of using synonyms (like slacks, trousers, and 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# Found an issue? Edit this guide A Edit this guide