Create or update synonyms setedit
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:
response = client.synonyms.put_synonym(
id: 'my-synonyms-set',
body: {
synonyms_set: [
{
id: 'test-1',
synonyms: 'hello, hi'
},
{
synonyms: 'bye, goodbye'
},
{
id: 'test-2',
synonyms: 'test => check'
}
]
}
)
puts response
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:
response = client.synonyms.put_synonym(
id: 'my-synonyms-set',
body: {
synonyms_set: [
{
id: 'test-1',
synonyms: 'hello, hi'
}
]
}
)
puts response
response = client.indices.create(
index: 'test-index',
body: {
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'
}
}
}
}
)
puts response
response = client.synonyms.put_synonym(
id: 'my-synonyms-set',
body: {
synonyms_set: [
{
id: 'test-1',
synonyms: 'hello, hi, howdy'
}
]
}
)
puts response
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"
]
}
]
}
}