API client / Methods / Indexing
Required API Key: any key with the addObject ACL
Method signature
$index->saveObjects(array objects);
$index->saveObjects(array objects, [
  // All the following parameters are optional
  'autoGenerateObjectIDIfNotExist' => boolean,
  'objectIDKey' => string
  // + any requestOptions
]);


// Update a single record
$index->saveObject(array object)
$index->saveObject(array object, [
  // All the following parameters are optional
  'autoGenerateObjectIDIfNotExist' => boolean,
  'objectIDKey' => string
  // + any requestOptions
]);

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

Adds or replaces records.

Adds records to an index or replaces them.

If a record doesn’t contain an objectID, Algolia automatically adds it. If you specify an existing objectID, it completely replaces all the attributes except for objectID.

To update only some attributes of an existing record, use partialUpdateObjects instead.

Limitations

To ensure good performance, saveObjects automatically sends batches of 1,000 records. If you’re indexing many records and have a stable, high-speed internet connection, increase the batch size to send more records per request and shorten your indexing time.

To ensure good performance, saveObjects automatically sends batches of 1,000 records. If you’re indexing many records and have a stable, high-speed internet connection, increase the batch size to send more records per request and shorten your indexing time.

To ensure good performance, saveObjects automatically sends batches of 1,000 records. If you’re indexing many records and have a stable, high-speed internet connection, increase the batch size to send more records per request and shorten your indexing time.

To ensure good performance, saveObjects automatically sends batches of 1,000 records. If you’re indexing many records and have a stable, high-speed internet connection, increase the batch size to send more records per request and shorten your indexing time.

To ensure good performance, saveObjects automatically sends batches of 1,000 records. If you’re indexing many records and have a stable, high-speed internet connection, increase the batch size to send more records per request and shorten your indexing time.

To ensure good performance, saveObjects automatically sends batches of 1,000 records. If you’re indexing many records and have a stable, high-speed internet connection, increase the batch size to send more records per request and shorten your indexing time.

When updating large numbers of records, be aware of the rate limitations on these processes and the impact on your analytics data.

Examples

Read the Algolia CLI documentation for more information.

Replace all attributes in existing records

1
2
3
4
5
6
7
8
9
10
11
12
13
14
$res = $index->saveObjects(
  [
    [
      'objectID'  => 'myID1',
      'firstname' => 'Jimmie',
      'lastname'  => 'Barninger'
    ],
    [
      'objectID'  => 'myID2',
      'firstname' => 'Warren',
      'lastname'  => 'Speach'
    ]
  ]
);

Replace all attributes in a single record

1
2
3
4
5
6
7
8
$index->saveObject(
  [
    'firstname' => 'Jimmie',
    'lastname'  => 'Barninger',
    'city'      => 'New York',
    'objectID'  => 'myID'
  ]
);

Replace all attributes in existing records and send extra HTTP headers

1
2
3
4
$objects = [/* objects */];
$index->saveObjects($objects, [
  'X-Forwarded-For' => '94.228.178.246'
]);

Increase the default batch size

1
2
3
4
5
6
7
$config = new SearchConfig([
    'appId' => 'YourApplicationID',
    'apiKey' => 'YourWriteAPIKey',
    'batchSize' => 999999,
]);

$client = SearchClient::createWithConfig($config);

Parameters

Parameter Description
objects
type: list of object
Required

A list of records to save.

autoGenerateObjectIDIfNotExist
type: boolean
default: false
Optional

saveObjects requires an objectID unless you set autoGenerateObjectIDIfNotExist to true.

  • If the objectID exists, Algolia replaces the record
  • If the objectID is present but doesn’t exist, Algolia creates the record
  • If the objectID isn’t specified and autoGenerateObjectID is false (the default), the engine returns an error.
  • If the objectID isn’t specified and autoGenerateObjectID is true, the engine generates an objectID and returns it in the response.

In the Ruby API client, this parameter is spelled: auto_generate_object_id_if_not_exist.

objectIDKey
type: string
Optional

The objectID is set from the value of the specified key.

Only available for PHP.

requestOptions
type: key-value mapping
default: No request options
Optional

A mapping of requestOptions to send along with the query. In addition to sending extra HTTP headers or setting timeouts, you can use requestOptions to set autoGenerateObjectIDIfNotExist.

objects ➔ object

An objectID must be specified for each record.

  • If the objectID exists, the record is replaced
  • If the objectID doesn’t exist, the engine will create a record
Parameter Description

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

Save records

1
2
3
4
5
6
7
{
  "objectIDs": [
    "myObjectID1",
    "myObjectID2"
  ],
  "taskID": 678,
}

Save record

1
2
3
4
{
  "objectID": "myObjectID1",
  "taskID": 678,
}
Field Description
objectIDs
list

List of objectIDs of the saved records in order. This property is only returned when using save objects.

objectID
string

The objectID of the saved record. This property is only returned when using save object.

taskID
integer

The taskID used with the waitTask method.

Did you find this page helpful?