For AI agents: this page is also available as Markdown at /docs/synonym-filters.md. Every docs page is: add .md to its URL. llms.txt lists them all.
Synonym filters
A synonym filter in a field's analyzer makes tv and television the same word for that field. The filter runs when documents are written and when queries are analyzed, so it works in every query language and through the Elasticsearch, OpenSearch and Solr compatible APIs.
{
"type": "text",
"analyzer": {
"tokenizer": "unicode_word",
"filters": ["lowercase", {"name": "synonym_graph", "params": {
"synonyms": [
"tv, television",
"i-pod, i pod => ipod",
"wi fi, wifi, wireless network"
]
}}]
}
}
Rules are in the Solr format, as in Elasticsearch:
a, b, cmakes the words equivalent. Withexpand(the defaulttrue) each one maps to all the others; withexpand: falseeach one maps to the first.a, b => c, dreplacesaorbwithcandd, never the other way round.- A line starting with
#is a comment, and a backslash escapes,or=>. - A rule can have several words on a side (
wireless network).
Rules go through the filters before the synonym filter, so with lowercase first, Wi Fi in a rule matches WI fi in a document. A rule side that the chain removes entirely, such as a stop word, is an error; with lenient: true that rule is skipped.
| Param | Default | Meaning |
|---|---|---|
synonyms | Required. The rules, one per entry. | |
expand | true | Map equivalent words to all the others, or only to the first. |
lenient | false | Skip rules the chain cannot analyze instead of failing. |
#synonym or synonym_graph
synonym_graph places a multi-word alternative as its own path, which is correct for phrase queries on the query side. The index keeps only each word's start position, so at index time a graph's side paths are not kept as paths; synonym lays a multi-word output over the words that follow, as Elasticsearch's synonym filter does. Use synonym when your rules have multi-word alternatives, and synonym_graph when every alternative is one word or for analyzers you name at query time.
#Index-time filters or collection synonyms
WarpSearch also keeps synonyms per collection, applied by the text query language when it rewrites a search. Choose by how you change them and where you search:
| Synonym filter in the analyzer | Collection synonyms | |
|---|---|---|
| Applies to | Every query language and compatible API, on the fields with the filter | Searches in the text language, on every field |
| Changing a rule | Needs a new field or collection and a reindex | Takes effect at once |
| Matching | On the analyzed words of the field (after stemming, folding, ...) | On normalized query words |
| Index size | Grows with the expansions | Unchanged |
| Managed in | The schema | The console, or PUT /v1/collections/{c}/synonyms |
A synonym list that changes often, such as a merchandising list, fits the collection synonyms. A fixed vocabulary of a domain (abbreviations, product families, spelling variants) fits a filter.
#Through the compatible APIs
Elasticsearch and OpenSearch synonym and synonym_graph filters in settings.analysis keep their synonyms, expand and lenient settings. synonyms_path, synonyms_set and the WordNet format are refused: list the rules inline. flatten_graph is dropped with a warning. Where a filter applies depends on how a field uses its analyzer, because WarpSearch analyzes queries with the field's own analyzer and has no separate search analyzer:
| The synonym filter is in | Becomes |
|---|---|
The field's analyzer (with or without the same search_analyzer) | A synonym filter in the field's analysis, as on this page. updateable: true is accepted with a warning, since changing the rules needs a reindex. |
Only the field's search_analyzer, Elasticsearch's usual setup for synonyms | The collection synonyms, stored when the index is created and applied to searches in the text query language, with a warning. They change without a reindex, so updateable: true fits. |
| Both | The analyzer's filters in the field's analysis, and the search_analyzer's other filters as collection synonyms, with one warning that they differ. |
The rest of a search_analyzer is not applied, with a warning.
Solr's synonym filter factories read their rules from a file, so they are dropped with a warning. Import the file into the collection synonyms instead: Relevance > Synonyms in the console reads Solr and Elasticsearch synonyms.txt files.