# 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:

1. **One-way synonyms**: Defining the words `iphone` and `android` as one-way synonyms of `smart phone` will cause searches for `smart phone` to return documents containing `iphone` or `android` or both.

2. **Multi-way synonyms**: Defining the words `blazer`, `coat` and `jacket` 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 with `blazer` or `coat` or `jacket` are returned).

## Create or update a synonym

### Multi-way synonym


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

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



```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);
```


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

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


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

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


```dart
final synonym = {
  "synonyms": ["blazer", "coat", "jacket"]
};

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


```java
SearchSynonymSchema synonym = new SearchSynonymSchema();
synonym.addSynonymsItem("blazer").addSynonymsItem("coat").addSynonymsItem("jacket");

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


```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"]
}'
```


#### Sample Response


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


### One-way synonym


```js
synonym = {
  "root": "smart phone",
  "synonyms": ["iphone", "android"]
}

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



```php
$synonym = [
  'root' => 'smart phone',
  'synonyms' => ['iphone', 'android'],
];

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


```py
synonym = {
  "root": "smart phone",
  "synonyms": ["iphone", "android"]
}

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


```rb
synonym = {
  "root": "smart phone",
  "synonyms": ["iphone", "android"]
}

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


```dart
final synonym = {
  "root": "smart phone",
  "synonyms": ["iphone", "android"]
};

// Creates/updates a synonym called `smart-phone-synonyms` in the `products` collection
await client.collection('products').synonyms.upsert('smart-phone-synonyms', synonym);
```


```java
SearchSynonymSchema synonym = new SearchSynonymSchema();
synonym.addSynonymsItem("iphone").addSynonymsItem("android");
synonym.root("smart phone");

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


```bash
curl "http://localhost:8108/collections/products/synonyms/smart-phone-synonyms" -X PUT \
-H "Content-Type: application/json" \
-H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '{
    "root": "smart phone",
    "synonyms": ["iphone", "android"]
}'
```


#### Sample Response


```json
{
  "id":"smart-phone-synonyms",
  "root":"smart phone",
  "synonyms": ["iphone", "android"]
}
```


#### 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.


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



```php
$client->collections['products']->synonyms['coat-synonyms']->retrieve();
```


```py
client.collections('products').synonyms['coat-synonyms'].retrieve
```


```rb
client.collections('products').synonyms['coat-synonyms'].retrieve
```


```dart
await client.collection('products').synonym('coat-synonyms').retrieve();
```


```java
SearchSynonym searchSynonym = client.collections("products").synonyms("coat-synonyms").retrieve();
```


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


#### Sample Response


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


#### Definition
`GET ${TYPESENSE_HOST}/collections/:collection/synonyms/:id`

## List all synonyms
List all synonyms associated with a given collection.


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



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


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


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


```dart
await client.collection('products').synonyms.retrieve();
```


```java
SearchSynonymsResponse searchSynonymsResponse =  client.collections("products").synonyms().retrieve();
```


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


#### Sample Response


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


#### Definition
`GET ${TYPESENSE_HOST}/collections/:collection/synonyms`

## Delete a synonym
Delete a synonym associated with a collection.


```js
client.collections('products').synonyms('coat-synonyms').delete()
```



```php
$client->collections['products']->synonyms['coat-synonyms']->delete();
```


```py
client.collections['products'].synonyms['coat-synonyms'].delete()
```


```rb
client.collections['products'].synonyms['coat-synonyms'].delete
```


```dart
await client.collection('products').synonym('coat-synonyms').delete();
```


```java
SearchSynonym searchSynonym = client.collections("products").synonyms("coat-synonyms").delete();
```


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


#### Sample Response


```json
{
  "id": "coat-synonyms"
}
```


#### Definition
`DELETE ${TYPESENSE_HOST}/collections/:collection/synonyms/:id`