API client / Methods / Synonyms

Jun. 08, 2023

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

index.save_synonym(
  Hash synonym,
  Hash opts = {
    Boolean forwardToReplicas: false
  }
)

index.saveSynonym(object synonym)

index.saveSynonym(object synonym, {
  // All the following parameters are optional
  forwardToReplicas => boolean
})

index.save_synonym(dict synonym, {
  // All the following parameters are optional
  'forwardToReplicas': bool
})

index.saveSynonym(
  _ synonym: Synonym,
  forwardToReplicas: Bool? = nil,
  requestOptions: RequestOptions? = nil,
  completion: Result<SynonymRevision> -> Void
)

suspend fun Index.saveSynonym(
    synonym: Synonym,
    forwardToReplicas: Boolean? = null,
    requestOptions: RequestOptions? = null
): RevisionSynonym

index.SaveSynonym(
  Synonym synonym,

  // All the following parameters are optional
  forwardToReplicas: bool
)

index.saveSynonym(
  Synonym synonym,
  bool forwardToReplicas
)

index.AddSynonym(Synonym synonym)
index.AddSynonym(Synonym synonym, opt.ForwardToReplicas(bool forwardToReplicas)

save.synonym(Synonym synonym)
    .inIndex("index_name")
    .and(bool forwardToReplicas)

See code examples

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

Copy

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

1
2
3
4
5
6
7
index.saveSynonym({
  objectID: 'synonymID',
  type: 'synonym',
  synonyms: ['car', 'vehicle', 'auto']
}, { forwardToReplicas: true }).then(() => {
  // done
});

1
2
3
4
5
6
7
8
let synonym: Synonym = .multiWay(objectID: "synonymID",
                                 synonyms: ["car", "vehicle", "auto"])

index.saveSynonym(synonym, forwardToReplicas: true) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
val synonym = Synonym.MultiWay(
    objectID = ObjectID("synonymID"),
    synonyms = listOf("car", "vehicle", "auto")
)

index.saveSynonym(synonym, forwardToReplicas = true)

1
2
3
4
5
6
7
8
9
10
11
var synonym = new Synonym
{
  ObjectID = "synonymID",
  Type = "synonym",
  Synonyms = new List<string> { "car", "vehicle", "auto" }
};

index.SaveSynonym(synonym, forwardToReplicas: true);

// Asynchronous
await index.SaveSynonymAsync(synonym, forwardToReplicas: true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
bool forwardToReplicas = true;

Synonym synonym = Synonym.createSynonym(
    "synonymID",
     Arrays.asList("car", "vehicle", "auto"));
// or
Synonym synonym = new Synonym()
              .setObjectID("synonymID")
              .setType(SynonymType.SYNONYM)
              .setSynonyms(Arrays.asList("car", "vehicle", "auto"));

// Sync version
index.saveSynonym(synonym, forwardToReplicas);

// Async version 
index.saveSynonymAsync(synonym, forwardToReplicas);

1
2
3
4
5
6
7
8
forwardToReplicas := opt.ForwardToReplicas(true)
synonym := search.NewRegularSynonym(
  "synonymID",
  "car",
  "vehicle",
  "auto",
)
res, err := index.SaveSynonym(synonym, forwardToReplicas)

Add or update a one way synonym

Copy

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

1
2
3
4
5
6
7
8
index.saveSynonym({
  objectID: 'synonymID',
  type: 'oneWaySynonym',
  input: 'car',
  synonyms: ['vehicle', 'auto']
}, { forwardToReplicas: true }).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
index.save_synonym({
    'objectID': 'synonymID',
    'type': 'oneWaySynonym',
    'input': 'car',
    'synonyms': [
        'vehicle',
        'auto'
    ]
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
9
let synonym: Synonym = .oneWay(objectID: "synonymID",
                               input: "car",
                               synonyms: ["vehicle", "auto"])

index.saveSynonym(synonym, forwardToReplicas: true) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
val synonym = Synonym.OneWay(
    objectID = ObjectID("synonymID"),
    input = "car",
    synonyms = listOf("vehicle", "auto")
)

index.saveSynonym(synonym, forwardToReplicas = true)

1
2
3
4
5
6
7
8
9
10
11
12
var synonym = new Synonym
{
  ObjectID = "synonymID",
  Type = "oneWaySynonym",
  Input = "car",
  Synonyms = new List<string> { "vehicle", "auto" }
};

index.SaveSynonym(synonym, forwardToReplicas: true);

// Asynchronous
await index.SaveSynonymAsync(synonym, forwardToReplicas: true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
bool forwardToReplicas = true;

Synonym synonym = Synonym.createOneWaySynonym(
  "synonymID", "car", 
  Arrays.asList("vehicle", "auto"));
// or
Synonym synonym = new Synonym()
              .setObjectID("synonymID")
              .setType(SynonymType.ONE_WAY_SYNONYM)
              .setInput("car")
              .setSynonyms(Arrays.asList("vehicle", "auto"));

// Sync version
index.saveSynonym(synonym, forwardToReplicas);

// Async version 
index.saveSynonymAsync(synonym, forwardToReplicas);

1
2
3
4
5
6
7
8
forwardToReplicas := opt.ForwardToReplicas(true)
synonym := search.NewOneWaySynonym(
	"synonymID",
	"car",
	"vehicle",
	"auto",
)
res, err := index.SaveSynonym(synonym, forwardToReplicas)

Add or update an alternative correction 1 synonym

Copy

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

1
2
3
4
5
6
7
8
index.saveSynonym({
  objectID: 'synonymID',
  type: 'altCorrection1',
  word: 'car',
  corrections: ['vehicle', 'auto']
}, { forwardToReplicas: true }).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
index.save_synonym({
    'objectID': 'synonymID',
    'type': 'altCorrection1',
    'word': 'car',
    'corrections': [
        'vehicle',
        'auto'
    ]
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
9
10
let synonym: Synonym = .alternativeCorrection(objectID: "synonymID",
                                              word: "car",
                                              corrections: ["vehicle", "auto"],
                                              typo: .one)

index.saveSynonym(synonym, forwardToReplicas: true) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
val synonym = Synonym.AlternativeCorrections(
    objectID = ObjectID("synonymID"),
    corrections = listOf("vehicle", "auto"),
    typo = SynonymType.Typo.One,
    word = "car"
)

index.saveSynonym(synonym, forwardToReplicas = true)

1
2
3
4
5
6
7
8
9
10
11
12
var synonym = new Synonym
{
  ObjectID = "synonymID",
  Type = "altCorrection1",
  Input = "car",
  Synonyms = new List<string> { "vehicle", "auto" }
};

index.SaveSynonym(synonym, forwardToReplicas: true);

// Asynchronous
await index.SaveSynonymAsync(synonym, forwardToReplicas: true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
bool forwardToReplicas = true;

Synonym synonym = Synonym.createAltCorrection1(
  "synonymID", "car", 
  Arrays.asList("vehicle", "auto"));
// or
Synonym synonym = new Synonym()
              .setObjectID("synonymID")
              .setType(SynonymType.ALT_CORRECTION_1)
              .setWord("car")
              .setCorrections(Arrays.asList("vehicle", "auto"));

// Sync version
index.saveSynonym(synonym, forwardToReplicas);

// Async version 
index.saveSynonymAsync(synonym, forwardToReplicas);

1
2
3
4
5
6
7
8
forwardToReplicas := opt.ForwardToReplicas(true)
synonym := search.NewAltCorrection1(
  "synonymID",
  "car",
  "vehicle",
  "auto",
)
res, err := index.SaveSynonym(synonym, forwardToReplicas)

Add or update an alternative correction 2 synonym

Copy

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

1
2
3
4
5
6
7
8
index.saveSynonym({
  objectID: 'synonymID',
  type: 'altCorrection2',
  word: 'car',
  corrections: ['vehicle', 'auto']
}, { forwardToReplicas: true }).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
index.save_synonym({
    'objectID': 'synonymID',
    'type': 'altCorrection2',
    'word': 'car',
    'corrections': [
        'vehicle',
        'auto'
    ]
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
9
10
let synonym: Synonym = .alternativeCorrection(objectID: "synonymID",
                                              word: "car",
                                              corrections: ["vehicle", "auto"],
                                              typo: .two)

index.saveSynonym(synonym, forwardToReplicas: true) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
val synonym = Synonym.AlternativeCorrections(
    objectID = ObjectID("synonymID"),
    corrections = listOf("vehicle", "auto"),
    typo = SynonymType.Typo.One,
    word = "car"
)

index.saveSynonym(synonym, forwardToReplicas = true)

1
2
3
4
5
6
7
8
9
10
11
12
var synonym = new Synonym
{
  ObjectID = "synonymID",
  Type = "altCorrection2",
  Input = "car",
  Synonyms = new List<string> { "vehicle", "auto" }
};

index.SaveSynonym(synonym, forwardToReplicas: true);

// Asynchronous
await index.SaveSynonymAsync(synonym, forwardToReplicas: true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
bool forwardToReplicas = true;

Synonym synonym = Synonym.createAltCorrection2(
  "synonymID", "car", 
  Arrays.asList("vehicle", "auto"));
// or
Synonym synonym = new Synonym()
              .setObjectID("synonymID")
              .setType(SynonymType.ALT_CORRECTION_2)
              .setWord("car")
              .setCorrections(Arrays.asList("vehicle", "auto"));

// Sync version
index.saveSynonym(synonym, forwardToReplicas);

// Async version 
index.saveSynonymAsync(synonym, forwardToReplicas);

1
2
3
4
5
6
7
8
forwardToReplicas := opt.ForwardToReplicas(true)
synonym := search.NewAltCorrection2(
  "synonymID",
  "car",
  "vehicle",
  "auto",
)
res, err := index.SaveSynonym(synonym, forwardToReplicas)

Add or update a placeholder synonym

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

Copy
{
  "address": "589 Howard <Street>"
}

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

Copy

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

1
2
3
4
5
6
7
8
9
index.save_synonym({
  objectID: 'synonymID',
  type: 'placeholder',
  placeholder: '<Street>',
  replacements: [
    'street',
    'st'
  ]
}, { forwardToReplicas: true })

1
2
3
4
5
6
7
8
index.saveSynonym({
  objectID: 'synonymID',
  type: 'placeholder',
  placeholder: '<Street>',
  replacements: ['street', 'st']
}, { forwardToReplicas: true }).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
index.save_synonym({
    'objectID': 'synonymID',
    'type': 'placeholder',
    'placeholder': '<Street>',
    'replacements': [
        'street',
        'auto'
    ]
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
9
let synonym: Synonym = .placeholder(objectID: "synonymID",
                                    placeholder: "street",
                                    replacements: ["street", "st"])

index.saveSynonym(synonym, forwardToReplicas: true) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
val synonym = Synonym.Placeholder(
    objectID = ObjectID("synonymID"),
    placeholder = Synonym.Placeholder.Token("street"),
    replacements = listOf("street", "st")
)

index.saveSynonym(synonym, forwardToReplicas = true)

1
2
3
4
5
6
7
8
9
10
11
12
var synonym = new Synonym
{
  ObjectID = "synonymID",
  Type = "placeholder",
  Placeholder = "<Street>",
  Synonyms = new List<string> { "street", "st" }
};

index.SaveSynonym(synonym, forwardToReplicas: true);

// Asynchronous
await index.SaveSynonymAsync(synonym, forwardToReplicas: true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
bool forwardToReplicas = true;

Synonym synonym = Synonym.createPlaceHolder(
  "synonymID", "<Street>", 
  Arrays.asList("street", "st"));
// or
Synonym synonym = new Synonym()
              .setObjectID("synonymID")
              .setType(SynonymType.PLACEHOLDER)
              .setPlaceholder("<Street>")
              .setCorrections(Arrays.asList("street", "st")),

// Sync version
index.saveSynonym(synonym, forwardToReplicas);

// Async version 
index.saveSynonymAsync(synonym, forwardToReplicas);

1
2
3
4
5
6
7
8
forwardToReplicas := opt.ForwardToReplicas(true)
	synonym := search.NewPlaceholder(
		"synonymID",
		"<Street>",
		"street",
		"st",
	)
	res, err := index.SaveSynonym(synonym, forwardToReplicas)

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`	type: synonym object 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

Copy

          {
  "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?

Save synonym

About this method

Examples

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

Add or update a one way synonym

Add or update an alternative correction 1 synonym

Add or update an alternative correction 2 synonym

Add or update a placeholder synonym

Parameters

synonym ➔ synonym object

Response

JSON format

On this page