OpenSearch's built-in dictionary handles most spelling corrections automatically, but it fails to recognize product codes, brand names, and domain-specific terms. An intervention dictionary lets you define custom correction entries that override the built-in dictionary for those cases — ensuring queries like manhatan are corrected to manhattan, or preventing the built-in dictionary from incorrectly "correcting" a product code.
How it works
When a search query matches an intervention entry, OpenSearch applies the correction defined in that entry and retains it. The built-in dictionary then processes the remaining unmatched terms.
Spelling correction based on intervention entries has high credibility. OpenSearch applies intervention corrections first, retains them, and then processes the unchanged part of the query using the built-in dictionary.
Example:
Intervention entry:
mobile phone changer -> mobile phone chargerSearch query:
which mobile phone changer brad is goodResult: The intervention entry corrects changer to charger. The built-in dictionary corrects brad to brand. Final result: which mobile phone charger brand is good.
Intervention entry types
There are two types of intervention entries:
| Type | Behavior |
|---|---|
| Add | OpenSearch corrects the search query and retrieves results based on the corrected query. |
| Block | OpenSearch does not correct the search query and does not retrieve results based on the correcting query. |
Use Block when the built-in dictionary incorrectly "corrects" a term you want to keep as-is. For example, if the built-in dictionary changes a product code xr100 to xr1000, add a Block entry for xr100 to prevent that correction.
Matching rules
When multiple intervention entries could apply to a search query, OpenSearch resolves conflicts using three rules:
Rule 1: Earlier entry takes precedence
If two entries have overlapping predefined queries, the entry added first takes effect.
Example: query china constructing back, entries china constructing -> china construction and construction back -> construction bank. Both entries partially match, but only the first entry applies. Result: china construction back.
Rule 2: Longer predefined query takes precedence
If two entries share the same starting term, the entry with the longer predefined query wins.
Example: query opansearching is excellent, entries opan -> open and opansearching -> opensearch. The longer entry matches the full term. Result: opensearch is excellent.
Rule 3: Multiple entries can take effect
In inclusive match mode, multiple non-overlapping entries can each correct a different part of the same query.
Note: Intervention entries use inclusive match, not substring match. An entry takes effect only when one or more consecutive, complete semantic terms (up to five) in the query match the predefined query in the entry.
Create a spelling correction dictionary
Prerequisites
Before you begin, make sure that you have:
An OpenSearch application with query analysis rules configured
Access to the OpenSearch console
Step 1: Create the dictionary
Log on to the OpenSearch console. In the left-side navigation pane, choose Search Algorithm Center > Retrieval Configuration.
On the Basic Configuration page, click Dictionary Management in the left-side pane.
On the Dictionary Management page, click Create in the upper-right corner.
In the Create Query Analysis Dictionary panel, enter a name for the dictionary, set Dictionary Type to Spelling Correction, and click Save.
The dictionary appears in the dictionary list.
Step 2: Add intervention entries
Find the dictionary in the list and click Manage Entries in the Actions column.
On the Manage Entries page, click Add Intervention Entry.
In the Add Intervention Entry panel, fill in the fields:
Field Description Search Query The misspelled term or phrase to match Corrected Word The corrected term or phrase Intervention Type Select Add to enable correction, or Block to prevent correction Click Save.
Note: Each intervention entry must have a unique search query. OpenSearch normalizes all entry content: uppercase letters are converted to lowercase, and full-width characters are converted to half-width characters.
Step 3: Associate the dictionary with a query analysis rule
Go to the Query Analysis Rule Configuration page and click Create in the upper-right corner.
In the Create Rule panel, select the intervention dictionary and associate it with the query analysis rule.
One intervention dictionary can be associated with multiple query analysis rules.
Step 4: Test before going live
Run a search test to verify spelling correction results before applying the rule to a live application. This confirms the intervention entries produce the expected output.
Example
Scenario: An e-commerce shopping guide application uses OpenSearch with query analysis rules. After going live, some search queries return unexpected results due to incomplete spelling correction.
Problem: Customers searching for manhatan get very few results because the built-in dictionary does not recognize it as a misspelling of manhattan. Most documents containing manhattan are not retrieved.
Solution: Add the intervention entry manhatan -> manhattan to a spelling correction dictionary, then associate the dictionary with the query analysis rule.
Steps:
Create a spelling correction dictionary (see Step 1).
Add the intervention entry: set Search Query to
manhatan, set Corrected Word tomanhattan, and set Intervention Type to Add.Associate the dictionary with the query analysis rule (see Step 3).
Run a search test. OpenSearch now returns results for
manhattanwhen customers entermanhatan.
Limits and constraints
| Constraint | Limit |
|---|---|
| Intervention dictionaries per application | 20 |
| Search queries per intervention entry | 1 |
| Correcting queries per intervention entry | 1 |
| Intervention entries per dictionary | 1,000 |
Additional constraints:
An entry takes effect when any term in the search query matches the predefined query. For example, the entry
changer -> chargerapplies to the querymobile phone changer— OpenSearch does not require an entry for the full phrase.Intervention takes effect only for one or more (up to five) consecutive and complete semantic terms that match the predefined query (inclusive match, not substring match).
Intervention-based spelling correction takes priority over built-in dictionary correction.
You cannot change the name or type of a dictionary after it is created.
You cannot delete a dictionary that is associated with a query analysis rule, whether the rule is applied to a live or offline application. Disassociate the dictionary from the rule first.