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:

Multi-way synonyms: Defining words ABC, DEF and XYZ (for eg) as multi-way synonyms will cause searches for any one of those words (eg: DEF) to return records containing at least one of the words in the synonym set (eg: records with ABC or DEF or KYX are returned).
One-way synonyms: Defining the words DEF and XYZ as one-way synonyms of ABC will cause searches for DEF or XYZ to return records containing ABC.

Create or update a synonym

Multi-way synonym

synonym = {
  "synonyms": ["blazer", "coat", "jacket"]
}

// Creates/updates a synonym called `coat-synonyms` in the `products` collection
client.collections('products').synonyms().upsert('coat-synonyms', synonym)

</template> <template v-slot:PHP>

php

$synonym = [
  "synonyms" => ["blazer", "coat", "jacket"]
]

# Creates/updates a synonym called `coat-synonyms` in the `products` collection
$client->collections['products']->synonyms->upsert('coat-synonyms', $synonym)

</template> <template v-slot:Python>

synonym = {
  "synonyms": ["blazer", "coat", "jacket"]
}

# Creates/updates a synonym called `coat-synonyms` in the `products` collection
client.collections['products'].synonyms.upsert('coat-synonyms', synonym)

</template> <template v-slot:Ruby>

synonym = {
  "synonyms" => ["blazer", "coat", "jacket"]
}

# Creates/updates a synonym called `coat-synonyms` in the `products` collection
client.collections['products'].synonyms.upsert('coat-synonyms', synonym)

</template> <template v-slot:Shell>

bash

curl "http://localhost:8108/collections/products/synonyms/coat-synonyms" -X PUT \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
  "synonyms": ["blazer", "coat", "jacket"]
}'

</template> </Tabs>

Sample Response

json

{
  "id": "coat-synonyms",
  "synonyms": ["blazer", "coat", "jacket"]
}

</template> </Tabs>

One-way synonym

synonym = {
  "root": "blazer",
  "synonyms": ["coat", "jacket"]
}

// Creates/updates a synonym called `blazer-synonyms` in the `products` collection
client.collections('products').synonyms().upsert('blazer-synonyms', synonym)

</template> <template v-slot:PHP>

php

synonym = {
  "root": "blazer",
  "synonyms": ["coat", "jacket"]
}

// Creates/updates a synonym called `blazer-synonyms` in the `products` collection
client.collections('products').synonyms().upsert('blazer-synonyms', synonym)

</template> <template v-slot:Python>

synonym = {
  "root": "blazer",
  "synonyms": ["coat", "jacket"]
}

// Creates/updates a synonym called `blazer-synonyms` in the `products` collection
client.collections('products').synonyms().upsert('blazer-synonyms', synonym)

</template> <template v-slot:Ruby>

synonym = {
  "root": "blazer",
  "synonyms": ["coat", "jacket"]
}

// Creates/updates a synonym called `blazer-synonyms` in the `products` collection
client.collections('products').synonyms().upsert('blazer-synonyms', synonym)

</template> <template v-slot:Shell>

bash

synonym = {
  "root": "blazer",
  "synonyms": ["coat", "jacket"]
}

// Creates/updates a synonym called `blazer-synonyms` in the `products` collection
client.collections('products').synonyms().upsert('blazer-synonyms', synonym)

</template> </Tabs>

Sample Response

json

{
  "id":"coat-synonyms",
  "root":"blazer",
  "synonyms": ["coat", "jacket"]
}

</template> </Tabs>

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.

Retrieve a synonym

We can retrieve a single synonym.

client.collections('products').synonyms('coat-synonyms').retrieve

</template> <template v-slot:PHP>

php

client.collections('products').synonyms('coat-synonyms').retrieve

</template> <template v-slot:Python>

client.collections('products').synonyms('coat-synonyms').retrieve

</template> <template v-slot:Ruby>

client.collections('products').synonyms('coat-synonyms').retrieve

</template> <template v-slot:Shell>

bash

client.collections('products').synonyms('coat-synonyms').retrieve

</template> </Tabs>

Sample Response

json

{
  "id": "coat-synonyms",
  "root":"",
  "synonyms": ["blazer", "coat", "jacket"]
}

</template> </Tabs>

Definition

GET ${TYPESENSE_HOST}/collections/:collection/synonyms/:id

List all synonyms

List all synonyms associated with a given collection.

client.collections('products').synonyms().retrieve

</template> <template v-slot:PHP>

php

$client->collections['products']->synonyms->retrieve()

</template> <template v-slot:Python>

client.collections['products'].synonyms.retrieve()

</template> <template v-slot:Ruby>

client.collections['products'].synonyms.retrieve

</template> <template v-slot:Shell>

bash

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/products/synonyms"

</template> </Tabs>

Sample Response

json

curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
"http://localhost:8108/collections/products/synonyms"

</template> </Tabs>

Definition

GET ${TYPESENSE_HOST}/collections/:collection/synonyms

Delete a synonym

Delete a synonym associated with a collection.

client.collections('books').synonyms('coat-synonyms').delete()

</template> <template v-slot:PHP>

php

$client->collections['books']->synonyms['coat-synonyms'].delete()

</template> <template v-slot:Python>

client.collections['books'].synonyms['coat-synonyms'].delete()

</template> <template v-slot:Ruby>

client.collections['books'].synonyms['coat-synonyms'].delete

</template> <template v-slot:Shell>

bash

curl "http://localhost:8108/collections/books/synonyms/coat-synonyms" -X DELETE \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}"

</template> </Tabs>

Sample Response

json

{
  "id": "coat-synonyms"
}

</template> </Tabs>

Definition

DELETE ${TYPESENSE_HOST}/collections/:collection/synonyms/:id