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

Use this method to add new records (objects) to an index or replace existing records with an updated set of attributes.

This method redefines all of a record’s attributes (except its objectID). In other words, it fully replaces an existing record.

If there’s an error saving one of your records, none of them will be added to your index.

This method differs from partialUpdateObjects in a significant way:

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

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, you can 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, you can 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, you can 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, you can 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, you can 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, you can increase the batch size to send more records per request and shorten your indexing time.

When updating large numbers of records, or large records, be aware of the rate limit of 10,000 indexing operations per Unit (as applicable). 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.

This method also has a singular version.

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

Override 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

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

Response

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language or implementation, the actual type in your language might differ from what’s written here. You can view the response in the logs (using the getLogs method).

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,
}
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?