Add synonyms

In the Synonyms section, you can add and manage word substitutes for your search index. Synonyms expand search results so that customers find what they're looking for even when they use different terminology than what appears in your product catalog.

Synonyms can be added manually, imported from a CSV file, or proposed automatically by AI agents that analyze search patterns and product data.

Synonym types

Each synonym pair works in one of two directions:

• One-way synonyms work in one direction only. For example, if "TV" is the source term and "television" is its synonym, searching for "TV" returns television products — but searching for "television" does not return TV results.
• Two-way synonyms work in both directions. Terms are treated as fully interchangeable and grouped together. For example, if "smartphone", "phone", and "mobile" are two-way synonyms, searching for any of these terms returns the same results.

Synonym states

Every synonym has a state that indicates its origin and whether it requires your attention:

How synonyms are created

Synonyms come from three sources:

• Manual — You enter synonyms one by one directly in the interface.
• CSV import — You upload a file containing multiple synonyms at once.
• AI agents — The system automatically proposes synonyms and submits them as Suggested for your review and manual activation. These synonyms are based on::
  • User activity — The agent uses time-window analysis to detect patterns where users search for one term, then quickly search for a related term within the same session, indicating a synonym relationship.
  • Product catalog data — For indexes with no search history yet, the agent can analyze your product catalog to generate relevant synonym proposals (cold start option).

Requirements

For imported synonyms:

• The file must be encoded in UTF-8; UTF-8 BOM is not supported.
• Use commas as the word separator.

For synonyms proposed by AI agents: You must have a history of item.search events with the searchType parameter set to full-text-search. The agent analyzes search reformulations — sessions where a user searched for one term and then quickly searched for a related term — so events from such searches must be collected. This requirement does not apply to the cold start option.

Adding synonyms manually

Procedure

1. Go to AI Hub > Indexes.
2. In the list, click the index to which you want to add synonyms.
3. Under the name of the index, select the Synonyms tab.
4. Click Add synonym.
5. From the dropdown list, select Add synonym.
6. From the left dropdown list, define the type of the synonym:
   • One way
     1. In the Word field, enter the source term.
     2. In the Synonym field, enter the synonym for the word.
   • Two ways
     1. In the Synonyms field, enter the terms that are interchangeable with each other.
7. To add more synonyms, click Add synonym.
8. To save the list, click Add.
   Result: The synonyms will be added and they will be assigned the Accepted status.

Adding synonyms by CSV import

1. Go to AI Hub > Indexes.
2. In the list, click the index to which you want to add synonyms.
3. Under the name of the index, select the Synonyms tab.
4. Click Add synonym.
5. From the dropdown list, select Import CSV.
6. Choose the import method:
   • Replace — Deletes all existing synonyms added through the import and saves the ones from the file.
   • Add — Adds the synonyms from the file to the existing list.
7. Upload a CSV file.
   • The imported synonyms will get the Accepted status.
   • See example CSV files.

Example CSV files

One-way synonyms only

word,synonyms,type
phone,smartphone,oneway

If a customer enters phone, results include smartphones. Searching for smartphone returns only smartphones — not phones.

Two-way synonyms only

word,synonyms,type
,"computer,PC",synonyms

The search engine returns the same results for computer and PC.

One-way and two-way synonyms in one file

word,synonyms,type
phone,smartphone,oneway
,"computer,PC",synonyms

• The first row defines a one-way synonym: searching for phone returns smartphones, but not the reverse.
• The second row defines two-way synonyms (first column is empty): computer and PC return the same results.

Adding synonyms by Synonyms Agent

Enable the Synonyms Agent

Before AI agents can propose synonyms, you must enable the Synonyms Agent in the index settings.

Procedure

1. Go to AI Hub > Indexes.
2. Click the index you want to configure.
3. Under the name of the index, select the Settings tab.
4. Find the Synonyms Agent section.
   

   

5. Toggle the switch from Disabled to Enabled. Result:
   

   

6. In the Suggestion frequency section, select how often the agent proposes new synonyms:

   • Monthly — Uses more data for higher confidence, but learns more slowly (every 30 days).
   • Weekly — Faster training, lower confidence.
7. Click Apply.
   Result: The agent runs at the selected frequency and proposes synonyms in the Synonyms tab. When the synonyms suggestions will be ready for review, a notification banner will appear on the list of synonyms.
   
   If you disable the agent, it is queued for shutdown and stops running at the next scheduled time.
   

Initial synonym generation (Cold start)

For new indexes with no search history, you can trigger a one-time synonym generation based on your product catalog data.

To run the cold start:

1. In the Synonyms Agent section, find Initial synonym generation (Cold start).
2. Toggle the switch to enable it.
3. Click Apply.

Review AI-proposed synonyms

AI agents run on a recurring schedule and propose new synonyms based on search behavior and catalog data. When the synonyms suggestions are ready for review, a notification banner appears on the list of synonyms.

Procedure

1. Go to AI Hub > Indexes.
2. Click the index you want to manage.
3. Select the Synonyms tab.
   Result: A notification banner is displayed above the synonym list.
   

   

4. On the notification banner, click Review suggestions.
   Result: A pop-up appears.
   

   

5. Review each proposal and decide:

   Accepting and rejecting synonyms is irreversible.

   • Accept the synonym.
   • Reject to dismiss the proposal.
   • Edit the proposal.
     When you edit the proposal, you save and accept the edited proposal, this action is irreversible.

Accepted synonyms become active with the Accepted state. Rejected proposals are retained with the Rejected state for reference.