Create or update a synonym set

PUT /_synonyms/{id}

Auth

Synonym sets are limited to a maximum of 100,000 synonym rules per set by default. This limit is configurable using the synonyms.max_synonym_rules cluster setting.

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.

For practical examples of how to create or update a synonyms set, refer to the External documentation.

About synonym API examples

Required authorization

Cluster privileges manage_search_synonyms

Path parameters

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

Query parameters

append boolean · default: false: If true, the provided synonym rules are appended to the existing set, with matching IDs overwriting existing rules. If false, the entire synonyms set is replaced with the new synonym rules definitions.

Request body

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

Responses

application/json

result enum required: The update operation result.; Values: created updated deleted not_found noop
reload_analyzers_details object: Updating a synonyms set can reload the associated analyzers in case refresh is set to true. This information is the analyzers reloading result.

The synonym rules are not valid.

application/json

error object required
status number required

Examples

Request Console 1 / 8 languages

Console Kibana Dev Tools

PUT _synonyms/my-synonyms-set

{
  "synonyms_set": {
  "synonyms" : "hello, hi, howdy"
  }
}

JavaScript Elasticsearch JavaScript Client

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

Python Elasticsearch Python Client

resp = client.synonyms.put_synonym(
    id="my-synonyms-set",
    synonyms_set={
        "synonyms": "hello, hi, howdy"
    },
)

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_synonyms/my-synonyms-set" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "synonyms_set": {
      "synonyms": "hello, hi, howdy"
    }
  }'

Java Elasticsearch Java Client

client.synonyms().putSynonym(p -> p
    .id("my-synonyms-set")
    .synonymsSet(s -> s
        .synonyms("hello, hi, howdy")
    )
);

C# Elasticsearch .NET Client

var response = await client.Synonyms
    .PutSynonymAsync(id: "my-synonyms-set", d1 => d1
        .SynonymsSet(d2 => d2
            .Synonyms("hello, hi, howdy")
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->synonyms()->putSynonym([
    "id" => "my-synonyms-set",
    "body" => [
        "synonyms_set" => [
            "synonyms" => "hello, hi, howdy",
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.synonyms.put_synonym(
  id: "my-synonyms-set",
  body: {
    "synonyms_set": {
      "synonyms": "hello, hi, howdy"
    }
  }
)

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
}