This topic describes how to upload a custom synonym dictionary file to your Alibaba Cloud Elasticsearch cluster. After you upload a custom file and the synonym dictionary of your Elasticsearch cluster is updated, new indexes are searched by using the updated synonym dictionary.


When you upload a synonym dictionary file, take note of the following items:
  • After you upload a synonym dictionary file to your Elasticsearch cluster, the system restarts the cluster. During the restart, the system updates the synonym dictionary file to all nodes in the cluster. The time required for the updated dictionary to take effect depends on the number of nodes.
  • A new dictionary file does not take effect for existing indexes because these indexes cannot automatically load the file. For example, the index-aliyun index is created based on the aliyun.txt synonym file, and you modify the file and upload the modified file. The uploaded file does not take effect for the index. If you also want a new dictionary file to take effect on existing indexes, reindex the data in these indexes after the synonym dictionary of your cluster is updated.
  • A synonym dictionary file must be a TXT file encoded in UTF-8. Each line can contain only one synonym expression.
    ipod, i-pod, i pod => ipod, i-pod, i pod
    foo => foo bar
  • The stopword list of your Elasticsearch cluster cannot contain the keywords specified in the synonym dictionary file of the cluster. Otherwise, an error is reported in the logs of the cluster when you upload a new synonym file or make other changes.


  1. Log on to the Alibaba Cloud Elasticsearch console.
  2. In the top navigation bar, select the region where your cluster resides.
  3. In the left-side navigation pane, click Elasticsearch Clusters. On the page that appears, find the target cluster and click its ID in the Cluster ID/Name column.
  4. In the left-side navigation pane of the page that appears, click Cluster Configuration.
  5. In the Basic Configuration section, click Upload next to Synonym Dictionary Configuration.
  6. In the Synonym Dictionary Configuration pane, select the method that you want to use to upload a synonym dictionary file. Then, upload the file that is generated based on the rules in Configuration rules.
    Configure synonyms
    • Upload: If you select this method, click Upload and select the local synonym dictionary file that you want to upload.
    • Add OSS File: If you select this method, specify Bucket Name and File Name, and click Add.

      Make sure that the specified bucket resides in the same region as your Elasticsearch cluster and the file you want to upload is a TXT file.

  7. Click Save.

What to do next

After the state of the Elasticsearch cluster becomes Active, log on to the Kibana console of the cluster. Then, create indexes, verify synonyms, and upload test data to perform a search test. When you create an index, you must configure setting and mapping and configure "synonyms_path": "analysis/your_dict_name.txt" in setting. For more information, see Using Synonyms in open source Elasticsearch documentation and Configure synonyms.