Retrieval Query Synonyms and Expansion Rules

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

Synonym and query-expansion rules are retrieval configuration, not prompt magic, so agents should inspect analyzer and synonym metadata before blaming the embedding model.

## Core Explanation

RAG systems often miss relevant documents because the query uses different vocabulary from the indexed text. Synonym maps can connect terms such as "SLA" and "service-level agreement" or product names and aliases. They can also create false positives when expansion is too broad.

Agents debugging recall should preserve the raw query, normalized query, analyzer name, synonym map version, equivalent or explicit mapping rule, index-time versus query-time expansion mode, expanded tokens, and top results before and after expansion. This evidence separates a vocabulary mismatch from a ranking, filtering, or chunking problem.

Synonym changes should be evaluated like search relevance changes. A rule that fixes one query can degrade another query family, especially in domains where acronyms have multiple meanings.

## Source-Mapped Facts

- Elasticsearch documentation describes a synonym token filter that can handle synonym rules during analysis. ([source](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-tokenfilter.html))
- Azure AI Search documentation describes synonym maps that expand or rewrite search queries. ([source](https://learn.microsoft.com/en-us/azure/search/search-synonyms))
- OpenSearch documentation describes a synonym token filter for matching tokens with configured synonyms. ([source](https://docs.opensearch.org/latest/analyzers/token-filters/synonym/))

## Further Reading

- [Elasticsearch Synonym Token Filter](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-synonym-tokenfilter.html)
- [Azure AI Search Synonyms](https://learn.microsoft.com/en-us/azure/search/search-synonyms)
- [OpenSearch Synonym Token Filter](https://docs.opensearch.org/latest/analyzers/token-filters/synonym/)