API Reference / API Methods / Indexing / Save objects
Feb. 26, 2019

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

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 of course its objectID). In other words, it fully replaces an existing object.

Saving objects has the same effect as the add objects method if you specify objectIDs for every record.

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

  • With save objects you define an object’s full set of attributes. Attributes not specified will no longer exist. For example, if an existing object contains attribute X, but X is not defined in a later update call, attribute X will no longer exist for that object.
  • In contrast, with partial update objects you can single out one or more attributes, and either remove them, add them, or update their content. Additionally, attributes that already exist but are not specified in a partial update are not impacted.

When updating large numbers of objects, or large sizes, be aware of our rate limit. You’ll know you’ve reached the rate limit when you start receiving errors on your indexing operations. This can only be resolved if you wait before sending any further indexing operations.

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

Parameters

objects
type: list of object
Required
autoGenerateObjectIDIfNotExist
type: boolean
Optional

If false, if any of the object do not contain an objectID, the method throws an error. If true, if any of the object do not contain an objectID, the object is automatically assigned an objectID by the engine.

Only available for PHP.

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 request options to send along with the query.

objects âž” object

An objectID needs to be specified for each object.

  • If the objectID exists, the record is replaced
  • If the objectID does not 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?