API Reference / API Methods / Indexing / Partial update objects

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

You are currently reading the documentation of the JavaScript API Client v4. Read our migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

Update one or more attributes of an existing object.

This method lets you update only a part of an existing object, either by adding new attributes or updating existing ones.

You can partially update several objects in a single method call.

When updating many or large objects, be aware of our rate limit.

Specifying existing attributes updates them in the object, while specifying new attributes adds them. You need to use the saveObjects method to completely redefine an existing object, or replace an object with a different one.

You can’t individually update nested attributes. Specifying a nested attribute treats it as a replacement of its first-level ancestor. To change nested attributes, you need to use the saveObjects method. You can retrieve the object’s data by using the getObjects method.

Built-in operations

For convenience, we provide five different built-in operations to update an attribute without pushing its entire value. These operations can be helpful if you don’t have access to your initial data.

  • Increment: increment a numeric attribute
  • Decrement: decrement a numeric attribute
  • Add: append a number or string element to an array attribute
  • Remove: remove all matching number or string elements from an array attribute
  • AddUnique: add a number or string element to an array attribute only if it’s not already present

You can specify an operation by providing an object with two following properties:

  • _operation: the operation to apply on the attribute
  • value: the right-hand side argument to the operation (e.g., increment or decrement step, value to add or remove)

The built-in operations aren’t idempotent, and can trigger unexpected side-effects. For example, if you’re using the Increment or Decrement operations in a concurrent or multi-threaded environment, you may trigger it more than once and end up with incorrect data in your records.

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

Increment an existing numeric attribute

1
2
3
4
5
6
7
8
9
$index->partialUpdateObject(
  [
    'count'    => [
      '_operation' => 'Increment',
      'value'      => 2
    ],
    'objectID' => 'myID'
  ]
);

Add a new value to an existing array attribute

1
2
3
4
5
6
7
8
9
$index->partialUpdateObject(
  [
    '_tags'    => [
      '_operation' => 'AddUnique',
      'value'      => 'public'
    ],
    'objectID' => 'myID'
  ]
);

Parameters

objects
type: list of object
Required
objectID
type: integer
Required

objectID to update.

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?