elasticsearch/docs/reference/synonyms/apis/delete-synonyms-set.asciidoc

[[delete-synonyms-set]]
=== Delete synonyms set

beta::[]

++++
<titleabbrev>Delete synonyms set</titleabbrev>
++++

Deletes a synonyms set.

[[delete-synonyms-set-request]]
==== {api-request-title}

`DELETE _synonyms/<synonyms_set>`

[[delete-synonyms-set-prereqs]]
==== {api-prereq-title}

* Requires the `manage_search_synonyms` cluster privilege.
* You can only delete a synonyms set that is not in use by any index analyzer. See <<delete-synonym-set-analyzer-requirements>> for more information.

[[delete-synonyms-set-path-params]]
==== {api-path-parms-title}

`<synonyms_set>`::
(Required, string)
Synonyms set identifier to delete.


[[delete-synonyms-set-response-codes]]
==== {api-response-codes-title}

`400`::
The `synonyms_set` identifier was not provided, or the synonyms set can't be deleted because it does not meet the <<delete-synonym-set-analyzer-requirements,specified requirements>>.

`404` (Missing resources)::
No synonyms set with the identifier `synonyms_set` was found.

[[delete-synonyms-set-example]]
==== {api-examples-title}

The following example deletes a synonyms set called `my-synonyms-set`:


////
[source,console]
----
PUT _synonyms/my-synonyms-set
{
  "synonyms_set": [
    {
      "id": "test-1",
      "synonyms": "hello, hi"
    }
  ]
}
----
// TESTSETUP
////

[source,console]
----
DELETE _synonyms/my-synonyms-set
----

[discrete]
[[delete-synonym-set-analyzer-requirements]]
==== Delete synonyms set analyzer requirements

synonyms sets can be used in  <<analysis-synonym-graph-tokenfilter,synonym graph token filters>> and <<analysis-synonym-tokenfilter,synonym token filters>>.
These synonym filters can be used as part of <<search-analyzer, search analyzers>>.

Analyzers need to be loaded when an index is restored (such as when a node starts, or the index becomes open).
Even if the analyzer is not used on any field mapping, it still needs to be loaded on the index recovery phase.

If any analyzers cannot be loaded, the index becomes unavailable and the cluster status becomes <<red-yellow-cluster-status,red or yellow>> as index shards are not available.

To prevent that, synonyms sets that are used in analyzers can't be deleted.
A delete request in this case will return a `400` response code with the following error message:

////
[source,console]
----
PUT /index-1
{
  "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 /index-2
{
  "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"
      }
    }
  }
}

DELETE _synonyms/my-synonyms-set
----
// TEST[catch:bad_request]
////

[source,console-result]
----
{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "Synonyms set [my-synonyms-set] cannot be deleted as it is used in the following indices: index-1, index-2",
        "stack_trace": ...
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "Synonyms set [my-synonyms-set] cannot be deleted as it is used in the following indices: index-1, index-2",
    "stack_trace": ...
  },
  "status": 400
}
----
// TESTRESPONSE[s/"stack_trace": \.\.\./"stack_trace": $body.$_path/]

To remove a synonyms set, you must first remove all indices that contain analyzers using it.
You can migrate an index by creating a new index that does not contain the token filter with the synonyms set, and use the <<docs-reindex>> in order to copy over the index data.
Once finished, you can delete the index.

When the synonyms set is not used in analyzers, you will be able to delete it.