API Reference / API Methods / Indexing / Save objects
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 object
$index->saveObject(array object)
$index->saveObject(array object, [
  // All the following parameters are optional
  'autoGenerateObjectIDIfNotExist' => boolean,
  'objectIDKey' => string
  // + any requestOptions
]);

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.

Replace an existing object with an updated set of attributes.

The save method is used to redefine the entire set of an object’s attributes (except its objectID). In other words, it fully replaces an existing object.

This method differs from partial update objects in a significant way:

  • With saveObjects, you define an object’s full set of attributes. Attributes not specified will no longer exist. For example, if an existing object contains the author attribute, but you don’t define it in your update call, it removes the author attribute from that object.
  • In contrast, when using partialUpdateObjects, you can single out one or more attributes and either create or update their content. If you don’t define an existing attribute in your update call, it doesn’t impact it.

To ensure good performance, saveObjects automatically splits your records into batches of 1,000 objects. If you’re indexing many records and have a stable, high-speed internet connection, you can set the default batch size to a higher value to send more records per request and shorten your indexing time.

Automatic batching is only available in the latest major versions of Algolia’s JavaScript, PHP, Go, C#, Java, and Python clients.

When updating large numbers of objects, or large sizes, be aware of the rate limit. You’ll know you’ve reached the rate limit when you start receiving errors on your indexing operations. To resolve rate limiting errors, you need to wait before sending any further indexing operations.

Saving objects is a single transactional operation. If there’s an error saving one of your objects, **none of the objects you passed will be saved to your index.**

This method also has a singular version.

Examples

Replace all attributes from existing objects

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 of a single object

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

Replace all attributes from existing objects and send extra HTTP headers

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

Override the default batch size

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

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

Parameters

objects
type: list of object
Required

A list of objects to save.

autoGenerateObjectIDIfNotExist
type: boolean
default: false
Optional

When false, if any of the objects doesn’t contain an objectID, the method throws an error. When true, if any of the objects doesn’t contain an objectID, the engine automatically assigns one.

objectIDKey
type: string
Optional

If specified, for each record, 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, when using this method.

objects ➔ object

An objectID needs to be specified for each object.

  • If the objectID exists, the record is replaced
  • If the objectID doesn’t exist, a record will be created

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

Save objects

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

Save object

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

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

objectID
string

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

taskID
integer

The taskID used with the waitTask method.

Did you find this page helpful?