Create or update synonyms setedit
This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.
Creates or updates a synonyms set.
Requestedit
PUT _synonyms/<synonyms_set>
Prerequisitesedit
Requires the manage_search_synonyms cluster privilege.
Path parametersedit
-
<synonyms_set> - (Required, string) Synonyms set identifier to create. This identifier will be used by other Synonyms APIs to manage the synonyms set.
Request bodyedit
-
synonyms_set - (Required, array of synonym rules objects) The synonym rules definitions for the synonyms set.
Properties of synonyms_set objects
-
id - (Optional, string) The identifier associated to the synonym rule, that can be used to manage individual synonym rules via synonym rules APIs. In case a synonym rule id is not specified, an identifier will be created automatically by Elasticsearch.
-
synonyms -
(Required, string) The synonym rule. This needs to be in Solr format. Some examples are:
- "i-pod, i pod ⇒ ipod",
- "universe, cosmos"
Examplesedit
The following example creates a new synonyms set called my-synonyms-set:
PUT _synonyms/my-synonyms-set
{
"synonyms_set": [
{
"id": "test-1",
"synonyms": "hello, hi"
},
{
"synonyms": "bye, goodbye"
},
{
"id": "test-2",
"synonyms": "test => check"
}
]
}
If any of the synonym rules included is not valid, the API will return an error.
PUT _synonyms/my-synonyms-set
{
"synonyms_set": [
{
"synonyms": "hello => hi => howdy"
}
]
}
{
"error": {
"root_cause": [
{
"type": "action_request_validation_exception",
"reason": "Validation Failed: 1: More than one explicit mapping specified in the same synonyms rule: [hello => hi => howdy];",
"stack_trace": ...
}
],
"type": "action_request_validation_exception",
"reason": "Validation Failed: 1: More than one explicit mapping specified in the same synonyms rule: [hello => hi => howdy];",
"stack_trace": ...
},
"status": 400
}
Analyzer reloadingedit
When an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices. This would be equivalent to invoking Reload search analyzers API for all indices that use the synonyms set.
For example, creating an index with a synonyms set and updating it:
PUT _synonyms/my-synonyms-set
{
"synonyms_set": [
{
"id": "test-1",
"synonyms": "hello, hi"
}
]
}
PUT /test-index
{
"settings": {
"analysis": {
"filter": {
"synonyms_filter": {
"type": "synonym_graph",
"synonyms_set": "my-synonyms-set",
"updateable": true
}
},
"analyzer": {
"my_index_analyzer": {
"type": "custom",
"tokenizer": "standard",
"filter": ["lowercase"]
},
"my_search_analyzer": {
"type": "custom",
"tokenizer": "standard",
"filter": ["lowercase", "synonyms_filter"]
}
}
}
},
"mappings": {
"properties": {
"title": {
"type": "text",
"analyzer": "my_index_analyzer",
"search_analyzer": "my_search_analyzer"
}
}
}
}
PUT _synonyms/my-synonyms-set
{
"synonyms_set": [
{
"id": "test-1",
"synonyms": "hello, hi, howdy"
}
]
}
The reloading result is included as part of the response:
{
"result": "updated",
"reload_analyzers_details": {
"_shards": {
"total": 2,
"successful": 1,
"failed": 0
},
"reload_details": [
{
"index": "test-index",
"reloaded_analyzers": [
"my_search_analyzer"
],
"reloaded_node_ids": [
"1wYFZzq8Sxeu_Jvt9mlbkg"
]
}
]
}
}