17 Oct 2018


Synonyms overview

Synonyms tell the engine about sets of words and expressions that should be considered equal — for example, jacket ⇔ parka or mad ⇔ angry.

Prefix search is also enabled on the synonym, so if a data set included only jackets, but a user searched for parkas, searches for p, pa, par would start showing results.

While synonyms are powerful, their use can also lead to surprising or unexpected results, and should be used sparingly. For many use cases, including an attribute with an array of relevant keywords is enough.

How Synonyms Are Stored

Synonyms are stored as regular JSON objects with:

  • a unique identifier, objectID, which can be use to update or delete later
  • a type attribute that reflects whether the synonym is regular, one-way, an alternative correction, or a placeholder.

Synonyms dictionary

Algolia does not provide any built-in synonym dictionary. The reasoning behind this choice is that synonyms are very use-case dependent.

You have to enter them yourself via the dashboard or using one of the API clients.

One way to know which synonyms to add for your use-case is to use Algolia analytics feature. By looking at the queries with no results you can have a clear idea of which synonyms you should configure.

Cascading synonyms

Synonyms don’t cascade, to avoid side-effects and give you full control on your synonym strategy. This means that if you set two separate synonyms pairs — for example jacket ⇒ parka and parka ⇒ raincoat, jacket won’t match raincoat.

Synonym Types

(Regular) two-way synonyms

Regular synonyms are bi-directional; searches for one term will also return matches on the other term, and vice versa. In the example below, searches for “jacket” will also return “parka.”

"jacket"  "parka"

Similarly, searching for “parka” will also return “jacket”:

"parka"  "jacket"

Regular synonyms look much like regular Algolia objects — they’re JSON objects. The synonyms themselves are represented by the array-valued synonyms attribute:

   "objectID": "a-unique-identifier",
   "type": "synonym",
   "synonyms": [
      "galaxy note"

However, regular synonyms are not typo-tolerant.

One-way synonyms

Sometimes, searches for one term should also yield results for another, but not in reverse. This is where one-way synonyms come in handy.

In the example below, searches for “tablet” should logically return “iPad” since iPads are just one type of tablet.

"tablet"  "iPad"

However, “iPad” is more specific than “tablet,” and probably shouldn’t return generic matches for “tablet”:

"iPad"  "tablet"

One-way synonyms are stored very similarly to regular synonyms; the only difference is that the type attribute is now oneWaySynonym.

   "objectID": "a-unique-identifier",
   "type": "oneWaySynonym",
   "input": "tablet",
   "synonyms": [
      "galaxy note"

Alternative Corrections

When creating synonyms, including one-way synonyms, records with the original term and records with the synonym will be ranked evenly, all other things being equal. When this is not the intended behavior, for example, if you would like records with the original term to 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.

There are two types of alternative corrections based on the type parameter: altCorrection1 will return matches with one typo, and altCorrection2 will return matches with two typos.

Alternative corrections do not support multi-word corrections, so galaxy note, for example, could be used as an input but not as a correction.

The following synonym defines an alternative correction with one typo:

   "objectID": "a-unique-identifier",
   "type": "altCorrection1",
   "word": "tablet",

This will create ranking where records with tablet will appear before those with ipad, since records with ipad will be considered as having 1 typo. Changing the type to altCorrection2 defines an alternative correction with two typos.


Placeholders allow you to define tokens that can take any value from a list of defined words. Use tokens in records when you want to match different possible values at this position without having the original token searchable.

For example, consider this record:

  "name": "iPhone <version>"

To create placeholders, enclose the desired terms in angle brackets. The angle-bracketed <version> above, for example, might refer to a placeholder defined as:

   "objectID": "a-unique-identifier",
   "type": "placeholder",
   "placeholder": "<version>",
   "replacements": ["3G", "3GS", "4", "4S", "5", "5C", "5S", "6", "6S", "7", "8", "X"]

Now, searches for “iPhone 4” or “iPhone 7” will both yield the record.

Try these tutorials

If you want to get started implementing synonyms, we have a tutorial you might find helpful:

© Algolia - Privacy Policy