Using synonyms file in Elastic Cloud


In order to use synonyms in Elasticsearch, we can use a .txt file with a list of our synonyms and add the path to this file in our index definition. See below as an example:

PUT /test_index
  "settings": {
    "index": {
      "analysis": {
        "analyzer": {
          "synonym": {
            "tokenizer": "whitespace",
            "filter": [ "synonym" ]
        "filter": {
          "synonym": {
            "type": "synonym",
            "synonyms_path": "analysis/synonym.txt"

As per the documentation, the process to update this file when using Elastic Cloud is as follows:

  1. Create the extension where we will store a zipped synonyms file. See here
curl -XPOST \
 -H "Authorization: ApiKey $EC_API_KEY" \
 -H 'content-type:application/json' \ \
   "name" : "synonyms-v1",
   "description" : "The best synonyms ever",
   "extension_type" : "bundle",
   "version" : "7.*"
  1. Send a zipped synonyms file to the extension
curl -XPUT \
-H "Authorization: ApiKey $EC_API_KEY" \
"$extension_id" \
-T /tmp/
  1. Add the new extension and update the deployment (plan change), either via api or through the elastic cloud console. See here. We would like to do this via api.

By following the process outlined above, we managed to successfully add a synonyms file to our deployment, but each time, one of our nodes (we have 2 data nodes and a tiebreaker) stops during the process. The error received is of "unknown" type.

{ "failure_type": "ClusterFailure:InstancesAreNotStopped", "InstanceId(ElasticsearchId(xxxx),NodeName(tiebreaker-xxxx))": "FailedToStop(Allocation [xxxx] failed with unknown error)" }

We had to ask technical support to restart the nodes.

Afterwards, now that the extension containing the synonyms file had already been added to the deployment, we updated the file and performed a rolling reset (instead of the deployment plan upgrade call mentioned in step 3. above, see here) with the command below :

POST /api/v1/deployments/{deployment_id}/elasticsearch/{ref_id}/_restart

The data in our data nodes begin to transfer to the new instances, but the step Calling Elasticsearch node shutdown API has been frozen for 24 hours.

Has anyone worked with synonyms in Elastic Cloud? Is this really the only solution to use synonyms in elastic cloud? Restarting/updating full deployments has proven to be a risky procedure for us. We want to use synonyms on an important production environment and can't risk such issues.

Kind regards,

This topic was automatically closed 28 days after the last reply. New replies are no longer allowed.