# Synonyms
The synonyms feature allows you to define search terms that should be considered equivalent. For eg: when you define a synonym for sneaker
as shoe
, searching for sneaker
will now return all records with the word shoe
in them, in addition to records with the word sneaker
.
Typesense supports two types of synonyms:
One-way synonyms: Defining the words
iphone
andandroid
as one-way synonyms ofsmart phone
will cause searches forsmart phone
to return documents containingiphone
orandroid
or both.Multi-way synonyms: Defining the words
blazer
,coat
andjacket
as multi-way synonyms will cause searches for any one of those words (eg:coat
) to return documents containing at least one of the words in the synonym set (eg: records withblazer
orcoat
orjacket
are returned).
Precedence
When using Synonyms and Overrides together, Overrides are handled first since the rules can contain instructions to replace the query. Synonyms will then work on the modified query.
Locale-specific synonyms
When a synonym has a locale
specified, it will only be applied when searching fields with a matching locale. If no locale is specified for a synonym, it will be applied globally. This helps manage cases where the same word has different meanings across languages.
Phrase Match Queries & Filtering
Synonyms are not triggered when using Phrase Search or Filtering, by design.
So for eg, "Site Reliability"
will not return results containing Infrastructure
even if they are defined as multi-way synonyms, because of the double quotes around "Site Reliability"
which makes it a phrase search. So only documents that contain that exact full phrase are returned, without any synonym matches.
Also, synonyms are only applied to the tokens in the q
search parameter, and not to any tokens in the filter_by
parameter. For eg, if you define a multi-way synonym for abc <> xyz
and use filter_by: title:=abc
, it will only match documents where title=abc
, not title=xyz
, because filtering is designed to be similar to a SQL WHERE
condition to do a structured query and synonyms don't apply to filters.
# Create or update a synonym
# Multi-way synonym
# Sample Response
# One-way synonym
# Sample Response
# Definition
PUT ${TYPESENSE_HOST}/collections/:collection/synonyms/:id
# Arguments
Parameter | Required | Description |
---|---|---|
synonyms | yes | Array of words that should be considered as synonyms. |
root | no | For 1-way synonyms, indicates the root word that words in the synonyms parameter map to. |
locale | no | Locale for the synonym. If specified, the synonym will only be applied when searching a field that has a matching locale. If not specified, the synonym will be applied globally. |
symbols_to_index | no | By default, special characters are dropped from synonyms. Use this attribute to specify which special characters should be indexed as is. |
# Retrieve a synonym
We can retrieve a single synonym.
# Sample Response
# Definition
GET ${TYPESENSE_HOST}/collections/:collection/synonyms/:id
# List all synonyms
List all synonyms associated with a given collection.
NOTE: By default, ALL synonyms are returned, but you can use the offset
and limit
parameters to
paginate on the listing.
# Sample Response
# Definition
GET ${TYPESENSE_HOST}/collections/:collection/synonyms
# Delete a synonym
Delete a synonym associated with a collection.
# Sample Response
# Definition
DELETE ${TYPESENSE_HOST}/collections/:collection/synonyms/:id