Search Synonyms

Map equivalent or one-way terms to improve query recall without changing catalog data.

Audience: Search managers tuning lexical matching and long-tail intent coverage.

Critical: Synonym management is site-scoped under /api/v1/sites/:siteId/search/analytics/synonyms and requires search synonym permissions.

Search Overview Zero Results Search Analytics

Who This Page Is For

Use this page when users search with alternate phrasing (for example "trainers" vs "sneakers") and you need deterministic term mapping.

Quick Start (2-5 Minutes)

List existing groups

Fetch active and inactive synonym groups for site.

GET /api/v1/sites/:siteId/search/analytics/synonyms?isActive=true

Create equivalent group

Use type=equivalent for bidirectional matching.

POST /api/v1/sites/:siteId/search/analytics/synonyms

Create one-way mapping

Use type=one_way with sourceTerm for controlled expansion.

{ "terms": ["hoodie", "hooded sweatshirt"], "type": "one_way", "sourceTerm": "hoodie" }

Adjust or disable group

Update terms or set isActive=false for rollback-safe tuning.

PUT /api/v1/sites/:siteId/search/analytics/synonyms/:synonymId

Remove obsolete mapping

Delete synonym when no longer needed.

DELETE /api/v1/sites/:siteId/search/analytics/synonyms/:synonymId

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`terms`	Required	`string[]`	Create synonym	List of terms to be linked in synonym group.
`type`	Optional	`equivalent \| one_way`	Create/update synonym	Matching direction behavior.
`sourceTerm`	Conditional	`string`	one_way synonyms	Source token for one-way expansion.
`isActive`	Optional	`boolean`	Update synonym	Soft-disable mapping without deleting record.

Synonym endpoints

GET    /api/v1/sites/:siteId/search/analytics/synonyms
POST   /api/v1/sites/:siteId/search/analytics/synonyms
PUT    /api/v1/sites/:siteId/search/analytics/synonyms/:synonymId
DELETE /api/v1/sites/:siteId/search/analytics/synonyms/:synonymId

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Symmetric terms should match each other	type=equivalent	Bidirectional matching improves recall.
Only one query direction should expand	type=one_way + sourceTerm	Prevents noisy reverse expansion.
Need safe rollback of a bad synonym set	PUT ... isActive=false	Disables effect without deleting audit history.
Mapping no longer useful and should be removed	DELETE synonym	Cleans up stale query logic permanently.
Need evidence of impact	Pair with search analytics top-queries/zero-results	Shows whether synonym reduced misses.

Common Errors and Fixes

No change in result quality after synonym creation

Cause: Synonym inactive or query path uses different normalized term.

Fix: Verify isActive=true and inspect normalized query in logs.

Unexpected broad matching

Cause: Equivalent group contains overly generic terms.

Fix: Split into narrower groups or switch to one_way mapping.

Validation failure on create

Cause: terms field missing or not an array.

Fix: Send terms as non-empty string array.

One-way mapping behaves like equivalent

Cause: Missing sourceTerm when type=one_way.

Fix: Set sourceTerm explicitly in payload.

Production Checklist

Each synonym group has clear business intent and owner.Required
one_way groups always include explicit sourceTerm.Required
High-volume queries are reviewed after synonym deployment.Required
Rollback procedure uses isActive toggle before delete.Required
Changes are correlated with zero-results trend movement.Required