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, you can search new indexes by using the updated synonym dictionary.

Background information

Note the following points when you upload a synonym dictionary file:
  • After you upload a synonym dictionary file to your Elasticsearch cluster, the cluster is restarted. During the restart process, the system updates the synonym dictionary file to all nodes in the cluster. The time that is required for the updated dictionary to take effect is based on the number of nodes.
  • Assume that the index-aliyun index is created based on the aliyun.txt synonym file. If you have uploaded a new synonym dictionary file to overwrite the existing dictionary file, the existing index cannot automatically load the new dictionary file. You must recreate the indexes after you update the synonym dictionary. Otherwise, the updated synonym dictionary only takes effect on new indexes.
  • A synonym dictionary file must be a TXT file encoded by using UTF-8. Each line can contain only one synonym expression.
    ipod, i-pod, i pod => ipod, i-pod, i pod
    foo => foo bar


  1. Log on to the Alibaba Cloud Elasticsearch console.
  2. In the top navigation bar, select the region where your Alibaba Cloud Elasticsearch cluster resides.
  3. Find the target cluster and click its ID.
  4. In the left-side navigation pane of the cluster details page, click Cluster Configuration.
  5. On the Cluster Configuration page, click Synonym Dictionary Configuration on the right side of Word Splitting.
  6. In the Synonym Dictionary Configuration pane, select the mode that you want 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 mode, click Upload and select the local synonym dictionary file that you want to upload.
    • Add OSS File: If you select this mode, specify Bucket Name and File Name and click Add.

      Make sure that the specified bucket is in the same region as the Elasticsearch cluster and the specified file is a TXT file.

  7. Click Save.

What to do next

After the status of the Elasticsearch cluster becomes Active, log on to the Kibana console to 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 the open-source Elasticsearch documentation and Configure synonyms.