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