Configure synonyms in Elasticsearch

Synonyms are words or phrases that have the same or similar meaning. When you configure synonyms in Elasticsearch, a search for one term automatically matches documents that use an equivalent term. For example, you can define synonym rules to match different terms for the same concept, surface results for domain-specific jargon, or handle common misspellings.

This page walks you through defining synonym rules, grouping them into reusable synonym sets, configuring Elasticsearch to apply them during text analysis, and verifying that queries return the expanded results you expect.

To manage synonym sets using the API or Kibana UI, you need the manage_search_synonyms cluster privilege.

To use synonyms in Elasticsearch, follow this workflow:

  1. Create synonym sets and rules: Define which terms are equivalent and how to store your synonym sets.
  2. Configure token filters and analyzers: Set up synonym token filters and add them to your analyzers.
  3. Create an index with your synonym analyzer: Apply your analyzer to an index mapping.
  4. Test your analyzer: Verify your synonym configuration produces the expected tokens.
  5. Search with synonyms: Run a search query and confirm synonym expansion works.

Synonym rules define which terms should be treated as equivalent. Each rule uses one of two mapping types:

  • Explicit mappings use => to specify one-way replacements (for example, i-pod, i pod => ipod).
  • Equivalent mappings use commas to group interchangeable terms (for example, ipod, i-pod, i pod).

For full format details, refer to the synonym graph token filter reference.

You have multiple options for creating synonym sets and rules.

Synonym sets created through the API or the Kibana UI can only be used at search time. For index-time synonyms, use a file-based or inline approach with the synonym token filter.

You can use the synonyms APIs to manage synonym sets. This is the most flexible approach, as it allows you to dynamically define and modify synonym sets. The following example creates a synonym set named my-synonym-set. Later steps on this page use this set.

				PUT _synonyms/my-synonym-set
					{
  "synonyms_set": [
    {
      "id": "laptop-synonyms",
      "synonyms": "laptop, notebook"
    }
  ]
}

Changes to your synonym sets automatically reload the associated analyzers. For more examples, including rule validation and analyzer reloading, refer to Create or update synonym set API examples.

You can create and manage synonym sets and synonym rules using the Kibana user interface.

To create a synonym set using the UI:

  1. Use the global search field to find Synonyms, then select Synonyms / Synonyms from the results.
  2. Select Get started.
  3. Enter a name for your synonym set.
  4. Add your synonym rules in the editor by adding terms to match against:
    • Add Equivalent rules by adding multiple equivalent terms. For example: ipod, i-pod, i pod
    • Add Explicit rules by adding multiple terms that map to a single term. For example: i-pod, i pod => ipod
  5. Select Save to save your rules.

The UI supports the same synonym rule formats as the file-based approach. Changes made through the UI automatically reload the associated analyzers.

You can store your synonym set in a file.

Make sure you upload the synonym set file to all your cluster nodes, in the configuration directory for your Elasticsearch distribution. If you're using Elastic Cloud Hosted, you can upload synonyms files using custom bundles.

An example of a synonym file:

# Blank lines and lines starting with pound are comments.

# Explicit mappings
i-pod, i pod => ipod
sea biscuit, sea biscit => seabiscuit

# Equivalent mappings
ipod, i-pod, i pod
universe, cosmos

For the full synonym file format specification, including expand behavior and rule merging, refer to the synonym token filter reference.

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

When a synonym 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 define synonyms directly in your token filter using the synonyms parameter. This is useful for testing, but not recommended for production.

"synonyms_filter": {
  "type": "synonym_graph",
  "synonyms": ["laptop, notebook", "i-pod, i pod => ipod"]
}
Warning

A large number of inline synonyms increases cluster size unnecessarily and can lead to performance issues. For production workloads, use the REST API or file-based approach instead.

Warning

Synonym sets must exist before you reference them in an index. An index that references a nonexistent synonym set becomes inoperable and must be deleted and re-created, or closed and re-opened.

Once your synonym 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:

  • Synonym graph: Recommended for search analyzers. Correctly handles multi-word synonyms. This filter is designed for search-time use only.
  • Synonym: Required for index-time synonyms. Not recommended if you need to use multi-word synonyms.

Refer to each token filter's reference page for configuration details and instructions on adding it to an analyzer. If your analyzer chain includes a stop token filter, pay attention to ordering. Stop filters placed before or after a synonym filter affect synonym expansion differently.

Large synonym sets can trigger a memory circuit breaker. Refer to the synonym graph token filter reference for thresholds and lenient behavior.

Important

When lenient is false, invalid synonym rules cause errors: analyzer changes fail to apply, and an index with invalid rules cannot be reopened. lenient defaults to the value of updateable. Refer to Synonyms and stop token filters for details.

Synonyms can be applied at search time or index time. Search time is recommended because you can update your synonym sets without reindexing. If token filters are configured with "updateable": true, search analyzers can be reloaded when you make changes.

The following example creates an index with synonyms_analyzer as a search analyzer on the title field.

				PUT /my-index
					{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "search_analyzer": "synonyms_analyzer"
      }
    }
  },
  "settings": {
    "analysis": {
      "analyzer": {
        "synonyms_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "synonyms_filter"]
        }
      },
      "filter": {
        "synonyms_filter": {
          "type": "synonym_graph",
          "synonyms_set": "my-synonym-set",
          "updateable": true
        }
      }
    }
  }
}
  1. For file-based synonym sets, use "synonyms_path": "analysis/synonym-set.txt" instead.
  2. Applies synonyms at search time only, not when indexing documents.
  3. Required when you use synonyms_set: synonym sets can only be loaded into search-time analyzers. It also lets you reload the analyzer when the set changes, without reindexing.

After creating your index, use the analyze API to verify that your synonym configuration produces the expected tokens:

				GET /my-index/_analyze
					{
  "analyzer": "synonyms_analyzer",
  "text": "laptop"
}

The response contains tokens for both laptop and notebook, because my-synonym-set defines them as equivalent terms.

After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. Queries that support synonym expansion include match, query_string, and simple_query_string.

Index a document so the search has something to match:

				POST /my-index/_doc?refresh=true
					{
  "title": "Lightweight notebook for travel"
}

For example, if laptop and notebook are configured as equivalent terms and you search for laptop, Elasticsearch also matches documents containing notebook:

				GET /my-index/_search
					{
  "query": {
    "match": {
      "title": "laptop"
    }
  }
}

The response includes the document, even though its title doesn't contain the word laptop: synonyms_analyzer expanded the query term to notebook at search time.