Elasticsearch:Upload a synonym dictionary file

Precautions

• Before you upload a synonym dictionary file to your Elasticsearch cluster, you must make sure that the cluster is in a normal state. After you upload a synonym dictionary file, the system restarts the cluster. During the restart, the system updates the synonym dictionaries on all the nodes in the cluster based on the synonym dictionary file. The time required for the updated dictionaries to take effect depends on the specifications, data volume, and load of the cluster. We recommend that you upload a synonym dictionary file during off-peak hours.

• In most cases, if the indexes of your cluster have replica shards and the load of your cluster is normal, your cluster can still provide services during a cluster configuration change. The following items indicate that the load of a cluster is normal: The CPU utilization of each node in the cluster is about 60%, the heap memory usage of each node in the cluster is about 50%, and the value of NodeLoad_1m for each node is less than the number of vCPUs for the node.

• If the indexes of your cluster do not have replica shards, the load of the cluster is excessively high, and large amounts of data are written to or queried in your cluster, access to the cluster may time out during a cluster configuration change. We recommend that you configure an access retry mechanism for your client before you perform a cluster configuration change. This reduces the impact on your business.

• 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, perform one of the following operations:

  • Reindex the data in these indexes after the synonym dictionary of your Elasticsearch cluster is updated. During the reindex operation, services are not interrupted.

  • Reopen these indexes. During the reopen operation, services are interrupted. To reopen an index, go to the Console tab of the Dev Tools page in the Kibana console and run the following command:

    ---index_name specifies the name of an index.
    POST <index_name>/_close
    POST <index_name>/_open

• A synonym dictionary file must be a TXT file encoded in UTF-8. Each line can contain only one synonym expression. Synonym expressions support Solr rules and WordNet rules. The following code provides an example:

  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 dictionary file or make other changes.

• To prevent impacts on your business, we recommend that you do not change the name of the synonym dictionary file in use. Otherwise, the indexes that use the synonym dictionary file may become abnormal.

Procedure

1. Log on to the Alibaba Cloud Elasticsearch console.

2. In the left-side navigation pane, click Elasticsearch Clusters.

3. Navigate to the desired cluster.

   1. In the top navigation bar, select the resource group to which the cluster belongs and the region where the cluster resides.

   2. On the Elasticsearch Clusters page, find the cluster and click its ID.

4. In the left-side navigation pane of the page that appears, choose Configuration and Management > Cluster Configuration.

5. In the Basic Configuration section, click Upload on the right side of Synonym Dictionary Configuration.

6. In the Synonym Dictionary Configuration panel, click Configure in the lower-left corner.

7. Select a method that you want to use to upload a synonym dictionary file.

   Note

   A synonym dictionary file is a TXT file generated based on the rules described in Configuration rules.

   • Upload: If you select this method, click Upload and select the synonym dictionary file that you want to upload from your on-premises machine.

   • Add OSS File: If you select this method, configure the Bucket Name and File Name parameters, and click Add.

     Make sure that the bucket you specify resides in the same region as your Elasticsearch cluster and the file to be uploaded is a TXT file.

8. Click Save.

What to do next

After the state of the Elasticsearch cluster becomes Normal, 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 the setting and mapping parameters and specify "synonyms_path": "analysis/your_dict_name.txt" for the setting parameter. For more information, see Use synonyms and Using Synonyms in open source Elasticsearch documentation.

References

API operation for updating the synonym dictionary of a cluster: UpdateSynonymsDicts