Skip to main content
This page documents an earlier version of the API client. For the latest version, see Add or update attributes of multiple records.
Required ACL: addObject Use this method to add or update attributes of one or more records, without replacing the whole record.
  • If you provide an objectID that exists in your index, this method adds or updates the attributes of that record, without affecting the other attributes. To replace whole records, use the saveObjects method instead.
  • If you provide an objectID that doesn’t exist in your index, this method creates a new record unless the createIfNotExists parameter is false.
  • If you call this method on an index that doesn’t exist yet, this method creates a new index.
  • You can’t partially update nested attributes. If you specify a nested attribute, this method replaces the first-level ancestor. To update nested attributes, use the saveObjects method. To retrieve the record’s data, use the getObjects method.
When updating large numbers of records, be aware of the rate limitations on these processes and the impact on your analytics data.

​
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 attribute to update as the key and its value being 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.
To update a single record, use the partialUpdateObject method.

​
Examples

​
Partially update multiple records

List<Contact> contacts = new List<Contact>
{
    new Contact { ObjectID = "myID1", Firstname = "Jimmie" },
    new Contact { ObjectID = "myID2", Firstname = "Warren" }
};

index.PartialUpdateObjects(contacts);

// Asynchronous
await index.PartialUpdateObjectsAsync(contacts);

​
Partially update multiple records and send extra HTTP headers

List<Contact> contacts = new List<Contact>
{
    new Contact { ObjectID = "myID1", Firstname = "Jimmie" },
    new Contact { ObjectID = "myID2", Firstname = "Warren" }
};

RequestOptions requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-User-ID", "user123" } }
};

index.PartialUpdateObjects(contacts, requestOptions);

// Asynchronous
await index.PartialUpdateObjectsAsync(contacts, requestOptions);

​
Update one attribute of an existing record

This example updates only the city attribute of a single record 
var contact = new Contact { ObjectID = "myID", City = "San Francisco"" };

index.PartialUpdateObject(contact);

// Asynchronous
await index.PartialUpdateObjectAsync(contact);

​
Add a new attribute to an existing record

This example adds a state attribute to a single record. 
index.PartialUpdateObject(new Contact { ObjectID = "myID1", State = "California" });

// Asynchronous
await index.PartialUpdateObjectAsync(new Contact { ObjectID = "myID1", State = "California" });

​
Increment a numeric attribute

This example updates the count attribute and increments its value. 
class Record
{
    public string ObjectID { get; set; }

    public PartialUpdateOperation<int> Count { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Count = PartialUpdateOperation<int>.Increment(2),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

​
Add a new value to an existing array attribute

This example updates the _tags attribute and adds an item to the list. 
class Record
{
    public string ObjectID { get; set; }

    [JsonProperty(PropertyName = "_tags")]
    public PartialUpdateOperation<string> Tags { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Tags = PartialUpdateOperation<string>.AddUnique("public"),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

​
Update only if the value matches a numeric attribute

This example updates the version attribute using the IncrementFrom built-in operation. This ensures that this attribute is only incremented if the provided value matches. 
class Record
{
    public string ObjectID { get; set; }

    public PartialUpdateOperation<int> Count { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Count = PartialUpdateOperation<int>.IncrementFrom(2),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

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

This example updates the lastmodified attribute using the IncrementSet built-in operation to ensure that only the highest increment value is set. 
class Record
{
    public string ObjectID { get; set; }

    public PartialUpdateOperation<int> Count { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Count = PartialUpdateOperation<int>.IncrementSet(1593431913),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

​
Parameters

​
objects
object[]
required
List of records to update. (Required for partial_update_objects).
​
createIfNotExists
boolean
default:true
If true, updating a record with a non-existing objectID creates a new record with the specified attributes. If false (the objectID doesn’t exist), the update will be ignored. This means that no error will be returned, and the record won’t be updated.
In the Java, JavaScript, Ruby, Python, PHP, and .NET API clients, this parameter defaults to false.
​
requestOptions
object
A mapping of request options to send along with the query.

​
Response

​
objectIDs
list
List of object IDs of the records that should be updated.
​
taskID
integer
The task ID used with the waitTask method.

​
Response as JSON

This section shows the JSON response returned by the API. Each API client wraps this response in language-specific objects, so the structure may vary. To view the response, use the getLogs method. Don’t rely on the order of properties—JSON objects don’t preserve key order.
JSON
{
  "objectIDs": [
    "myObjectID1",
    "myObjectID2"
  ],
  "taskID": 678,
}
⌘I