Synonyms

Synonyms expand search queries to include alternative terms. Define synonym sets with multiple expansion alternatives, locale support, and root word mapping.

Synonym Sets

A synonym set is a named group of synonym rules. You can create multiple sets and apply them selectively to search queries.

Create a Synonym Set

PUT /synonym_sets/product_synonyms
Content-Type: application/json
X-TYPESENSE-API-KEY: YOUR_API_KEY

{
  "locale": "en"
}

List Synonym Sets

GET /synonym_sets
X-TYPESENSE-API-KEY: YOUR_API_KEY

Get a Synonym Set

GET /synonym_sets/product_synonyms
X-TYPESENSE-API-KEY: YOUR_API_KEY

Delete a Synonym Set

DELETE /synonym_sets/product_synonyms
X-TYPESENSE-API-KEY: YOUR_API_KEY

Synonym Items

Each item within a synonym set defines a group of interchangeable terms or a one-way root mapping.

Create a Synonym Item

PUT /synonym_sets/product_synonyms/items/shoe_synonyms
Content-Type: application/json
X-TYPESENSE-API-KEY: YOUR_API_KEY

{
  "synonyms": ["shoe", "sneaker", "trainer", "footwear"]
}

When any of these terms appears in a search query, Torque expands the query to include all alternatives.

Root Synonyms

Use root for one-way synonyms where specific terms map to a canonical form:

PUT /synonym_sets/product_synonyms/items/laptop_root
Content-Type: application/json
X-TYPESENSE-API-KEY: YOUR_API_KEY

{
  "root": "laptop",
  "synonyms": ["notebook", "portable computer"]
}

Searching for “notebook” or “portable computer” will also match “laptop”, but searching for “laptop” will not expand to include the other terms.

List Synonym Items

GET /synonym_sets/product_synonyms/items
X-TYPESENSE-API-KEY: YOUR_API_KEY

Get a Synonym Item

GET /synonym_sets/product_synonyms/items/shoe_synonyms
X-TYPESENSE-API-KEY: YOUR_API_KEY

Delete a Synonym Item

DELETE /synonym_sets/product_synonyms/items/shoe_synonyms
X-TYPESENSE-API-KEY: YOUR_API_KEY

Using Synonyms in Search

Specify which synonym sets to apply with the synonym_sets parameter:

GET /collections/products/documents/search?\
q=sneaker&query_by=title,description&synonym_sets=product_synonyms
X-TYPESENSE-API-KEY: YOUR_API_KEY

Multiple synonym sets can be applied (comma-separated):

synonym_sets=product_synonyms,brand_synonyms

Persistence

Synonym sets and their items are persisted to disk and restored on server restart.