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?

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 using 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", "&"]
   }

You can also add the separators to the index using your dashboard:

Configuration > Special Characters > Separators characters to index

Conclusion

If your synonym involving special characters isn’t working, check whether the character is a separator. By adding it to separatorsToIndex, you can ensure it is indexed properly and that your synonym functions as expected.