All Products
Search

This Product

    OpenSearch:Dictionary configurations

    Document Center

    OpenSearch:Dictionary configurations

    Last Updated:Jun 26, 2026

    Dictionary configurations let you add custom intervention entries to override how built-in analyzers tokenize text. When a built-in analyzer produces incorrect or unhelpful tokens for your domain-specific terms, add those terms to the appropriate custom dictionary to get the expected tokenization results.

    When to use custom dictionaries

    Add a custom intervention entry when any of the following apply:

    • Compound terms are split incorrectly — the analyzer breaks a multi-word product name or technical term into unrelated tokens. For example, the Chinese analyzer tokenizes "ping-pong ball auction is over" as "ping-pong / ball / auction / over", so searching for "racket" returns no results.

    • Brand names or product codes are fragmented — proprietary names that have no equivalent in standard dictionaries get split at unexpected boundaries.

    • Domain-specific terminology is tokenized using general language rules — IT, e-commerce, gaming, or education terms that require specialized treatment.

    How it works

    Open Search creates two dictionary configuration versions by default:

    • `_offline_adv_v1` — a read-only system version containing eight built-in dictionaries:

      Dictionary
      General-purpose Chinese text analyzer.dict
      Chinese e-commerce content analyzer of the general-purpose edition.dict
      Chinese game content analyzer of the general-purpose edition.dict
      Chinese education content analyzer.dict
      Chinese entertainment content analyzer.dict
      English e-commerce content analyzer of the general-purpose edition.dict
      Chinese IT content analyzer.dict
      Chinese e-commerce content analyzer.dict

    • `_offline_adv_edit` — the editable version where you add your custom intervention entries.

    Each time you publish the editable version, the system creates a new read-only version named _offline_adv_v{n} (where {n} is an integer starting from 2). You can add a version description when publishing to document the purpose of each change.

    Each instance supports only one editable dictionary configuration version at a time.

    Add a custom intervention entry

    After adding entries and publishing the updated version, reindexing is required so that the new tokenization rules apply to your existing indexed documents. The dictionary takes effect for online queries immediately after reindexing completes.

    Prerequisites

    Before you begin, ensure that you have:

    • An Open Search instance with at least one index table

    • Identified which dictionary is used by the index table containing the target field

    Add entries and publish

    1. In the left-side navigation pane of the Instance Details page, choose Configuration Center > Advanced Configurations.

    2. Find the version named _offline_adv_edit and click Modify in the Actions column.

    3. Find the dictionary used by the index table that contains the target field, and click Modify in the Actions column.

    4. Add your intervention entry using one of the following methods:

      • Enter directly: In the panel, type the entry and click Submit.

      • Upload a file: In the panel, upload a dictionary file and enter your custom intervention entry in the field, then click Submit.

      The file must be in .dict or .txt format and cannot exceed 5 MB.

    5. Publish the edited version: The system generates a new read-only version (for example, _offline_adv_v2).

      • Specify a version description.

      • Click Publish in the Actions column.

    Synchronize and reindex

    1. Synchronize the new version to your cluster and trigger a reindexing task. Reindexing is required because the analyzer processes text at index time — existing documents were indexed with the previous tokenization rules and must be reindexed to reflect the updated dictionary.

    2. Monitor the reindexing progress on the Data Source Changes tab of the Change History page in O&M Center.

    After reindexing completes, the updated dictionary configurations take effect for online queries immediately.

    Entry formats

    Each line in a dictionary file represents one intervention entry. All entries must be UTF-8 encoded.

    Equivalent mapping

    Use this format when you want the tokenizer to treat the entry as a single, indivisible token. The tokenizer recognizes any occurrence of the entry and keeps it intact.

    Format: Enter the entry on its own line. No spaces or tab characters are allowed within the entry.

    opensearch
opensearch

    Explicit mapping

    Use this format when you want to define exactly how the entry is split into tokens. The mapping is one-way: the tokenizer recognizes the original entry and replaces it with the specified tokens.

    Format: Enter the original entry, a tab character (\t), and then the target tokens separated by spaces.

    opensearch	open search
opensearch	open search

    Delete a dictionary configuration version

    Versions in the Unused state can be deleted on the Dictionary Configurations tab of the Advanced Configurations page.

    Versions in the In Use state cannot be deleted. To delete an In Use version:

    1. In the left-side navigation pane of the Instance Details page, choose O&M Center > O&M Management.

    2. Click Update Configurations and change the Dictionary Configuration Version parameter to a different version.

    3. Synchronize the change to your cluster and trigger a reindexing task.

    4. After the version state changes to Unused, delete it from the Dictionary Configurations tab.

    Limitations

    • Each instance supports only one editable dictionary configuration version (_offline_adv_edit).

    • Versions in the In Use state are read-only and cannot be deleted.

    • The Advanced Configurations page supports both dictionary configurations and query configurations.