Skip to content

Search Synonyms

Typesense matches the words a shopper types, with typo tolerance, prefixes and (since the versioned-collection rebuild) stemming, so "boot" finds "boots". It does not know that "shoes" and "footwear" mean the same thing. Synonyms tell it, per site.

Types

Type Behaviour Example
Multi-way Every term finds the others shoes, footwear, boots: each finds all three
One-way The root finds its synonyms, never the reverse root boots → wellies: "boots" finds wellies, "wellies" stays specific

Terms are trimmed, lower-cased and de-duplicated. A multi-way synonym needs at least two terms, a one-way synonym a root and at least one term, with at most 20 terms of 50 characters each and 1,000 synonyms per site. A synonym that duplicates an existing one is refused.

Review flow

Each synonym has a status:

  • Live: applied to search. Synonyms a merchant or agent creates are live straight away.
  • Suggested: proposed by AI, not applied until someone accepts it.
  • Rejected: turned down. Kept, so the same idea isn't proposed again. It is never applied and never exported.

Suggest with AI sends the site's recent zero-result and low-result searches, and the catalogue's own vocabulary (collection, taxonomy, category page and product names), to the site's AI provider and saves the synonym groups it proposes as Suggested. No customer data is sent: search terms are stored without user, session or IP. Suggestions run in the admin app and over MCP. The rest app has no AI integration, so its suggest endpoint answers 501 Not Implemented.

MongoDB is the source of truth (SearchSynonymService, commerce-core search.synonyms). Creating, updating, accepting or deleting a synonym writes it to the site's product collection and, when content search is on, its content collection, using the synonym's id as the Typesense synonym id. Writes are synchronous. If Typesense is down or not configured, the synonym still saves and records the error, and Resync (admin, REST or MCP) replaces the collections' synonyms with the live set.

Collections are rebuilt behind an alias when the schema changes (see Search Architecture). A new collection starts with no synonyms, so the worker listens for SearchCollectionCreatedEvent, which fires after a collection is created and before it goes live, and applies the site's live synonyms to it.

"Why don't I see X when I search for Y?" The explain diagnostic takes a query and, optionally, a product (SKU or seoName) and reports:

  • how many products the query finds, and the top results;
  • whether the product is in the search index, and why not if it isn't (disabled, missing, not yet reindexed);
  • which of the query's words the product's indexed name, description and search terms contain or lack;
  • the synonyms, live and suggested, that apply to the query;
  • what to do: add a synonym, add a word to the product's search terms, and so on.

A product's search terms (attributes.searchTerms, comma-separated, indexed into the stemmed searchTerms field) are edited in three places, all through ProductService and the shared rules in ProductSearchTerms (trimmed, de-duplicated ignoring case, no commas, at most 50 characters a term and 50 terms a product):

  • Admin: the product editor's Shop search card, and Search > Search terms (/admin/search/terms), which lists every product that has some with an inline editor and turns a zero-result search into a term on a product picked by name or SKU. See Search section.
  • MCP: agents can act on the "add to the product's search terms" suggestion themselves: manageProducts update with addSearchTerms (or searchTerms to replace the list, or removeSearchTerms), and products get shows the current searchTerms.

The product is reindexed on save, so the search finds it shortly after. Search terms aren't shown to shoppers: the product attributes block skips them.

Where to manage them

  • Admin: Manage Commerce > Search Synonyms (/admin/search/synonyms): list, add, edit, delete, accept or reject suggestions, Suggest with AI, Resync, and an Explain a search box. The dashboard's zero-result searches link straight to it with the term filled in.
  • REST (admin, spec-first in api.yaml): /v1/admin/search/synonyms (list, create), /{synonymId} (get, update, delete), /{synonymId}/accept, /{synonymId}/reject, /suggest, /resync, and GET /v1/admin/search/explain.
  • MCP: synonyms (actions list, explain, gaps for zero-result searches) and manageSynonyms (create, update, delete, accept, reject, suggest, resync).

Site transfer

Live synonyms travel in search/synonyms.json with new ids. Suggested and rejected ones stay behind. See Site Data Transfer.