When the built-in analyzers don't produce the tokenization results your application requires, create a custom analyzer. A custom analyzer combines a built-in analyzer with intervention entries. Intervention entries override how specific terms are segmented during indexing and query processing.
How it works
A custom analyzer consists of two components:
-
A built-in analyzer — the base tokenization logic (for example, the general Chinese analyzer)
-
Intervention entries — key-value pairs that override how specific terms are segmented
Manually added intervention entries take priority over the entries from the specified built-in analyzer. When you assign a custom analyzer to an index field, OpenSearch applies it during both indexing and query processing.
Secondary analysis
Each intervention entry has a Secondary Analysis toggle that controls what happens after the entry matches:
-
Enabled — OpenSearch re-segments the terms produced by the original custom analyzer
-
Disabled — OpenSearch retains the terms exactly as produced by the original custom analyzer
For example, given the entry "kaifang sousuo" (OpenSearch) with the general Chinese analyzer:
With secondary analysis disabled:
Limitations
Quotas
| Resource | Limit |
|---|---|
| Custom analyzers (new OpenSearch console) | 20 |
| Intervention entries per custom analyzer | 1,000 |
Intervention entry constraints
| Constraint | Details |
|---|---|
| Key length | 10 characters maximum |
| Value length | 32 characters maximum |
| Allowed characters | Chinese characters and letters only |
| Prohibited characters | Uppercase letters, full-width characters (U+FF01–U+FF5E), and Chinese punctuation |
| Key format | Cannot contain spaces |
| Semantic analysis entries | The key must equal the value after removing all spaces from the value |
| Key uniqueness | A key cannot be a substring of another entry's value in the same analyzer |
Entry validation examples
Key cannot contain spaces:
| Entry | Valid? | Reason |
|---|---|---|
Key: correctentry, value: correct entry |
Yes | Key has no spaces |
Key: incorrect entry, value: in correct entry |
No | Key contains a space |
For semantic analysis, the key must match the value after removing spaces:
| Entry | Valid? | Reason |
|---|---|---|
Key: correctentry, value: correct entry |
Yes | Key equals value with spaces removed |
Key: incorrectentry, value: wrong entry |
No | Key does not equal value with spaces removed |
Key cannot be a substring of another entry's value:
| Entry | Valid? | Reason |
|---|---|---|
Key: customanalyzer, value: custom analyzer |
Yes | — |
Key: analyzer |
No | analyzer appears in the value of the first entry |
Key: tokenize |
Yes | tokenize does not appear in any other entry's value |
Create a custom analyzer
Prerequisites
Before you begin, ensure that you have:
-
An OpenSearch application
-
Access to the OpenSearch console
Steps
-
In the OpenSearch console, go to Search Configuration Center > Retrieval Configuration in the left-side navigation pane.
-
On the Basic Configuration page, click Analyzer Management in the left-side pane, then click Create.
-
In the Create Analyzer panel, enter a name for the analyzer, select an analyzer type, and click Save.
-
On the Manage Entries page of the new analyzer, click Add. In the Add Intervention Entry panel, set the Search Query and Analysis Results fields, and turn on Secondary Analysis.
Separate terms in the Analysis Results field with spaces. For example, for the key
stickyrice, set the value tosticky rice.
-
Run an analysis test to verify the intervention entry takes effect. 5.1. Enter test text in the Test Text field. 5.2. Review the analysis results across your custom analyzers.
-
Go back to the Basic Configuration page and modify the application configuration offline.
OpenSearch generates an offline version of your application based on your settings. Changes to the offline application do not affect the live application.
-
In the Index Field List section, find the target index field. In the Analysis Method column, select your custom analyzer from the drop-down list.
-
Wait for reindexing to complete. The custom analyzer takes effect after reindexing finishes.
Example: With the general Chinese analyzer, searching for rice does not retrieve documents containing sticky rice, millet, or white rice. After creating a custom analyzer named test_zw, updating the application schema, and reindexing, the search retrieves those documents as expected.
After reindexing
-
Adding intervention entries to a custom analyzer that is already in use requires reindexing before the entries take effect. To trigger reindexing sooner, update the documents whose analysis results are incorrect.
-
A custom analyzer that is assigned to an application cannot be deleted.