Icon relevance white


Last updated 12 December 2017

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, simply including an attribute with an array of relevant keywords is a better alternative.

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.

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 “jackets” will also return “parkas.”

"jacket"  "parka"

Similarly, searching for “parkas” will also return “jackets”:

"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

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",

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.

For example, consider this record:

  "address": "589 Howard <Street>"

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

   "objectID": "a-unique-identifier",
   "type": "placeholder",
   "placeholder": "<Street>",
   "replacements": ["street", "st"]

Now, searches for “Howard St” or “Howard Street” will both yield the record.

What’s Next

Continue building your Algolia knowledge with these concepts:

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

© Algolia - Privacy Policy