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

{
  "items": [
    {"id": "shoe_synonyms", "synonyms": ["shoe", "sneaker", "trainer"]}
  ]
}

The body takes an items array (it may be empty - items can also be added individually, see below). Each item optionally carries a locale and symbols_to_index.

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

Collection-Bound Synonym Sets

Bind sets in the collection schema to apply them to every search on the collection - no per-query parameter needed. A query's own synonym_sets parameter overrides the binding, and enable_synonyms=false disables expansion for a single query:

{
  "name": "products",
  "synonym_sets": ["product_synonyms"],
  "fields": [ ... ]
}

Persistence

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