Loading

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. For examples of how to create or update a synonym set with APIs, refer to the Create or update synonym set API examples page.

Changes to your synonym sets automatically reload the associated analyzers.

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

Too many 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 details on thresholds and lenient behavior.

Important

Invalid synonym rules can cause errors when applying analyzer changes and can prevent an index from being reopened. Refer to the synonym graph token filter reference 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. Allows the analyzer to be reloaded when synonym sets change, 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"
}

If your synonym set includes laptop, notebook as equivalent terms, the response contains tokens for both laptop and notebook.

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.

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"
    }
  }
}

This query matches documents where the title field contains laptop or notebook, because the synonym rule treats them as equivalent.