API Reference / API Methods / Indexing / 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 # A

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.

If the index targeted by this operation doesn’t exist yet, it’s automatically created.

When updating many or large objects, be aware of the 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#

To update an attribute without pushing the entire record, you can use these built-in operations. 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 made of numbers or strings
  • AddUnique: add a number or string element to an array attribute made of numbers or strings only if it’s not already present
  • IncrementFrom: increment a numeric integer attribute only if the provided value matches the current value, and otherwise ignore the whole object update. For example, if you pass an IncrementFrom value of 2 for the version attribute, but the current value of the attribute is 1, the engine ignores the update. If the object doesn’t exist, the engine only creates it if you pass an IncrementFrom value of 0.
  • IncrementSet : increment a numeric integer attribute only if the provided value is greater than the current value, and otherwise ignore the whole object update. For example, if you pass an IncrementSet value of 2 for the version attribute, and the current value of the attribute is 1, the engine updates the object. If the object doesn’t exist yet, the engine only creates it if you pass an IncrementSet value that’s greater than 0.

For Remove and AddUnique: the operation will be silently ignored if the array attribute has any nested object or array.

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

  • _operation: the operation to apply on the attribute
  • value: the right-hand side argument to the operation, for example, increment or decrement step, value to add or remove

Only the IncrementFrom and IncrementSet operations guarantee idempotent record updates. The other built-in operations aren’t idempotent and can cause unexpected side-effects, unless you use them in combination with the idempotent operations. 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 wrong data in your records.

Note: This method also has a singular version.

Examples # A

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

Update only if the value matches a numeric attribute#

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

Update only if the value is greater than a numeric attribute#

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

Parameters # A

objects #
type: list of object
Required

A list of objects to partially update.

objectID #
type: integer
Required

objectID to update.

createIfNotExists #
type: boolean
default: true (false for .NET, Java, Ruby, PHP and JavaScript)
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, JavaScript, Ruby, PHP and .NET default to false.

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. Note: Java, JavaScript, PHP and .NET default to false.

requestOptions #
type: key-value mapping
default: ""
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 and createIfNotExists, when using this method.

objects âž” object #

An object that matches some or all objects.

The object needs to contain an objectID.

If you supply an unknown objectID:

  • When <a href='#method-param-createifnotexists'>createIfNotExists</a> is true, the method creates a new record with the supplied objectID and attributes.
  • When <a href='#method-param-createifnotexists'>createIfNotExists</a> is false, the method ignores the new record (without sending back an error).

Response # A

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/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#

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?
PHP v3