› › ›

Create or update synonym rule

Creates or updates a synonym rule for a synonym set.

Request

PUT _synonyms/<synonyms_set>/<synonym_rule>

Prerequisites

Requires the manage_search_synonyms cluster privilege.

Path parameters

<synonyms_set>: (Required, string) Synonyms set identifier to update.
<synonym_rule>: (Required, string) Synonym rule identifier to create or update.

Request body

synonyms

(Required, string) The synonym rule definition. This needs to be in Solr format. Some examples are:

"i-pod, i pod ⇒ ipod",
"universe, cosmos"

Examples

The following example updates an existing synonym rule called test-1 for the synonyms set my-synonyms-set:

resp = client.synonyms.put_synonym_rule(
    set_id="my-synonyms-set",
    rule_id="test-1",
    synonyms="hello, hi, howdy",
)
print(resp)

response = client.synonyms.put_synonym_rule(
  set_id: 'my-synonyms-set',
  rule_id: 'test-1',
  body: {
    synonyms: 'hello, hi, howdy'
  }
)
puts response

const response = await client.synonyms.putSynonymRule({
  set_id: "my-synonyms-set",
  rule_id: "test-1",
  synonyms: "hello, hi, howdy",
});
console.log(response);

PUT _synonyms/my-synonyms-set/test-1
{
  "synonyms": "hello, hi, howdy"
}

{
  "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"
        ]
      }
    ]
  }
}

All analyzers using this synonyms set will be reloaded automatically to reflect the new rule.

If any of the synonym rules included is invalid, the API will return an error.

resp = client.synonyms.put_synonym_rule(
    set_id="my-synonyms-set",
    rule_id="test-1",
    synonyms="hello => hi => howdy",
)
print(resp)

const response = await client.synonyms.putSynonymRule({
  set_id: "my-synonyms-set",
  rule_id: "test-1",
  synonyms: "hello => hi => howdy",
});
console.log(response);

PUT _synonyms/my-synonyms-set/test-1
{
  "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
}

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/put-synonym-rule.html