Use blacklists and whitelists to control which search queries appear as drop-down suggestions, top searches, and hints. Add unwanted queries to a blacklist to block them, or add high-quality queries to a whitelist to promote them to the top of results.
How it works
Blocking: A blacklist uses inclusion matching (equivalent to substring matching). If any segmented term in a candidate search query matches a blacklisted keyword, the entire query is blocked. For example, if "garbage" is in a blacklist, any query whose terms include "garbage" is excluded from results.
Promoting: A whitelist query that meets the recommendation condition is prioritized in the candidate search query results.
Conflict resolution: If the same query matches both a blacklist and a whitelist, the blacklist takes precedence.
Regular expression support: Blacklists support regular expressions, which lets you cover many similar patterns with a single entry—useful for staying within entry limits.
Immediate effect: Changes take effect immediately. Retraining the model is not required.
Behavior by list type
| List type | Behavior when active |
|---|---|
| Drop-down suggestion blacklist | Matching queries do not appear in drop-down suggestions |
| Drop-down suggestion whitelist | Matching queries are prioritized in drop-down suggestions |
| Top search blacklist | Matching queries are excluded from top searches |
| Top search whitelist | Queries appear in the specified positions of top searches. If no queries are configured for a position, results follow the top search model ranking |
| Hint blacklist | Matching queries are excluded from hints |
| Hint whitelist | Queries rotate as recommended search queries in hints |
Create and apply an intervention dictionary
Prerequisites
Before you begin, ensure that you have:
Access to the OpenSearch console
An existing drop-down suggestion model to attach the dictionary to
Create a blacklist or whitelist
Log on to the OpenSearch console. In the left-side navigation pane, choose Search Algorithm Center > Search Guidance.
On the Drop-down Suggestions page, click Blacklists and Whitelists in the left-side pane.
On the Blacklists and Whitelists page, click Create.
In the Create Whitelist or Blacklist panel, configure the following:
Name: Enter a name for the intervention dictionary.
Type: Select the list type. Choose Drop-down Suggestions Whitelist to promote queries, or Drop-down Suggestions Blacklist to block them.
Click Save.
On the Blacklists and Whitelists page, find the dictionary you created and click Manage Entries in the Actions column.
Add intervention entries to the dictionary.
Attach the dictionary to a model
After adding entries, attach the intervention dictionary to a drop-down suggestion model to activate it.
Limits
| List type | Max entries |
|---|---|
| Drop-down suggestion blacklist | 500 |
| Drop-down suggestion whitelist | 500 |
| Top search blacklist | 500 |
| Top search whitelist | 10 |
| Hint blacklist | 500 |
| Hint whitelist | 3 |
Note: Blacklists support regular expressions. Use a single regex pattern to match multiple similar queries and stay within the entry limit. Blacklists and whitelists referenced by a model cannot be deleted—detach the dictionary from all models before deleting it.