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:

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.

View this page as Markdown

Cookie settings

Optional tracking stays off until you choose it. Your choice applies to this browser for 180 days. Read the details.

Essential storage keeps you signed in, protects forms, and remembers this choice. It is always available.