---
title: Configure synonyms in Elasticsearch
description: Learn how to define synonym sets, configure synonym token filters and analyzers, and apply synonyms at search time or index time in Elasticsearch.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7945/solutions/search/full-text/search-with-synonyms
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available
---

# 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.






## Prerequisites

To manage synonym sets using the API or Kibana UI, you need the `manage_search_synonyms` [cluster privilege](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/security-privileges).

## Synonyms workflow overview

To use synonyms in Elasticsearch, follow this workflow:
1. [**Create synonym sets and rules**](#synonyms-store-synonyms): Define which terms are equivalent and how to store your synonym sets.
2. [**Configure token filters and analyzers**](#synonyms-synonym-token-filters): Set up synonym token filters and add them to your analyzers.
3. [**Create an index with your synonym analyzer**](#synonyms-apply-synonyms): Apply your analyzer to an index mapping.
4. [**Test your analyzer**](#synonyms-test-analyzer): Verify your synonym configuration produces the expected tokens.
5. [**Search with synonyms**](#synonyms-search-example): Run a search query and confirm synonym expansion works.


## Synonym rule formats

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](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-graph-tokenfilter) reference.

## Step 1: Create synonym sets and rules

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](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-tokenfilter).
<tab-set>
  <tab-item title="REST API">
    You can use the [synonyms APIs](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-synonyms) 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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7945/solutions/search/full-text/create-update-synonyms-api-example) page.Changes to your synonym sets automatically reload the associated analyzers.
  </tab-item>

  <tab-item title="Kibana UI">
    <applies-to>
      - Serverless Elasticsearch projects: Generally available
      - Elastic Stack: Generally available since 9.1
    </applies-to>
    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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7945/explore-analyze/find-and-organize/find-apps-and-objects) 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.
  </tab-item>

  <tab-item title="File-based">
    <applies-to>
      - Elastic Cloud Serverless: Unavailable
    </applies-to>
    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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7945/deploy-manage/deploy/elastic-cloud/upload-custom-plugins-bundles).An example of a synonym file:
    ```text
    # 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](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-tokenfilter) 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](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-reload-search-analyzers).This manual syncing and reloading makes this approach less flexible than using the synonyms API.
  </tab-item>

  <tab-item title="Inline">
    You can define synonyms directly in your token filter using the `synonyms` parameter. This is useful for testing, but not recommended for production.
    ```json
    "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>
  </tab-item>
</tab-set>

<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.
</warning>


## Step 2: Configure synonyms token filters and analyzers

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](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7945/manage-data/data-store/text-analysis). You can use two types of [token filter](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/token-filter-reference) to include synonyms:
- [Synonym graph](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-graph-tokenfilter): Recommended for search analyzers. Correctly handles multi-word synonyms. This filter is designed for search-time use only.
- [Synonym](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-tokenfilter): 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](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-graph-tokenfilter#synonym-graph-tokenizer-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](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-graph-tokenfilter#synonym-graph-tokenizer-circuit-breaker). Refer to the [synonym graph token filter](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-graph-tokenfilter#synonym-graph-tokenizer-circuit-breaker) 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](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-graph-tokenfilter) reference for details.
</important>


## Step 3: Create an index with your synonym analyzer

Synonyms can be applied at [search time or index time](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7945/manage-data/data-store/text-analysis/index-search-analysis). Search time is recommended because you can update your synonym sets without [reindexing](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-reindex). If token filters are configured with `"updateable": true`, search analyzers can be [reloaded](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-reload-search-analyzers) when you make changes.
The following example creates an index with `synonyms_analyzer` as a search analyzer on the `title` field.
```json

{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "search_analyzer": "synonyms_analyzer" <2>
      }
    }
  },
  "settings": {
    "analysis": {
      "analyzer": {
        "synonyms_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "synonyms_filter"]
        }
      },
      "filter": {
        "synonyms_filter": {
          "type": "synonym_graph",
          "synonyms_set": "my-synonym-set", <1>
          "updateable": true <3>
        }
      }
    }
  }
}
```


## Step 4: Test your analyzer

After creating your index, use the [analyze API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-analyze) to verify that your synonym configuration produces the expected tokens:
```json

{
  "analyzer": "synonyms_analyzer",
  "text": "laptop"
}
```

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

## Step 5: Search with synonyms

After you configure synonyms for a field, queries against that field automatically expand to include synonym terms. Queries that support synonym expansion include [match](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/query-dsl/query-dsl-match-query), [query_string](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/query-dsl/query-dsl-query-string-query), and [simple_query_string](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/query-dsl/query-dsl-simple-query-string-query).
For example, if `laptop` and `notebook` are configured as equivalent terms and you search for `laptop`, Elasticsearch also matches documents containing `notebook`:
```json

{
  "query": {
    "match": {
      "title": "laptop"
    }
  }
}
```

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

## Next steps

- [Create or update synonym set API examples](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7945/solutions/search/full-text/create-update-synonyms-api-example): Practical examples of managing synonym sets through the API.
- [Synonym graph token filter](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-graph-tokenfilter): Full reference for the recommended synonym token filter.
- [Synonym token filter](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/text-analysis/analysis-synonym-tokenfilter): Reference for the standard synonym token filter, required for index-time synonyms.
- [Text analysis](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7945/manage-data/data-store/text-analysis): Learn more about analyzers, tokenizers, and token filters.