Search with synonyms

Synonyms are words or phrases that have the same or similar meaning. They are an important aspect of search, as they can improve the search experience and increase the scope of search results.

Synonyms allow you to:

Synonyms are grouped together using synonyms sets. You can have as many synonyms sets as you need.

In order to use synonyms sets in Elasticsearch, you need to:

Your synonyms sets need to be stored in Elasticsearch so your analyzers can refer to them. There are three ways to store your synonyms sets:

You can use the synonyms APIs to manage synonyms sets. This is the most flexible approach, as it allows to dynamically define and modify synonyms sets.

Changes in your synonyms sets will automatically reload the associated analyzers.

You can store your synonyms set in a file.

A synonyms set file needs to be uploaded to all your cluster nodes, and be located in the configuration directory for your Elasticsearch distribution. If you’re using Elasticsearch Service, you can upload synonyms files using custom bundles.

An example synonyms file:

# Blank lines and lines starting with pound are comments.

# Explicit mappings match any token sequence on the left hand side of "=>"
# and replace with all alternatives on the right hand side.
# These types of mappings ignore the expand parameter in the schema.
# Examples:
i-pod, i pod => ipod
sea biscuit, sea biscit => seabiscuit

# Equivalent synonyms may be separated with commas and give
# no explicit mapping.  In this case the mapping behavior will
# be taken from the expand parameter in the token filter configuration.
# This allows the same synonym file to be used in different synonym handling strategies.
# Examples:
ipod, i-pod, i pod
foozball , foosball
universe , cosmos
lol, laughing out loud

# If expand==true in the synonym token filter configuration,
# "ipod, i-pod, i pod" is equivalent to the explicit mapping:
ipod, i-pod, i pod => ipod, i-pod, i pod
# If expand==false, "ipod, i-pod, i pod" is equivalent
# to the explicit mapping:
ipod, i-pod, i pod => ipod

# Multiple synonym mapping entries are merged.
foo => foo bar
foo => baz
# is equivalent to
foo => foo bar, baz

To update an existing synonyms set, upload new files to your cluster. Synonyms set files must be kept in sync on every cluster node.

When a synonyms set is updated, search analyzers that use it need to be refreshed using the reload search analyzers API

This manual syncing and reloading makes this approach less flexible than using the synonyms API.

You can test your synonyms by adding them directly inline in your token filter definition.

Once your synonyms sets are created, you can start configuring your token filters and analyzers to use them.

Elasticsearch uses synonyms as part of the analysis process. You can use two types of token filter to include synonyms:

Check each synonym token filter documentation for configuration details and instructions on adding it to an analyzer.

You can test an analyzer configuration without modifying your index settings. Use the analyze API to test your analyzer chain:

response = client.indices.analyze(
  body: {
    tokenizer: 'standard',
    filter: [
      'lowercase',
      {
        type: 'synonym_graph',
        synonyms: [
          'pc => personal computer',
          'computer, pc, laptop'
        ]
      }
    ],
    text: 'Check how PC synonyms work'
  }
)
puts response

GET /_analyze
{
  "tokenizer": "standard",
  "filter" : [
    "lowercase",
    {
      "type": "synonym_graph",
      "synonyms": ["pc => personal computer", "computer, pc, laptop"]
    }
  ],
  "text" : "Check how PC synonyms work"
}

Analyzers can be applied at index time or search time.

You need to decide when to apply your synonyms:

Synonyms sets created using the synonyms API can only be used at search time.

You can specify the analyzer that contains your synonyms set as a search time analyzer or as an index time analyzer.

The following example adds my_analyzer as a search analyzer to the title field in an index mapping:

  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "search_analyzer": "my_analyzer",
        "updateable": true
      }
    }
  }