Synonyms
Synonyms let you define term equivalences so users find the right results regardless of the exact words they use. When a user searches for "sneakers", results for "shoes" also appear.
How Synonyms Work
Skirre expands search queries using your synonym definitions. When a query contains a term that has synonyms defined, the search engine looks for matches on all equivalent terms.
Synonyms are defined as a map where each key is a term and the value is an array of equivalent terms. The relationship is one-directional, so searching for "shoes" will also search "sneakers" and "kicks", but searching for "sneakers" will not automatically search "shoes" unless you also add a reverse mapping.
Configuring Synonyms
Set synonyms through the Settings API:
await idx.updateSettings({ synonyms: { 'shoes': ['sneakers', 'kicks', 'footwear'], 'sneakers': ['shoes', 'kicks', 'footwear'], 'tv': ['television', 'monitor', 'screen'], 'television': ['tv', 'monitor', 'screen'], }, });
curl -X PUT https://search.example.com/v1/indices/products/settings \ -H "Authorization: Bearer sk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "synonyms": { "shoes": ["sneakers", "kicks", "footwear"], "sneakers": ["shoes", "kicks", "footwear"] } }'
"synonyms": {}.Auto-Synonym Discovery
Configuring synonyms manually requires knowing what terms your customers use interchangeably. Skirre can help: when semantic search is enabled, a nightly background job analyzes your indexed documents, extracts unique terms, and uses embedding similarity to find pairs that are semantically equivalent but not yet linked.
These appear as auto-synonym suggestions in the Analytics API. You review each pair and apply or dismiss — applying creates bidirectional synonym mappings automatically.
A similar feature, zero-result suggestions, identifies queries that return no results and suggests alternative queries with results. Applying creates a one-way synonym from the failing query to the working one. See Zero-Result Suggestions.
Best Practices
- Make synonyms bidirectional. If "shoes" maps to "sneakers", also map "sneakers" to "shoes". Otherwise, searching one term won't find results indexed under the other.
- Keep synonym groups small. Large groups (10+ terms) can reduce search precision. Focus on the most common equivalences.
- Use analytics to find gaps. Check no-result queries to discover terms users search for that could benefit from synonym mappings.
- Avoid overlapping groups. If "shoes" maps to both "sneakers" and "boots", make sure that's intentional since sneakers and boots are different products.
- Use lowercase. Synonym matching is case-insensitive, but defining synonyms in lowercase keeps the configuration clean.
Common Patterns
Abbreviations
{
"tv": ["television"],
"television": ["tv"],
"ac": ["air conditioner"],
"air conditioner": ["ac"]
}Regional variations
{
"pants": ["trousers"],
"trousers": ["pants"],
"sweater": ["jumper", "pullover"],
"jumper": ["sweater", "pullover"]
}Brand-specific terms
{
"thermos": ["vacuum flask", "insulated bottle"],
"vacuum flask": ["thermos", "insulated bottle"]
}Limitations
- Synonyms are stored per-index. There is no global synonym list shared across indices.
- Synonym expansion happens at query time, not at indexing time. Changes take effect immediately without re-indexing.
- Multi-word synonym values work but are treated as phrase matches.