If a synonym you’ve configured isn’t triggering a Rule as expected, it may be due to a built-in performance limitation in how Algolia evaluates synonyms in Rule conditions.
Matching Rules with Synonyms
Algolia allows Rules to match not only the exact words in a query, but also their synonyms - if the synonym handling option is enabled in the Rule's configuration. This can help expand the effectiveness of Rule conditions beyond exact matches.
However, for performance reasons, only the first 10 synonyms for each query are considered during rule evaluation.
Example Scenario
Suppose you’ve defined 15 synonyms for the word "bottle". If a Rule has a condition that looks for the word "bottle", only the first 10 synonyms will be evaluated against it. The remaining 5 will be ignored when checking if the Rule should apply.
This also applies across multiple words in the query. For example:
Query:
"glass bottle""glass"has 5 synonyms"bottle"has 15 synonyms
In this case, Algolia will use the first 5 synonyms of "glass" and the first 5 synonyms of "bottle", for a total of 10 synonyms, to evaluate Rule matching.
Recommendation
If a synonym isn’t matching your Rule condition, check:
The order of synonyms defined for the term
Whether the total number of evaluated synonyms exceeds 10
If the Rule is properly configured to match synonyms (e.g., in the Visual or Manual Rule Editor)
Reordering or reducing your synonym list can help ensure the most important ones are prioritized for Rule matching.
For a full list of common synonym issues, troubleshooting topics and best practices, see our summary article here.