# 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.

```json
{
  "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, c` makes the words equivalent. With `expand` (the default `true`) each one maps to all
  the others; with `expand: false` each one maps to the first.
- `a, b => c, d` replaces `a` or `b` with `c` and `d`, 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](synonyms-and-rules.md), 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](synonyms-and-rules.md), 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.
