Dynamic Field-Level Dictionary Updates in Easysearch IK: A Practical Guide

0. Introduction

IK analyzer field‑level dictionaries support only additions; modifications or deletions require a full index rebuild, causing high operational cost.

The IK reload API enables dynamic reloading of dictionary files without rebuilding the index.

1. Dictionary update challenges

Typical scenarios include short‑video platforms needing to treat trending terms such as “多巴胺穿搭” as whole words, e‑commerce systems updating brand vocabularies, and social media adding new slang.

Traditional IK loads dictionaries once at index creation; updating requires a full index rebuild.

Root cause: the static loading mechanism reads dictionaries into memory only during index creation, which works for static use cases but fails for dynamic business needs.

2. IK reload API design

The API adopts a full‑reload strategy: an API call triggers the analyzer to reread dictionary files from storage and rebuild the in‑memory dictionary structure.

It supports both full reload and targeted dictionary reload modes, providing flexibility for different scenarios.

Effect is limited to documents analyzed after the call; already indexed documents remain unchanged, preserving historical data stability.

3. Practical walk‑through

3.1 Add a new dictionary to the analysis_ik index

Upload the custom dictionary file to the analysis_ik index.

3.2 Create index and verify

Index creation fails before adding the dictionary and succeeds after the addition.

PUT my-index-000001
{
  "settings": {
    "number_of_shards": 3,
    "analysis": {
      "analyzer": {
        "my_custom_analyzer": {
          "type": "custom",
          "tokenizer": "my_tokenizer"
        }
      },
      "tokenizer": {
        "my_tokenizer": {
          "type": "ik_smart",
          "custom_dict_enable": true,
          "load_default_dicts": false,
          "lowcase_enable": true,
          "dict_key": "test_dic"
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "test_ik": {
        "type": "text",
        "analyzer": "my_custom_analyzer"
      }
    }
  }
}

Configuration disables default dictionaries ( load_default_dicts: false) and uses only the custom dictionary test_dic, making the effect of updates clearer.

3.3 Verify tokenization before adding words

GET my-index-000001/_analyze
{
  "analyzer": "my_custom_analyzer",
  "text": "显眼包，多巴胺穿搭"
}

Result shows the terms are split according to the default dictionary.

3.4 Add words and verify again

POST .analysis_ik/_doc
{
  "dict_key": "test_dic",
  "dict_type": "main_dicts",
  "dict_content": "多巴胺穿搭 显眼包"
}

New entries are automatically loaded each minute; deletions or updates require an explicit reload.

POST _ik/_reload
{
  "dict_key": "test_dic"
}

After reload, re‑analyze the same text:

POST my-index-000001/_analyze
{
  "analyzer": "my_custom_analyzer",
  "text": "显眼包，多巴胺穿搭"
}

Result shows the two terms are now treated as whole words.

3.5 Precise reload of a specific dictionary

When multiple dictionaries serve different tenants, the API can reload only the targeted dictionary:

POST _ik/_reload
{
  "dict_key": "test_dic"
}

Result shows the reload process.

Alternatively, specify the dictionary index name for multi‑tenant control:

POST _ik/_reload
{
  "dict_index": "custom_ik_index"
}

3.6 Delete a word and observe the effect

After removing a term from the custom dictionary, execute a reload to apply the change:

POST _ik/_reload
{}

4. Production considerations

Reload only affects documents indexed after the call; historical data may require update_by_query or full reindexing.

Built‑in dictionaries cannot be modified; they remain stable, so custom dictionary planning must account for their presence.

In a cluster, reload runs on all nodes to keep dictionary state consistent, which may require a maintenance window during low‑traffic periods.

5. Summary

Using the IK reload API resolves the inability to dynamically update field‑level dictionaries, enabling rapid incorporation of trending terms such as “OOTD穿搭”. While limitations remain for historical data, the feature markedly increases system flexibility and maintainability.