🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API client / Methods / Synonyms
Required API Key: any key with the editSettings ACL
Method signature
$index->saveSynonym(array synonym);

$index->saveSynonym(array synonym, [
  // All the following parameters are optional
  'forwardToReplicas' => boolean
])

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

About this method

Add a synonym to an index or replace it.

When you add or update a synonym, you must specify a unique objectID.

objectID isn’t a reference to an Algolia record: it’s the unique identifier for a synonym object.

To add multiple synonyms in a single API request, use the saveSynonyms method.

If the synonym objectID doesn’t exist, Algolia adds a new one.

If you use an existing synonym objectID, the existing synonym is replaced with the new one.

Examples

Read the Algolia CLI documentation for more information.

Add or update a regular synonym, where all the words are equivalent

1
2
3
4
5
6
7
8
9
10
11
$index->saveSynonym([
  'objectID' => 'synonymID',
  'type' => 'synonym',
  'synonyms' => [
    'car',
    'vehicle',
    'auto'
  ]
], [
  'forwardToReplicas' => true
]);

Add or update a one way synonym

1
2
3
4
5
6
7
8
9
10
$index->saveSynonym([
  'objectID' => 'synonymID',
  'type' => 'oneWaySynonym',
  'input' => 'car',
  'synonyms' => [
    'vehicle',
    'auto'
  ], [
    'forwardToReplicas' => true
  ]);

Add or update an alternative correction 1 synonym

1
2
3
4
5
6
7
8
9
10
11
$index->saveSynonym([
  'objectID' => 'synonymID',
  'type' => 'altCorrection1',
  'word' => 'car',
  'corrections' => [
    'vehicle',
    'auto'
  ]
], [
  'forwardToReplicas' => true
]);

Add or update an alternative correction 2 synonym

1
2
3
4
5
6
7
8
9
10
11
$index->saveSynonym([
  'objectID' => 'synonymID',
  'type' => 'altCorrection2',
  'word' => 'car',
  'corrections' => [
    'vehicle',
    'auto'
  ]
], [
  'forwardToReplicas' => true
]);

Add or update a placeholder synonym

To create placeholders, enclose the desired terms in angle brackets in the records. Consider this record:

1
2
3
{
  "address": "589 Howard <Street>"
}

<Street> refers to the placeholder as defined below when the synonym is created:

1
2
3
4
5
6
7
8
9
10
11
$index->saveSynonym([
  'objectID' => 'synonymID',
  'type' => 'placeholder',
  'placeholder' => '<Street>',
  'replacements' => [
    'street',
    'st'
  ]
], [
  'forwardToReplicas' => true
]);

Parameters

Parameter Description
objectID
type: string
Required

Must be unique. It can contain any character, and be of unlimited length.

With this method, you either create a new synonym or update an existing one. In both cases, you must specify an objectID. When the objectID is not found in the index, it will create a new synonym; otherwise, it will be an update.

Note that for some languages, this parameter is duplicated in the synonym object.

synonym
Required

A synonym object with only one type (see param below). Each type consists of a unique set of attributes.

forwardToReplicas
type: boolean
default: false
optional

By default, this method applies only to the specified index. By making this true, the method will also send the synonym to all replicas. Thus, if you want to forward your synonyms to replicas you will need to specify that.

synonym ➔ synonym object

Parameter Description
objectID
type: string
Required for only some languages

Must contain the same value as the objectId above.

type
type: string
Required

There are 4 synonym types. The parameter can be one of the following values:

  • synonym
  • oneWaySynonym
  • altCorrection1 or altCorrection2
  • placeholder
synonyms
type: list
Required if type=synonym or type=oneWaySynonym

A list of synonyms (up to 20 for type synonym and 100 for type oneWaySynonym).

input
type: string
Required if type=oneWaySynonym

Defines the synonym. A word or expression, used as the basis for the array of synonyms.

word
type: string
Required if type=altCorrection1 or type=altCorrection2

A single word, used as the basis for the below array of corrections.

corrections
type: list
Required if type=altCorrection1 or type=altCorrection2

An list of corrections of the word.

placeholder
type: string
Required if type=placeholder

A single word, used as the basis for the below array of replacements.

replacements
type: list
Required if type=placeholder

An list of replacements of the placeholder.

Response

This section shows the JSON response returned by the API. Each API client encapsulates this response inside objects specific to the programming language, so that the actual response might be different. You can view the response by using the getLogs method. Don’t rely on the order of attributes in the response, as JSON doesn’t guarantee the ordering of keys in objects.

JSON format

1
2
3
4
5
{
  "updatedAt":"2013-01-18T15:33:13.556Z",
  "taskID": 678,
  "id": "6891"
}
Field Description
id
string

objectID of the inserted object.

updatedAt
string

Date at which the indexing job has been created.

taskID
integer

The taskID used with the waitTask method.

Did you find this page helpful?