Synonyms & Taxonomy Tools

Marqo handles equivalent wording in two independent ways. Embedding-based retrieval matches meaning rather than exact words, so many synonyms are handled without any configuration. On top of that, synonym groups let you map specific queries onto a phrase of your choosing, for the cases where you need a guaranteed result.

Two Mechanisms, One Outcome

	Embedding-based matching	Synonym groups
Configured by	Nobody, it is always on	You, in the merchandising console
Works on	Meaning and context	The exact query string
Changes the query	No	Yes, the query is replaced before the search runs
Use it for	General wording differences	Terms you must control, and terms that must share merchandising rules

Embedding-based retrieval covers a lot of ground on its own. A search for "trainers" can surface running shoes without anyone maintaining a list, because the query and the product text are compared as vectors rather than as tokens.

Synonym groups exist for the cases where that is not enough: a house term your catalogue does not use, a brand shorthand, a campaign phrase, or a query you want to inherit another query's merchandising rules.

How Synonym Groups Work

A synonym group has one parent phrase and any number of child terms. When a shopper's query matches a child term, Marqo replaces the query with the parent phrase and runs the search as if the shopper had typed the parent phrase.

Matching is on the whole query, not on words inside it. It is case-insensitive and ignores leading and trailing whitespace, and is otherwise exact.

Shopper types	Group	Result
sneakers	child of running shoes	Searches for running shoes
SNEAKERS	child of running shoes	Searches for running shoes
mens sneakers	child of running shoes	No substitution, the whole query does not match the child term

Because substitution happens before anything else, the parent phrase is what the rest of the pipeline sees.

What Substitution Affects

• The response query field reports the parent phrase, not what the shopper typed. Your storefront should keep the shopper's original text for display and analytics if it needs it.
• Merchandising rules resolve against the parent phrase. This is the useful part: a rule authored on the parent phrase automatically covers every child term in the group, so you curate one query instead of ten.
• Dynamic facet rules resolve against the parent phrase for the same reason. See Dynamic Facets.
• Search redirects are matched against the parent phrase.

Where Substitution Does Not Apply

Substitution runs on the /search, /instant-search and /composite-search endpoints. It does not apply to:

• Collection requests, whether the shopper is browsing a collection or searching inside one.
• Weighted queries, where q is an object of terms and weights.
• Image queries, where q is an image URL or a data URL.

note

Because a rule authored on a child term is never reached, always author merchandising and facet rules against the parent phrase. A rule on a child term is silently dead: by the time rules are resolved, the query has already been replaced.

Configuring Synonym Groups

Synonym groups are managed in the merchandising console. Create a group, set its parent phrase, and add the child terms that should map onto it.

Choose the parent phrase carefully. It is the query that actually runs, so it should be the wording that retrieves the best results, which is usually the term your catalogue uses rather than the term shoppers type.

Published changes take a few minutes to reach live traffic.

Testing a Group

1. Navigate to Merchandising → Search Merchandising
2. Enter the child term you want to check
3. Confirm the results match what the parent phrase returns
4. Adjust ranking for the group by merchandising the parent phrase with boost/bury, pinning or exclusions

Best Practices

1. Reach for groups deliberately: embedding-based matching already covers ordinary wording differences, so add a group when you need a guaranteed outcome rather than as routine maintenance
2. Author rules on the parent phrase: it is the only trigger that fires for the whole group
3. Pick a parent phrase that retrieves well: it replaces the shopper's query verbatim
4. Remember the whole-query rule: sneakers as a child term does not cover mens sneakers, so add the variants you care about
5. Check your analytics: the response reports the substituted query, so make sure your storefront reports the term the shopper actually typed

Related Topics

• Attribute Enrichment - Automatic attribute extraction
• LLM Based Ranking and Relevance - Learn how the ranking system works
• Dynamic Facets - Facet rules resolve against the parent phrase