API Reference / API Methods / Synonyms / Save synonym
Feb. 26, 2019

Save Synonym

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
])

About this method

Create or update a single synonym on an index.

Whether you create or update a synonym, you must specify a unique objectID. If the objectID is not found in the index, the method will automatically create a new synonym.

Each synonym has a single type.

Each type consists of a unique set of attributes

Examples

Create/Update a regular synonym, where all the words are equivalent

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

Create/Update a one way synonym

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

Create/Update a alternative correction 1 synonym

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

Create/Update a alternative correction 2 synonym

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

Create/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>"
}

The angle-bracketed above 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' => 'a-unique-identifier',
  'type' => 'placeholder',
  'placeholder' => '<Street>',
  'replacements' => [
    'street',
    'st'
  ]
], [
  'forwardToReplicas' => true
]);

Parameters

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

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

In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.

JSON format

1
2
3
4
5
{
  "updatedAt":"2013-01-18T15:33:13.556Z",
  "taskID": 678,
  "id": "6891"
}
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?