[[using-synonyms]] === Using Synonyms

Synonyms can replace existing tokens or((("synonyms", "using"))) be added to the token stream by using the((("synonym token filter"))) http://bit.ly/1DInEGD[`synonym` token filter]:

[source,json]

PUT /my_index { "settings": { "analysis": { "filter": { "my_synonym_filter": { "type": "synonym", <1> "synonyms": [ <2> "british,english", "queen,monarch" ] } }, "analyzer": { "my_synonyms": { "tokenizer": "standard", "filter": [ "lowercase", "my_synonym_filter" <3> ] } } } }

}

<1> First, we define a token filter of type synonym.

<2> We discuss synonym formats in <>.

<3> Then we create a custom analyzer that uses the my_synonym_filter.

[TIP]

Synonyms can be specified inline with the synonyms parameter, or in a synonyms file that must((("synonyms", "specifying inline or in a separate file"))) be present on every node in the cluster. The path to the synonyms file should be specified with the synonyms_path parameter, and should be either absolute or relative to the Elasticsearch config directory. See <> for techniques that can be used to refresh the synonyms list.

==================================================

Testing our analyzer with the analyze API shows the following:

[source,json]

GET /my_index/_analyze?analyzer=my_synonyms

Elizabeth is the English queen

[source,text]

Pos 1: (elizabeth) Pos 2: (is) Pos 3: (the) Pos 4: (british,english) <1>

Pos 5: (queen,monarch) <1>

<1> All synonyms occupy the same position as the original term.

A document like this will match queries for any of the following: English queen, British queen, English monarch, or British monarch. Even a phrase query will work, because the position of each term has been preserved.

[TIP]

Using the same synonym token filter at both index time and search time is redundant.((("synonym token filter", "using at index time versus search time"))) If, at index time, we replace English with the two terms english and british, then at search time we need to search for only one of those terms. Alternatively, if we don't use synonyms at index time, then at search time, we would need to convert a query for English into a query for english OR british.

Whether to do synonym expansion at search or index time can be a difficult choice. We will explore the options more in <>.

======================================