All Products
Search
Document Center

:Configuration rules

Last Updated:Mar 26, 2026

Configure a synonym filter to expand search queries with related terms. Alibaba Cloud Elasticsearch supports two synonym formats: Solr and WordNet.

How it works

Define a synonym filter in the filter section of your index settings, then reference it in an analyzer:

PUT /test_index
{
  "settings": {
    "index": {
      "analysis": {
        "analyzer": {
          "synonym": {
            "tokenizer": "whitespace",
            "filter": ["synonym"]
          }
        },
        "filter": {
          "synonym": {
            "type": "synonym",
            "synonyms_path": "analysis/synonym.txt",
            "tokenizer": "whitespace"
          }
        }
      }
    }
  }
}

This configuration creates a synonym analyzer that uses the whitespace tokenizer and applies the synonym filter. The filter loads synonym rules from analysis/synonym.txt. For all supported parameters, see Synonym Token Filter in the open-source Elasticsearch documentation.

Parameters

Parameter Required Type Description
type Yes String Set to synonym.
synonyms Either synonyms or synonyms_path Array Synonym rules defined inline in the filter.
synonyms_path Either synonyms or synonyms_path String Path to a synonym rules file, relative to the Elasticsearch config directory.
format No String Synonym format. Valid values: solr, wordnet.
expand No Boolean Whether to expand equivalent synonym rules.
tokenizer No String Tokenizer used to parse synonym rules.

Choose a storage method

Method When to use
synonyms_path (file) Large synonym sets, production environments
synonyms (inline) Testing and small synonym sets
Note We recommend that you use synonyms_path to define large synonym sets in the file.

Solr synonyms

The Solr format supports two types of synonym rules.

Equivalent synonyms

Words separated by commas are treated as equivalent. The expand parameter controls how rules are applied:

ipod, i-pod, i pod
foozball, foosball
universe, cosmos
lol, laughing out loud

`expand` behavior:

If expand is true, ipod, i-pod, i pod is equivalent to:

ipod, i-pod, i pod => ipod, i-pod, i pod

If expand is false, ipod, i-pod, i pod is equivalent to:

ipod, i-pod, i pod => ipod

Explicit mappings

Use => to map one or more tokens to specific alternatives. These rules always ignore the expand parameter.

i-pod, i pod => ipod
sea biscuit, sea biscit => seabiscuit

Multiple entries for the same source token are merged:

foo => foo bar
foo => baz
# Equivalent to:
foo => foo bar, baz

Inline Solr synonyms

To define Solr synonyms directly in the filter, use synonyms instead of synonyms_path:

PUT /test_index
{
  "settings": {
    "index": {
      "analysis": {
        "filter": {
          "synonym": {
            "type": "synonym",
            "synonyms": [
              "i-pod, i pod => ipod",
              "begin, start"
            ]
          }
        }
      }
    }
  }
}

WordNet synonyms

The WordNet format uses "format": "wordnet" in the filter. You can define WordNet synonyms using either synonyms or synonyms_path.

Example using synonyms:

PUT /test_index
{
  "settings": {
    "index": {
      "analysis": {
        "filter": {
          "synonym": {
            "type": "synonym",
            "format": "wordnet",
            "synonyms": [
              "s(100000001,1,'abstain',v,1,0).",
              "s(100000001,2,'refrain',v,1,0).",
              "s(100000001,3,'desist',v,1,0)."
            ]
          }
        }
      }
    }
  }
}

To load WordNet synonyms from a file, use synonyms_path instead of synonyms.