Create or update a synonym set

PUT /_synonyms/{id}

Auth

Synonyms sets are limited to a maximum of 10,000 synonym rules per set. If you need to manage more synonym rules, you can create multiple synonym sets.

When an existing synonyms set is updated, the search analyzers that use the synonyms set are reloaded automatically for all indices. This is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.

Required privileges

Cluster privileges manage_search_synonyms

Path parameters

id string required: The ID of the synonyms set to be created or updated.

Request body

synonyms_set union oneOf required: The synonym rules definitions for the synonyms set.; object or object[]

Responses

application/json

result enum required: Values: created updated deleted not_found noop
reload_analyzers_details object required

The synonym rules are not valid.

application/json

View as Markdown

Examples

Request Console 1 / 6 languages

Console Kibana Dev Tools

PUT _synonyms/my-synonyms-set

JavaScript Elasticsearch JavaScript Client

const response = await client.synonyms.putSynonym({
  id: "my-synonyms-set",
});

Python Elasticsearch Python Client

resp = client.synonyms.put_synonym(
    id="my-synonyms-set",
)

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_synonyms/my-synonyms-set" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"

PHP Elasticsearch PHP Client

$resp = $client->synonyms()->putSynonym([
    "id" => "my-synonyms-set",
]);

Ruby Elasticsearch Ruby Client

response = client.synonyms.put_synonym(
  id: "my-synonyms-set"
)

Response

{
  "result": "created",
  "reload_analyzers_details": {
    "reload_details": [
      {
        "index": "string",
        "reloaded_analyzers": [
          "string"
        ],
        "reloaded_node_ids": [
          "string"
        ]
      }
    ],
    "_shards": {
      "failed": 0,
      "successful": 0,
      "total": 0,
      "failures": [
        {
          "index": "string",
          "node": "string",
          "reason": {
            "type": "string",
            "stack_trace": "string"
          },
          "shard": 0,
          "status": "string",
          "primary": false
        }
      ],
      "skipped": 0
    }
  }
}

Generated from the API spec

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