Why Are My Synonyms with Special Characters Not Working?

When setting up synonyms in Algolia, you may expect terms like and and & to be interchangeable, but sometimes they don’t work as expected. A common reason for this is that special characters, including &, are considered separators by default and are ignored during indexing.

Why does this happen?

If your synonym involving special characters isn’t working, check whether the character is a separator.

Algolia treats certain characters as separators, meaning they are removed from the index before search processing. These include symbols like:

! # ( ) [ ] { } * + - _ 一 , : ; < > ? @ / \ ^ | % & ~ £ ¥ $ § € " “ ” † ‡`

Because these characters are ignored, a synonym between and and & won’t function correctly unless Algolia recognises & as a searchable character.

How to fix it

To ensure your synonym works with special characters, you need to explicitly include them in the index by using either the separatorToIndex parameter:

1. Add & to separatorsToIndex in your index settings:

   {
     "separatorsToIndex": "&"
   }

2. Once & is indexed, you can then create a two-way synonym between and and &:

   {
     "objectID": "synonym_and",
     "type": "synonym",
     "synonyms": ["and", "&"]
   }

Or you can also add the separators to the index using your dashboard:

Configuration > Special Characters > Separators characters to index

By adding it to separatorsToIndex, you can ensure it is indexed properly and that your synonym functions as expected.

For a full list of common synonym issues, troubleshooting topics and best practices, see our summary article here.