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:

text
await idx.updateSettings({
  synonyms: {
    'shoes': ['sneakers', 'kicks', 'footwear'],
    'sneakers': ['shoes', 'kicks', 'footwear'],
    'tv': ['television', 'monitor', 'screen'],
    'television': ['tv', 'monitor', 'screen'],
  },
});
text
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"]
    }
  }'
Merge behavior
Settings updates merge with existing values. To remove all synonyms, set "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

text
{
  "tv": ["television"],
  "television": ["tv"],
  "ac": ["air conditioner"],
  "air conditioner": ["ac"]
}

Regional variations

text
{
  "pants": ["trousers"],
  "trousers": ["pants"],
  "sweater": ["jumper", "pullover"],
  "jumper": ["sweater", "pullover"]
}

Brand-specific terms

text
{
  "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.