Synonym graph token filter

The synonym_graph token filter allows to easily handle synonyms, including multi-word synonyms correctly during the analysis process.

In order to properly handle multi-word synonyms this token filter creates a graph token stream during processing. For more information on this topic and its various complexities, please read the Lucene’s TokenStreams are actually graphs blog post.

This token filter is designed to be used as part of a search analyzer only. If you want to apply synonyms during indexing please use the standard synonym token filter.

Synonyms are configured using a configuration file. Here is an example:

  1. PUT /test_index
  2. {
  3.   "settings": {
  4.     "index": {
  5.       "analysis": {
  6.         "analyzer": {
  7.           "search_synonyms": {
  8.             "tokenizer": "whitespace",
  9.             "filter": [ "graph_synonyms" ]
  10.           }
  11.         },
  12.         "filter": {
  13.           "graph_synonyms": {
  14.             "type": "synonym_graph",
  15.             "synonyms_path": "analysis/synonym.txt"
  16.           }
  17.         }
  18.       }
  19.     }
  20.   }
  21. }

The above configures a search_synonyms filter, with a path of analysis/synonym.txt (relative to the config location). The search_synonyms analyzer is then configured with the filter.

Additional settings are:

  • expand (defaults to true).
  • lenient (defaults to false). If true ignores exceptions while parsing the synonym configuration. It is important to note that only those synonym rules which cannot get parsed are ignored. For instance consider the following request:
  1. PUT /test_index
  2. {
  3.   "settings": {
  4.     "index": {
  5.       "analysis": {
  6.         "analyzer": {
  7.           "synonym": {
  8.             "tokenizer": "standard",
  9.             "filter": [ "my_stop", "synonym_graph" ]
  10.           }
  11.         },
  12.         "filter": {
  13.           "my_stop": {
  14.             "type": "stop",
  15.             "stopwords": [ "bar" ]
  16.           },
  17.           "synonym_graph": {
  18.             "type": "synonym_graph",
  19.             "lenient": true,
  20.             "synonyms": [ "foo, bar => baz" ]
  21.           }
  22.         }
  23.       }
  24.     }
  25.   }
  26. }

With the above request the word bar gets skipped but a mapping foo => baz is still added. However, if the mapping being added was foo, baz => bar nothing would get added to the synonym list. This is because the target word for the mapping is itself eliminated because it was a stop word. Similarly, if the mapping was “bar, foo, baz” and expand was set to false no mapping would get added as when expand=false the target mapping is the first word. However, if expand=true then the mappings added would be equivalent to foo, baz => foo, baz i.e, all mappings other than the stop word.

tokenizer and ignore_case are deprecated

The tokenizer parameter controls the tokenizers that will be used to tokenize the synonym, this parameter is for backwards compatibility for indices that created before 6.0.. The ignore_case parameter works with tokenizer parameter only.

Two synonym formats are supported: Solr, WordNet.

Solr synonyms

The following is a sample format of the file:

  1. # Blank lines and lines starting with pound are comments.
  3. # Explicit mappings match any token sequence on the LHS of "=>"
  4. # and replace with all alternatives on the RHS.  These types of mappings
  5. # ignore the expand parameter in the schema.
  6. # Examples:
  7. i-pod, i pod => ipod,
  8. sea biscuit, sea biscit => seabiscuit
  10. # Equivalent synonyms may be separated with commas and give
  11. # no explicit mapping.  In this case the mapping behavior will
  12. # be taken from the expand parameter in the schema.  This allows
  13. # the same synonym file to be used in different synonym handling strategies.
  14. # Examples:
  15. ipod, i-pod, i pod
  16. foozball , foosball
  17. universe , cosmos
  18. lol, laughing out loud
  20. # If expand==true, "ipod, i-pod, i pod" is equivalent
  21. # to the explicit mapping:
  22. ipod, i-pod, i pod => ipod, i-pod, i pod
  23. # If expand==false, "ipod, i-pod, i pod" is equivalent
  24. # to the explicit mapping:
  25. ipod, i-pod, i pod => ipod
  27. # Multiple synonym mapping entries are merged.
  28. foo => foo bar
  29. foo => baz
  30. # is equivalent to
  31. foo => foo bar, baz

You can also define synonyms for the filter directly in the configuration file (note use of synonyms instead of synonyms_path):

  1. PUT /test_index
  2. {
  3.   "settings": {
  4.     "index": {
  5.       "analysis": {
  6.         "filter": {
  7.           "synonym": {
  8.             "type": "synonym_graph",
  9.             "synonyms": [
  10.               "lol, laughing out loud",
  11.               "universe, cosmos"
  12.             ]
  13.           }
  14.         }
  15.       }
  16.     }
  17.   }
  18. }

However, it is recommended to define large synonyms set in a file using synonyms_path, because specifying them inline increases cluster size unnecessarily.

WordNet synonyms

Synonyms based on WordNet format can be declared using format:

  1. PUT /test_index
  2. {
  3.   "settings": {
  4.     "index": {
  5.       "analysis": {
  6.         "filter": {
  7.           "synonym": {
  8.             "type": "synonym_graph",
  9.             "format": "wordnet",
  10.             "synonyms": [
  11.               "s(100000001,1,'abstain',v,1,0).",
  12.               "s(100000001,2,'refrain',v,1,0).",
  13.               "s(100000001,3,'desist',v,1,0)."
  14.             ]
  15.           }
  16.         }
  17.       }
  18.     }
  19.   }
  20. }

Using synonyms_path to define WordNet synonyms in a file is supported as well.

Parsing synonym files

Elasticsearch will use the token filters preceding the synonym filter in a tokenizer chain to parse the entries in a synonym file. So, for example, if a synonym filter is placed after a stemmer, then the stemmer will also be applied to the synonym entries. Because entries in the synonym map cannot have stacked positions, some token filters may cause issues here. Token filters that produce multiple versions of a token may choose which version of the token to emit when parsing synonyms, e.g. asciifolding will only produce the folded version of the token. Others, e.g. multiplexer, word_delimiter_graph or ngram will throw an error.

If you need to build analyzers that include both multi-token filters and synonym filters, consider using the multiplexer filter, with the multi-token filters in one branch and the synonym filter in the other.

The synonym rules should not contain words that are removed by a filter that appears after in the chain (a stop filter for instance). Removing a term from a synonym rule breaks the matching at query time.