Guides / Managing results / Optimize search results / Synonyms

Managing Synonyms from the Dashboard

Synonyms in the dashboard

Go to the Synonyms tab on the Index Configuration section:

Synonyms 1

Adding synonyms

Add synonyms by clicking on the “Add synonyms” button. A small window should appear. You will be asked to choose a type. Depending on the type you select, the other fields on this window will change.

Synonym types

Algolia allows you to specify several types of synonyms.

Regular synonyms

Synonyms 2

Available fields:

  • Synonyms: A comma-separated list of words or expressions that should be considered equivalent.

Recall: Regular synonyms function as follows: Any word in the list, if typed, will find any other word in the list. All words are equivalent.

One-way synonyms

Synonyms 3

Available fields:

  • Search Term: The text used in a query that should be substituted by the Alternatives (“tablet”, in our example).
  • Alternatives: A comma-separated list of alternative words/expressions that should be considered equivalent to the Search Term.

Recall: One-way synonyms function as follows: The search term can find any of the terms in the list, but not vice-versa: The terms in the alternative list will not find the search term, nor will they find each other.

Alternative correction

Synonyms 4

Available fields:

  • Search Term: The text used in the query that should be substituted by the Corrections (“tablet”, in the example).
  • Typo: The number of typos (1 or 2) allowed when the Search Term is matched to one of the Corrections.
  • Corrections: A comma-separated list of alternative words that should be considered equivalent to the Search Term.

Recall: The difference between alternative corrections and the regular and one-way synonyms is that with alternative corrections, you are giving the match a typo count = 1 or 2. The effect of this is to rank alternative corrections lower than other synonym matches (where typo count = 0).

Note that only single-word expressions are allowed for both Search Term and Corrections. Don’t include spaces.


Synonyms 5

Available fields:

  • Placeholder: The token that should be identified in records as a placeholder. It must be enclosed in angle brackets. For example <street>.
  • Replacements: A comma-separated list of expressions that are allowed in place of the placeholder. Any query matching one of the replacements will also match the placeholder.

Recall: Placeholders allow you to place not-yet defined “tokens” that can take any value from a list of defined words.

What does “Forward to replica indices” mean?

Any synonyms that you create on an index can be automatically propagated to its replica indices. This is the default behavior. If you don’t want this default behavior, turn off this option.

Importing synonyms from a file

If you have a lot of synonyms, perhaps sourced by a merchandising team, or pulled from an external dictionary, you probably don’t want to add them one by one.

An easier method is to upload an entire file of synonyms at once. Click on the arrow and then the “Upload” button. This window will appear:

Synonyms 6

Two data formats are supported: JSON and CSV. Note: CSV is limited to regular synonyms (see below).


The file must contain an array of newline-delimited JSON objects.

Each object must include:

  • A unique objectID value that identifies the synonym record. It’s not generated automatically if it’s missing.
  • A type value. Options are synonym, oneWaySynonym, altCorrection1, altCorrection2, and placeholder.
  • All other fields required by the chosen type are described in the earlier sections.

Note: To see how to format every synonym inside the file you can have a look at the different synonym types


A CSV file can only be used to import regular synonyms (type is synonym). The file must contain one set of comma-separated synonyms per line.

For now, CSV import supports only Unix line breaks (\r\n), not yet CR/LF.

Forward to replica indices

Keep this box checked to forward synonyms to all replica indices.

Deleting synonyms

If you want to remove all synonyms from an index, click the “Delete All” button and this window will appear:

Synonyms 7

Confirm the deletion by entering the name of the index. This operation can’t be undone. Use the “Forward to replica indices” checkbox to propagate the deletion to all replica indices.

To delete a specific synonym record, click the Trash can icon in the “Actions” column of the synonyms list.

Synonyms 8

Editing synonyms

Click the edit button in the “Actions” column of the synonyms list to edit synonyms. The window that opens is identical to the synonym creation window described above.

Synonyms 9

Searching synonyms

Finding a specific synonym record can be tedious if you have a lot of them. To address this, the dashboard allows you to search through synonyms and also filter by type.

Did you find this page helpful?