> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Save synonym

> Add a synonym to an index or replace it.

export const Legacy = ({title, href}) => {
  return <Note>

    This page documents an earlier version of the API client.
    For the latest version, see <a href={href}>{title}</a>.

    </Note>;
};

<Legacy title="Create or replace a synonym" href="/doc/libraries/sdk/methods/search/save-synonym" />

**Required ACL:** `editSettings`

You need to provide a unique `objectID` for the synonym you want to add or replace:

* `objectID` isn't a reference to an Algolia record: it's a unique identifier of a synonym object.
* If a synonym with the provided `objectID` exists, the synonym is replaced,
  otherwise a new synonym is added.

For more information, see [Synonyms](/doc/guides/managing-results/optimize-search-results/adding-synonyms).

To add multiple synonyms in a single API request,
use the [`saveSynonyms`](/doc/libraries/sdk/v1/methods/save-synonyms) method.

## Examples

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

<CodeGroup>
  ```cs C# theme={"system"}
  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);
  ```

  ```go Go theme={"system"}
  forwardToReplicas := opt.ForwardToReplicas(true)
  synonym := search.NewRegularSynonym(
    "synonymID",
    "car",
    "vehicle",
    "auto",
  )
  res, err := index.SaveSynonym(synonym, forwardToReplicas)
  ```

  ```java Java theme={"system"}
  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);
  ```

  ```js JavaScript theme={"system"}
  index.saveSynonym({
    objectID: 'synonymID',
    type: 'synonym',
    synonyms: ['car', 'vehicle', 'auto']
  }, { forwardToReplicas: true }).then(() => {
    // done
  });
  ```

  ```kotlin Kotlin theme={"system"}
  val synonym = Synonym.MultiWay(
      objectID = ObjectID("synonymID"),
      synonyms = listOf("car", "vehicle", "auto")
  )

  index.saveSynonym(synonym, forwardToReplicas = true)
  ```

  ```php PHP theme={"system"}
  $index->saveSynonym([
    'objectID' => 'synonymID',
    'type' => 'synonym',
    'synonyms' => [
      'car',
      'vehicle',
      'auto'
    ]
  ], [
    'forwardToReplicas' => true
  ]);
  ```

  ```python Python theme={"system"}
  index.save_synonym({
      'objectID': 'synonymID',
      'type': 'synonym',
      'synonyms': ['car', 'vehicle', 'auto']
  }, {
      'forwardToReplicas': True
  })
  ```

  ```ruby Ruby theme={"system"}
  index.save_synonym({
    objectID: 'synonymID',
    type: 'synonym',
    synonyms: ['car', 'vehicle', 'auto']
  }, { forwardToReplicas: true })
  ```

  ```scala Scala theme={"system"}
  client.execute {
    save synonym Synonym(
      "synonymID",
      Seq("car", "vehicle", "auto")
    ) inIndex "index_name" and forwardToReplicas
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

### Add or update a one way synonym

<CodeGroup>
  ```cs C# theme={"system"}
  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);
  ```

  ```go Go theme={"system"}
  forwardToReplicas := opt.ForwardToReplicas(true)
  synonym := search.NewOneWaySynonym(
  	"synonymID",
  	"car",
  	"vehicle",
  	"auto",
  )
  res, err := index.SaveSynonym(synonym, forwardToReplicas)
  ```

  ```java Java theme={"system"}
  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);
  ```

  ```js JavaScript theme={"system"}
  index.saveSynonym({
    objectID: 'synonymID',
    type: 'oneWaySynonym',
    input: 'car',
    synonyms: ['vehicle', 'auto']
  }, { forwardToReplicas: true }).then(() => {
    // done
  });
  ```

  ```kotlin Kotlin theme={"system"}
  val synonym = Synonym.OneWay(
      objectID = ObjectID("synonymID"),
      input = "car",
      synonyms = listOf("vehicle", "auto")
  )

  index.saveSynonym(synonym, forwardToReplicas = true)
  ```

  ```php PHP theme={"system"}
  $index->saveSynonym([
    'objectID' => 'synonymID',
    'type' => 'oneWaySynonym',
    'input' => 'car',
    'synonyms' => [
      'vehicle',
      'auto'
    ], [
      'forwardToReplicas' => true
    ]);
  ```

  ```python Python theme={"system"}
  index.save_synonym({
      'objectID': 'synonymID',
      'type': 'oneWaySynonym',
      'input': 'car',
      'synonyms': [
          'vehicle',
          'auto'
      ]
  }, {
      'forwardToReplicas': True
  })
  ```

  ```ruby Ruby theme={"system"}
  index.save_synonym({
    objectID: 'synonymID',
    type: 'oneWaySynonym',
    input: 'car',
    synonyms: ['vehicle', 'auto']
  }, { forwardToReplicas: true })
  ```

  ```scala Scala theme={"system"}
  client.execute {
    save synonym OneWaySynonym(
      "synonymID",
      "car",
      Seq("vehicle", "auto")
    ) inIndex "index_name" and forwardToReplicas
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

### Add or update an alternative correction 1 synonym

<CodeGroup>
  ```cs C# theme={"system"}
  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);
  ```

  ```go Go theme={"system"}
  forwardToReplicas := opt.ForwardToReplicas(true)
  synonym := search.NewAltCorrection1(
    "synonymID",
    "car",
    "vehicle",
    "auto",
  )
  res, err := index.SaveSynonym(synonym, forwardToReplicas)
  ```

  ```java Java theme={"system"}
  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);
  ```

  ```js JavaScript theme={"system"}
  index.saveSynonym({
    objectID: 'synonymID',
    type: 'altCorrection1',
    word: 'car',
    corrections: ['vehicle', 'auto']
  }, { forwardToReplicas: true }).then(() => {
    // done
  });
  ```

  ```kotlin Kotlin theme={"system"}
  val synonym = Synonym.AlternativeCorrections(
      objectID = ObjectID("synonymID"),
      corrections = listOf("vehicle", "auto"),
      typo = SynonymType.Typo.One,
      word = "car"
  )

  index.saveSynonym(synonym, forwardToReplicas = true)
  ```

  ```php PHP theme={"system"}
  $index->saveSynonym([
    'objectID' => 'synonymID',
    'type' => 'altCorrection1',
    'word' => 'car',
    'corrections' => [
      'vehicle',
      'auto'
    ]
  ], [
    'forwardToReplicas' => true
  ]);
  ```

  ```python Python theme={"system"}
  index.save_synonym({
      'objectID': 'synonymID',
      'type': 'altCorrection1',
      'word': 'car',
      'corrections': [
          'vehicle',
          'auto'
      ]
  }, {
      'forwardToReplicas': True
  })
  ```

  ```ruby Ruby theme={"system"}
  index.save_synonym({
    objectID: 'synonymID',
    type: 'altCorrection1',
    word: 'car',
    corrections: ['vehicle', 'auto']
  }, { forwardToReplicas: true })
  ```

  ```scala Scala theme={"system"}
  client.execute {
    save synonym AltCorrection1(
      "synonymID",
      "car",
      Seq("vehicle", "auto")
    ) inIndex "index_name" and forwardToReplicas
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

### Add or update an alternative correction 2 synonym

<CodeGroup>
  ```cs C# theme={"system"}
  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);
  ```

  ```go Go theme={"system"}
  forwardToReplicas := opt.ForwardToReplicas(true)
  synonym := search.NewAltCorrection2(
    "synonymID",
    "car",
    "vehicle",
    "auto",
  )
  res, err := index.SaveSynonym(synonym, forwardToReplicas)
  ```

  ```java Java theme={"system"}
  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);
  ```

  ```js JavaScript theme={"system"}
  index.saveSynonym({
    objectID: 'synonymID',
    type: 'altCorrection2',
    word: 'car',
    corrections: ['vehicle', 'auto']
  }, { forwardToReplicas: true }).then(() => {
    // done
  });
  ```

  ```kotlin Kotlin theme={"system"}
  val synonym = Synonym.AlternativeCorrections(
      objectID = ObjectID("synonymID"),
      corrections = listOf("vehicle", "auto"),
      typo = SynonymType.Typo.One,
      word = "car"
  )

  index.saveSynonym(synonym, forwardToReplicas = true)
  ```

  ```php PHP theme={"system"}
  $index->saveSynonym([
    'objectID' => 'synonymID',
    'type' => 'altCorrection2',
    'word' => 'car',
    'corrections' => [
      'vehicle',
      'auto'
    ]
  ], [
    'forwardToReplicas' => true
  ]);
  ```

  ```python Python theme={"system"}
  index.save_synonym({
      'objectID': 'synonymID',
      'type': 'altCorrection2',
      'word': 'car',
      'corrections': [
          'vehicle',
          'auto'
      ]
  }, {
      'forwardToReplicas': True
  })
  ```

  ```ruby Ruby theme={"system"}
  index.save_synonym({
    objectID: 'synonymID',
    type: 'altCorrection2',
    word: 'car',
    corrections: ['vehicle', 'auto']
  }, { forwardToReplicas: true })
  ```

  ```scala Scala theme={"system"}
  client.execute {
    save synonym AltCorrection2(
      "synonymID",
      "car",
      Seq("vehicle", "auto")
    ) inIndex "index_name" and forwardToReplicas
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

### Add or update a placeholder synonym

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

```json theme={"system"}
{
  "address": "589 Howard <Street>"
}
```

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

<CodeGroup>
  ```cs C# theme={"system"}
  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);
  ```

  ```go Go theme={"system"}
  forwardToReplicas := opt.ForwardToReplicas(true)
  	synonym := search.NewPlaceholder(
  		"synonymID",
  		"<Street>",
  		"street",
  		"st",
  	)
  	res, err := index.SaveSynonym(synonym, forwardToReplicas)
  ```

  ```java Java theme={"system"}
  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);
  ```

  ```js JavaScript theme={"system"}
  index.saveSynonym({
    objectID: 'synonymID',
    type: 'placeholder',
    placeholder: '<Street>',
    replacements: ['street', 'st']
  }, { forwardToReplicas: true }).then(() => {
    // done
  });
  ```

  ```kotlin Kotlin theme={"system"}
  val synonym = Synonym.Placeholder(
      objectID = ObjectID("synonymID"),
      placeholder = Synonym.Placeholder.Token("street"),
      replacements = listOf("street", "st")
  )

  index.saveSynonym(synonym, forwardToReplicas = true)
  ```

  ```php PHP theme={"system"}
  $index->saveSynonym([
    'objectID' => 'synonymID',
    'type' => 'placeholder',
    'placeholder' => '<Street>',
    'replacements' => [
      'street',
      'st'
    ]
  ], [
    'forwardToReplicas' => true
  ]);
  ```

  ```python Python theme={"system"}
  index.save_synonym({
      'objectID': 'synonymID',
      'type': 'placeholder',
      'placeholder': '<Street>',
      'replacements': [
          'street',
          'auto'
      ]
  }, {
      'forwardToReplicas': True
  })
  ```

  ```ruby Ruby theme={"system"}
  index.save_synonym({
    objectID: 'synonymID',
    type: 'placeholder',
    placeholder: '<Street>',
    replacements: [
      'street',
      'st'
    ]
  }, { forwardToReplicas: true })
  ```

  ```scala Scala theme={"system"}
  client.execute {
    save synonym Placeholder(
      "synonymID",
      "<Street>",
      Seq("street", "st")
    ) inIndex "index_name" and forwardToReplicas
  }
  ```

  ```swift Swift theme={"system"}
  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)")
    }
  }
  ```
</CodeGroup>

## Parameters

<ParamField body="synonym" type="object" required>
  A synonym object.

  <Expandable>
    <ParamField body="type" type="string" required>
      The synonym type can be one of the following values:

      * `altCorrection1`
      * `altCorrection2`
      * `oneWaySynonym`
      * `placeholder`
      * `synonym`
    </ParamField>

    <ParamField body="corrections" type="string[]">
      List of corrections.
      Required for synonym types `altCorrection1` or `altCorrection2`.
    </ParamField>

    <ParamField body="input" type="string">
      A word or expression, used as the basis for synonyms.
      Required for synonym type `oneWaySynonym`.
    </ParamField>

    <ParamField body="objectID" type="string">
      Must contain the same value as the `objectId` above.
      Only required in some programming languages.
    </ParamField>

    <ParamField body="placeholder" type="string">
      A single word, used as the basis for replacements.
      Required for synonym type `placeholder`.
    </ParamField>

    <ParamField body="replacements" type="string[]">
      List of replacements for the placeholder.
      Required for synonym type `placeholder`.
    </ParamField>

    <ParamField body="synonyms" type="string[]">
      List of synonyms (up to 20 for type `synonym` and 100 for type `oneWaySynonym`).
      Required for synonym types `synonym` or `oneWaySynonym`.
    </ParamField>

    <ParamField body="word" type="string">
      A single word, used as the basis for corrections.
      Required for synonym types `altCorrection1` or `altCorrection2`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="forwardToReplicas" type="boolean" default={false}>
  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.
</ParamField>

## Response

<ResponseField name="id" type="string">
  objectID of the inserted object.
</ResponseField>

<ResponseField name="taskID" type="integer">
  The task ID used with the [`waitTask`](/doc/libraries/sdk/v1/methods/wait-task) method.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Date at which the indexing job has been created.
</ResponseField>

### Response as JSON

This section shows the JSON response returned by the API.
Each API client wraps this response in language-specific objects, so the structure may vary.
To view the response, use the `getLogs` method.
Don't rely on the order of properties—JSON objects don't preserve key order.

```jsonc JSON icon=braces theme={"system"}
{
  "updatedAt":"2013-01-18T15:33:13.556Z",
  "taskID": 678,
  "id": "6891"
}
```