Create or update synonyms set

Create or update synonyms set

New API reference

For the most up-to-date API details, refer to Synonyms APIs.

Creates or updates a synonyms set.

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 synonyms sets.

Request

PUT _synonyms/<synonyms_set>

Prerequisites

Requires the manage_search_synonyms cluster privilege.

Path parameters

<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

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

The following example creates a new synonyms set called my-synonyms-set:

  1. resp = client.synonyms.put_synonym(
  2.     id="my-synonyms-set",
  3.     synonyms_set=[
  4.         {
  5.             "id": "test-1",
  6.             "synonyms": "hello, hi"
  7.         },
  8.         {
  9.             "synonyms": "bye, goodbye"
  10.         },
  11.         {
  12.             "id": "test-2",
  13.             "synonyms": "test => check"
  14.         }
  15.     ],
  16. )
  17. print(resp)
  1. response = client.synonyms.put_synonym(
  2.   id: 'my-synonyms-set',
  3.   body: {
  4.     synonyms_set: [
  5.       {
  6.         id: 'test-1',
  7.         synonyms: 'hello, hi'
  8.       },
  9.       {
  10.         synonyms: 'bye, goodbye'
  11.       },
  12.       {
  13.         id: 'test-2',
  14.         synonyms: 'test => check'
  15.       }
  16.     ]
  17.   }
  18. )
  19. puts response
  1. const response = await client.synonyms.putSynonym({
  2.   id: "my-synonyms-set",
  3.   synonyms_set: [
  4.     {
  5.       id: "test-1",
  6.       synonyms: "hello, hi",
  7.     },
  8.     {
  9.       synonyms: "bye, goodbye",
  10.     },
  11.     {
  12.       id: "test-2",
  13.       synonyms: "test => check",
  14.     },
  15.   ],
  16. });
  17. console.log(response);
  1. PUT _synonyms/my-synonyms-set
  2. {
  3.   "synonyms_set": [
  4.     {
  5.       "id": "test-1",
  6.       "synonyms": "hello, hi"
  7.     },
  8.     {
  9.       "synonyms": "bye, goodbye"
  10.     },
  11.     {
  12.       "id": "test-2",
  13.       "synonyms": "test => check"
  14.     }
  15.   ]
  16. }

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

  1. resp = client.synonyms.put_synonym(
  2.     id="my-synonyms-set",
  3.     synonyms_set=[
  4.         {
  5.             "synonyms": "hello => hi => howdy"
  6.         }
  7.     ],
  8. )
  9. print(resp)
  1. const response = await client.synonyms.putSynonym({
  2.   id: "my-synonyms-set",
  3.   synonyms_set: [
  4.     {
  5.       synonyms: "hello => hi => howdy",
  6.     },
  7.   ],
  8. });
  9. console.log(response);
  1. PUT _synonyms/my-synonyms-set
  2. {
  3.   "synonyms_set": [
  4.     {
  5.       "synonyms": "hello => hi => howdy"
  6.     }
  7.   ]
  8. }
  1. {
  2.   "error": {
  3.     "root_cause": [
  4.       {
  5.         "type": "action_request_validation_exception",
  6.         "reason": "Validation Failed: 1: More than one explicit mapping specified in the same synonyms rule: [hello => hi => howdy];",
  7.         "stack_trace": ...
  8.       }
  9.     ],
  10.     "type": "action_request_validation_exception",
  11.     "reason": "Validation Failed: 1: More than one explicit mapping specified in the same synonyms rule: [hello => hi => howdy];",
  12.     "stack_trace": ...
  13.   },
  14.   "status": 400
  15. }

Analyzer reloading

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:

  1. resp = client.synonyms.put_synonym(
  2.     id="my-synonyms-set",
  3.     synonyms_set=[
  4.         {
  5.             "id": "test-1",
  6.             "synonyms": "hello, hi"
  7.         }
  8.     ],
  9. )
  10. print(resp)
  12. resp1 = client.indices.create(
  13.     index="test-index",
  14.     settings={
  15.         "analysis": {
  16.             "filter": {
  17.                 "synonyms_filter": {
  18.                     "type": "synonym_graph",
  19.                     "synonyms_set": "my-synonyms-set",
  20.                     "updateable": True
  21.                 }
  22.             },
  23.             "analyzer": {
  24.                 "my_index_analyzer": {
  25.                     "type": "custom",
  26.                     "tokenizer": "standard",
  27.                     "filter": [
  28.                         "lowercase"
  29.                     ]
  30.                 },
  31.                 "my_search_analyzer": {
  32.                     "type": "custom",
  33.                     "tokenizer": "standard",
  34.                     "filter": [
  35.                         "lowercase",
  36.                         "synonyms_filter"
  37.                     ]
  38.                 }
  39.             }
  40.         }
  41.     },
  42.     mappings={
  43.         "properties": {
  44.             "title": {
  45.                 "type": "text",
  46.                 "analyzer": "my_index_analyzer",
  47.                 "search_analyzer": "my_search_analyzer"
  48.             }
  49.         }
  50.     },
  51. )
  52. print(resp1)
  54. resp2 = client.synonyms.put_synonym(
  55.     id="my-synonyms-set",
  56.     synonyms_set=[
  57.         {
  58.             "id": "test-1",
  59.             "synonyms": "hello, hi, howdy"
  60.         }
  61.     ],
  62. )
  63. print(resp2)
  1. response = client.synonyms.put_synonym(
  2.   id: 'my-synonyms-set',
  3.   body: {
  4.     synonyms_set: [
  5.       {
  6.         id: 'test-1',
  7.         synonyms: 'hello, hi'
  8.       }
  9.     ]
  10.   }
  11. )
  12. puts response
  14. response = client.indices.create(
  15.   index: 'test-index',
  16.   body: {
  17.     settings: {
  18.       analysis: {
  19.         filter: {
  20.           synonyms_filter: {
  21.             type: 'synonym_graph',
  22.             synonyms_set: 'my-synonyms-set',
  23.             updateable: true
  24.           }
  25.         },
  26.         analyzer: {
  27.           my_index_analyzer: {
  28.             type: 'custom',
  29.             tokenizer: 'standard',
  30.             filter: [
  31.               'lowercase'
  32.             ]
  33.           },
  34.           my_search_analyzer: {
  35.             type: 'custom',
  36.             tokenizer: 'standard',
  37.             filter: [
  38.               'lowercase',
  39.               'synonyms_filter'
  40.             ]
  41.           }
  42.         }
  43.       }
  44.     },
  45.     mappings: {
  46.       properties: {
  47.         title: {
  48.           type: 'text',
  49.           analyzer: 'my_index_analyzer',
  50.           search_analyzer: 'my_search_analyzer'
  51.         }
  52.       }
  53.     }
  54.   }
  55. )
  56. puts response
  58. response = client.synonyms.put_synonym(
  59.   id: 'my-synonyms-set',
  60.   body: {
  61.     synonyms_set: [
  62.       {
  63.         id: 'test-1',
  64.         synonyms: 'hello, hi, howdy'
  65.       }
  66.     ]
  67.   }
  68. )
  69. puts response
  1. const response = await client.synonyms.putSynonym({
  2.   id: "my-synonyms-set",
  3.   synonyms_set: [
  4.     {
  5.       id: "test-1",
  6.       synonyms: "hello, hi",
  7.     },
  8.   ],
  9. });
  10. console.log(response);
  12. const response1 = await client.indices.create({
  13.   index: "test-index",
  14.   settings: {
  15.     analysis: {
  16.       filter: {
  17.         synonyms_filter: {
  18.           type: "synonym_graph",
  19.           synonyms_set: "my-synonyms-set",
  20.           updateable: true,
  21.         },
  22.       },
  23.       analyzer: {
  24.         my_index_analyzer: {
  25.           type: "custom",
  26.           tokenizer: "standard",
  27.           filter: ["lowercase"],
  28.         },
  29.         my_search_analyzer: {
  30.           type: "custom",
  31.           tokenizer: "standard",
  32.           filter: ["lowercase", "synonyms_filter"],
  33.         },
  34.       },
  35.     },
  36.   },
  37.   mappings: {
  38.     properties: {
  39.       title: {
  40.         type: "text",
  41.         analyzer: "my_index_analyzer",
  42.         search_analyzer: "my_search_analyzer",
  43.       },
  44.     },
  45.   },
  46. });
  47. console.log(response1);
  49. const response2 = await client.synonyms.putSynonym({
  50.   id: "my-synonyms-set",
  51.   synonyms_set: [
  52.     {
  53.       id: "test-1",
  54.       synonyms: "hello, hi, howdy",
  55.     },
  56.   ],
  57. });
  58. console.log(response2);
  1. PUT _synonyms/my-synonyms-set
  2. {
  3.     "synonyms_set": [
  4.         {
  5.             "id": "test-1",
  6.             "synonyms": "hello, hi"
  7.         }
  8.     ]
  9. }
  11. PUT /test-index
  12. {
  13.   "settings": {
  14.     "analysis": {
  15.       "filter": {
  16.         "synonyms_filter": {
  17.           "type": "synonym_graph",
  18.           "synonyms_set": "my-synonyms-set",
  19.           "updateable": true
  20.         }
  21.       },
  22.       "analyzer": {
  23.         "my_index_analyzer": {
  24.           "type": "custom",
  25.           "tokenizer": "standard",
  26.           "filter": ["lowercase"]
  27.         },
  28.         "my_search_analyzer": {
  29.           "type": "custom",
  30.           "tokenizer": "standard",
  31.           "filter": ["lowercase", "synonyms_filter"]
  32.         }
  33.       }
  34.     }
  35.   },
  36.   "mappings": {
  37.     "properties": {
  38.       "title": {
  39.         "type": "text",
  40.         "analyzer": "my_index_analyzer",
  41.         "search_analyzer": "my_search_analyzer"
  42.       }
  43.     }
  44.   }
  45. }
  47. PUT _synonyms/my-synonyms-set
  48. {
  49.     "synonyms_set": [
  50.         {
  51.             "id": "test-1",
  52.             "synonyms": "hello, hi, howdy"
  53.         }
  54.     ]
  55. }

The reloading result is included as part of the response:

  1. {
  2.   "result": "updated",
  3.   "reload_analyzers_details": {
  4.     "_shards": {
  5.       "total": 2,
  6.       "successful": 1,
  7.       "failed": 0
  8.     },
  9.     "reload_details": [
  10.       {
  11.         "index": "test-index",
  12.         "reloaded_analyzers": [
  13.           "my_search_analyzer"
  14.         ],
  15.         "reloaded_node_ids": [
  16.           "1wYFZzq8Sxeu_Jvt9mlbkg"
  17.         ]
  18.       }
  19.     ]
  20.   }
  21. }