API Reference / API Methods / Synonyms / Save synonym

Nov. 12, 2020

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

This method is not available in mobile API clients.

Synonyms need to be configured via
the Algolia Dashboard or with one of our backend API clients.

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

About this method

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

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

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

Copy

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

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

1
2
3
4
5
6
7
index.save_synonym({
    'objectID': 'a-unique-identifier',
    'type': 'synonym',
    'synonyms': ['car', 'vehicle', 'auto']
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
let synonym: Synonym = .multiWay(objectID: "myID",
                                 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
7
8
9
10
11
var synonym = new Synonym
{
  ObjectID = "a-unique-identifier",
  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(
    "a-unique-identifier",
     Arrays.asList("car", "vehicle", "auto"));
// or
Synonym synonym = new Synonym()
              .setObjectID("a-unique-identifier")
              .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(
  "a-unique-identified",
  "car",
  "vehicle",
  "auto",
)
res, err := index.SaveSynonym(synonym, forwardToReplicas)

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

index.saveSynonym(synonym, forwardToReplicas = true)

Create/Update a one way synonym

Copy

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

1
2
3
4
5
6
index.save_synonym({
  objectID: 'a-unique-identifier',
  type: 'oneWaySynonym',
  input: 'car',
  synonyms: ['vehicle', 'auto']
}, { forwardToReplicas: true })

1
2
3
4
5
6
7
8
index.saveSynonym({
  objectID: 'a-unique-identifier',
  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': 'a-unique-identifier',
    'type': 'oneWaySynonym',
    'input': 'car',
    'synonyms': [
        'vehicle',
        'auto'
    ]
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
9
let synonym: Synonym = .oneWay(objectID: "myID",
                               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
8
9
10
11
12
var synonym = new Synonym
{
  ObjectID = "a-unique-identifier",
  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(
  "a-unique-identifier", "car", 
  Arrays.asList("vehicle", "auto"));
// or
Synonym synonym = new Synonym()
              .setObjectID("a-unique-identifier")
              .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(
	"a-unique-identified",
	"car",
	"vehicle",
	"auto",
)
res, err := index.SaveSynonym(synonym, forwardToReplicas)

1
2
3
4
5
6
7
client.execute {
  save synonym OneWaySynonym(
    "a-unique-identifier",
    "car",
    Seq("vehicle", "auto")
  ) inIndex "index_name" and forwardToReplicas
}

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

index.saveSynonym(synonym, forwardToReplicas = true)

Create/Update a alternative correction 1 synonym

Copy

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

1
2
3
4
5
6
index.save_synonym({
  objectID: 'a-unique-identifier',
  type: 'altCorrection1',
  word: 'car',
  corrections: ['vehicle', 'auto']
}, { forwardToReplicas: true })

1
2
3
4
5
6
7
8
index.saveSynonym({
  objectID: 'a-unique-identifier',
  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': 'a-unique-identifier',
    'type': 'altCorrection1',
    'word': 'car',
    'corrections': [
        'vehicle',
        'auto'
    ]
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
9
10
let synonym: Synonym = .alternativeCorrection(objectID: "myID",
                                              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
9
10
11
12
var synonym = new Synonym
{
  ObjectID = "a-unique-identifier",
  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(
  "a-unique-identifier", "car", 
  Arrays.asList("vehicle", "auto"));
// or
Synonym synonym = new Synonym()
              .setObjectID("a-unique-identifier")
              .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(
  "a-unique-identified",
  "car",
  "vehicle",
  "auto",
)
res, err := index.SaveSynonym(synonym, forwardToReplicas)

1
2
3
4
5
6
7
client.execute {
  save synonym AltCorrection1(
    "a-unique-identifier",
    "car",
    Seq("vehicle", "auto")
  ) inIndex "index_name" and forwardToReplicas
}

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

index.saveSynonym(synonym, forwardToReplicas = true)

Create/Update a alternative correction 2 synonym

Copy

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

1
2
3
4
5
6
index.save_synonym({
  objectID: 'a-unique-identifier',
  type: 'altCorrection2',
  word: 'car',
  corrections: ['vehicle', 'auto']
}, { forwardToReplicas: true })

1
2
3
4
5
6
7
8
index.saveSynonym({
  objectID: 'a-unique-identifier',
  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': 'a-unique-identifier',
    'type': 'altCorrection2',
    'word': 'car',
    'corrections': [
        'vehicle',
        'auto'
    ]
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
9
10
let synonym: Synonym = .alternativeCorrection(objectID: "myID",
                                              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
9
10
11
12
var synonym = new Synonym
{
  ObjectID = "a-unique-identifier",
  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(
  "a-unique-identifier", "car", 
  Arrays.asList("vehicle", "auto"));
// or
Synonym synonym = new Synonym()
              .setObjectID("a-unique-identifier")
              .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(
  "a-unique-identified",
  "car",
  "vehicle",
  "auto",
)
res, err := index.SaveSynonym(synonym, forwardToReplicas)

1
2
3
4
5
6
7
client.execute {
  save synonym AltCorrection2(
    "a-unique-identifier",
    "car",
    Seq("vehicle", "auto")
  ) inIndex "index_name" and forwardToReplicas
}

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

index.saveSynonym(synonym, forwardToReplicas = true)

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

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

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

1
2
3
4
5
6
7
8
index.saveSynonym({
  objectID: 'a-unique-identifier',
  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': 'a-unique-identifier',
    'type': 'placeholder',
    'placeholder': '<Street>',
    'replacements': [
        'street',
        'auto'
    ]
}, {
    'forwardToReplicas': True
})

1
2
3
4
5
6
7
8
9
let synonym: Synonym = .placeholder(objectID: "myID",
                                    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
8
9
10
11
12
var synonym = new Synonym
{
  ObjectID = "a-unique-identifier",
  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(
  "a-unique-identifier", "<Street>", 
  Arrays.asList("street", "st"));
// or
Synonym synonym = new Synonym()
              .setObjectID("a-unique-identifier")
              .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(
		"a-unique-identified",
		"<Street>",
		"street",
		"st",
	)
	res, err := index.SaveSynonym(synonym, forwardToReplicas)

1
2
3
4
5
6
7
client.execute {
  save synonym Placeholder(
    "a-unique-identifier",
    "<Street>",
    Seq("street", "st")
  ) inIndex "index_name" and forwardToReplicas
}

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

index.saveSynonym(synonym, 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

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

`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

Copy
{
  "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.

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

Save Synonym

About this method

Examples

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

Create/Update a one way synonym

Create/Update a alternative correction 1 synonym

Create/Update a alternative correction 2 synonym

Create/Update a placeholder synonym

Parameters

synonym ➔ synonym object

Response

JSON format

Did you find this page helpful?

On this page