IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Synonyms APIs Get synonyms set »
Elastic Docs ›Elasticsearch Guide [8.11] ›REST APIs ›Synonyms APIs

Create or update synonyms set

edit

Create or update synonyms set

edit

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.

Synonyms sets are limited to a maximum of 10,000 synonym rules per set. Synonym sets with more than 10,000 synonym rules will provide inconsistent search results. If you need to manage more synonym rules, you can create multiple synonyms sets.

Request

edit

PUT _synonyms/<synonyms_set>

Prerequisites

edit

Requires the manage_search_synonyms cluster privilege.

Path parameters

edit
<synonyms_set>
(Required, string) Synonyms set identifier to create. This identifier will be used by other Synonyms APIs to manage the synonyms set.

Request body

edit
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"

Examples

edit

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 reloading

edit

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"
        ]
      }
    ]
  }
}
« Synonyms APIs Get synonyms set »