API Reference / API Methods / Indexing / Partial update objects
Feb. 26, 2019

Partial Update Objects

Required API Key: any key with the addObject ACL
Method signature
$index->partialUpdateObjects(array objects)
$index->partialUpdateObjects(array objects, [
  'createIfNotExists' => createIfNotExists
  // + any requestOptions
])

// update a single object
$index->partialUpdateObject(array object)
$index->partialUpdateObject(array object, [
  'createIfNotExists' => bool
  // + any requestOptions
])

About this method

Update one or more attributes of an existing object.

This method enables you to update only a part of an object by singling out one or more attributes of an existing object and performing the following actions:

  • add new attributes
  • update the content of existing attributes

You can perform the above actions on multiple objects in a single method call.

Specifying existing attributes will update them in the object, while specifying new attributes will add them. You need to use the save objects method if you want to completely redefine an existing object, replace an object with a different one, or remove attributes. You cannot individually remove attributes.

Nested attributes cannot be individually updated. If you specify a nested attribute, it will be treated as a replacement of its first-level ancestor. To change nested attributes, you will need to use the save object method. You can initially get the object’s data either from your own data or by using the get object method.

The same can be said about array attributes: you cannot update individual elements of an array. If you have a record in which one attribute is an array, you will need to retrieve the record’s array, change the element(s) of the array, and then resend the full array using this method.

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

Partially update multiple objects using one API call

1
2
3
4
5
6
7
8
9
10
11
12
$index->partialUpdateObjects(
    [
        [
            'objectID'  => 'myID1',
            'firstname' => 'Jimmie'
        ],
        [
            'objectID'  => 'myID2',
            'firstname' => 'Warren'
        ]
    ]
);

Partially update multiple objects using one API call and send extra http headers

1
2
3
4
5
6
$objects = [/* objects */];

$res = $index->partialUpdateObjects($objects, [
  'createIfNotExists' => true,
  'X-Forwarded-For' => '94.228.178.246'
]);

Update only the city attribute of an existing object

1
2
3
4
5
6
$index->partialUpdateObject(
  [
    'city'     => 'San Francisco',
    'objectID' => 'myID'
  ]
);

Add a new state attribute to an existing object

1
2
3
4
5
6
$index->partialUpdateObject(
  [
    'state'    => 'California',
    'objectID' => 'myID'
  ]
);

Parameters

objects
type: list of object
Required
createIfNotExists
type: boolean
default: true (false for .NET and Java)
Optional

When true, a partial update on a nonexistent object will create the object (generating the objectID and using the attributes as defined in the object).

When false, a partial update on a nonexistent object will be ignored (but no error will be sent back).

Note: Java and .NET default to false.

requestOptions
type: key value mapping
default: ""
Optional

A mapping of request options to send along with the query.

objects ➔ object

An object that matches part or all of your index’s object.

The object needs to contain an objectID.

If you supply an unknown objectID:

  • When createIfNotExists is true, the method creates a new record with the supplied objectID and attributes.
  • if createIfNotExists is false, the method will be ignored (but no error will be sent back).

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

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

List of objectIDs of the objects to be updated.

taskID
integer

The taskID used with the waitTask method.

Did you find this page helpful?