Upload a synonym dictionary file - Elasticsearch - Alibaba Cloud Documentation Center

Synonym dictionaries enhance search relevance by allowing queries to match related terms. This topic describes how to upload a synonym dictionary file to your Alibaba Cloud Elasticsearch cluster and outlines important considerations and best practices for doing so.

Usage notes and best practices

Review these critical points before uploading or managing synonym dictionary files.

Cluster state and restart impact

Cluster health: Before uploading, ensure your Elasticsearch cluster is in a healthy state.
Automatic restart: Uploading a new synonym dictionary file triggers an automatic rolling restart of your cluster. During this restart, the system updates synonym dictionaries on all nodes.
Restart duration: The time required for the restart and dictionary updates to take effect depends on your cluster's specifications, data volume, and current load.
Downtime risk:
- Low impact (Recommended): If your indices have replica shards and the cluster load is normal (CPU ~60%, heap ~50%, NodeLoad_1m < vCPU count), your cluster can typically continue to provide services during the rolling restart.
- High impact (Avoid): If your indices lack replica shards, or if the cluster is under excessively high load with heavy write/query operations, access to the cluster may time out during the restart. Implement an access retry mechanism in your client applications to minimize business impact.
Timing: We strongly recommend uploading synonym dictionary files during off-peak hours due to the cluster restart and potential resource consumption.

Impact on existing indices

New dictionary files and existing indices: A newly uploaded or updated synonym dictionary file does not automatically take effect for existing indices. This is because existing indices do not automatically reload the analyzer configurations.
To apply to existing indices: If you need the new dictionary to affect existing indices, choose one of the following methods:
- Reindex data: Reindex the data in these indices after the synonym dictionary is updated. This operation generally does not interrupt services.
- Reopen indices: Close and then reopen the affected indices. This operation will interrupt services for those indices.
```
---index_name specifies the name of an index.
POST <index_name>/_close
POST <index_name>/_open
```

Synonym dictionary file format and rules

File type: A synonym dictionary file must be a plain TXT file encoded in UTF-8.
Content: Each line in the file should contain only one synonym expression.
Rule types: Synonym expressions support both Solr rules and WordNet rules.
Example formats:
```
ipod, i-pod, i pod
computer, pc, laptop
```

Conflicts and naming conventions

Stopword conflicts: The stopword list of your Elasticsearch cluster must not contain any keywords specified in your synonym dictionary file. Conflicts will result in errors in the cluster logs when you upload the dictionary or make other changes.
File name changes: Avoid changing the name of a synonym dictionary file that is currently in use. Doing so can cause abnormalities in indices that rely on that dictionary.

Procedure

Console

Log on to the Alibaba Cloud Elasticsearch console.
In the left navigation menu, choose Elasticsearch Clusters.
Navigate to the target 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.
In the left navigation menu, choose Configuration and Management > Cluster Configuration.
In the Basic Configuration section, click Upload next to Synonym Dictionary Configuration.
In the Synonym Dictionary Configuration panel, click Configure.
Select a method.
- Upload: Click Upload and select the synonym dictionary file from your computer.
- Add OSS File: Configure the Bucket Name and File Name parameters, and click Add.
  Note
  Ensure the specified OSS bucket resides in the same region as your Elasticsearch cluster, and the file is a TXT file.
Click Save.
You can download an uploaded dictionary file by clicking the download icon next to its entry in the console.

API

See UpdateSynonymsDicts.

Next steps: Applying synonyms and verification

After uploading the synonym dictionary file and allowing the cluster to restart, configure your index analyzers to use the new dictionary.

Log on to the Kibana console of the cluster.
Create an index (or reindex/reopen an existing one) that uses the synonym analyzer. When defining your index settings and mappings, specify the synonyms_path parameter to point to your uploaded dictionary file (e.g., "synonyms_path": "analysis/your_dict_name.txt").
For detailed instructions, refer to: Use synonyms and Using Synonyms (Elasticsearch documentation).
Upload test data and perform search tests to verify that the synonyms are working as expected.