Required API Key:
any key with the
addObject
ACL
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'
]
]
);
|
1
2
3
4
5
6
7
| index.partial_update_objects([{
firstname: 'Jimmie',
objectID: 'myID'
}, {
firstname: 'Warren',
objectID: 'myID2'
}])
|
1
2
3
4
5
6
7
8
9
10
11
12
13
| const objects = [{
firstname: 'Jimmie',
objectID: 'myID1'
}, {
firstname: 'Warren',
objectID: 'myID2'
}];
index.partialUpdateObjects(objects, (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
2
3
4
| index.partial_update_objects([
{'objectID': 'myID1', 'firstname': 'Jimmie'},
{'objectID': 'myID2', 'firstname': 'Warren'}
])
|
1
2
3
4
5
6
7
8
9
10
11
| let obj1 = ["firstname": "Jimmie", "objectID": "myID1"]
let obj2 = ["firstname": "Warren", "objectID": "myID2"]
index.partialUpdateObjects(
[obj1, obj2],
completionHandler: { (content, error) -> Void in
if error == nil {
print("Object IDs: \(content!)")
}
}
)
|
1
2
3
4
5
6
7
8
9
10
| List<JSONObject> array = new ArrayList<JSONObject>();
array.add(
new JSONObject().put("firstname", "Jimmie").put("objectID", "myID")
);
array.add(
new JSONObject().put("firstname", "Warren").put("objectID", "myID2")
);
index.partialUpdateObjectsAsync(new JSONArray(array), null);
|
1
2
3
4
5
6
7
8
9
10
| 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);
|
1
2
3
4
5
6
7
8
9
10
| List<Contact> contacts = Arrays.asList(
new Contact().setCity("San Francisco").setObjectID("MyID"),
new Contact().setCity("Paris").setObjectID("MyID2")
);
// Sync version
index.partialUpdateObjects(contacts);
// Async version
index.partialUpdateObjectsAsync(contacts);
|
1
2
3
4
5
6
| objects := []map[string]string{
{"objectID": "myID1", "lastname": "Barninger"},
{"objectID": "myID2", "firstname": "Ray"},
}
res, err := index.PartialUpdateObjects(objects)
|
1
2
3
4
5
6
| client.execute {
partialUpdate from "index" objects Seq(
Contact("myID", "Jimmie", "Barninger"),
Contact("myID", "Speach")
)
}
|
1
2
3
4
5
6
7
| val firstname = Attribute("firstname")
val partials = listOf(
ObjectID("myID1") to Partial.Update(firstname, "Jimmie"),
ObjectID("myID2") to Partial.Update(firstname, "Warren")
)
index.partialUpdateObjects(partials)
|
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'
]);
|
1
2
3
4
5
6
7
8
9
| objects = []
create_if_not_exits = true
extra_headers = {
'X-Forwarded-For': '94.228.178.246'
}
res = index.partial_update_objects(objects, create_if_not_exits, extra_headers)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| const objects = [{
firstname: 'Jimmie',
objectID: 'myID1'
}, {
firstname: 'Warren',
objectID: 'myID2'
}];
client.setExtraHeader('X-Forwarded-For', '94.228.178.246');
index.partialUpdateObjects(objects, (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
2
3
4
| objects = [
# Objects
]
index.partial_update_objects(objects, {'X-Forwarded-For': '94.228.178.246'})
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| let requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"
let obj1 = ["firstname": "Jimmie", "objectID": "myID1"]
let obj2 = ["firstname": "Warren", "objectID": "myID2"]
index.partialUpdateObjects(
[obj1, obj2],
requestOptions: requestOptions,
completionHandler: { (content, error) -> Void in
if error == nil {
print("Object IDs: \(content!)")
}
}
)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| List<JSONObject> array = new ArrayList<JSONObject>();
array.add(
new JSONObject().put("firstname", "Jimmie").put("objectID", "myID")
);
array.add(
new JSONObject().put("firstname", "Warren").put("objectID", "myID2")
);
index.partialUpdateObjectsAsync(
new JSONArray(array),
true,
new RequestOptions()
.setHeader("X-Algolia-User-ID", "94.228.178.246"),
null
);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| 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);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
| List<Contact> contacts = Arrays.asList(
new Contact().setCity("San Francisco").setObjectID("MyID"),
new Contact().setCity("Paris").setObjectID("MyID2")
);
RequestOptions requestOptions =
new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
// Sync version
index.partialUpdateObjects(contacts, requestOptions);
// Async version
index.partialUpdateObjectsAsync(contacts, requestOptions);
|
1
2
3
4
5
6
7
8
9
10
| objects := []map[string]string{
{"objectID": "myID1", "lastname": "Barninger"},
{"objectID": "myID2", "firstname": "Ray"},
}
extraHeaders := opt.ExtraHeaders(map[string]string{
"X-Algolia-User-ID": "userID2",
})
res, err := index.PartialUpdateObjects(objects, extraHeaders)
|
1
2
3
4
5
6
7
8
9
10
| client.execute {
client.execute {
partialUpdate from "index" objects Seq(
Contact("myID", "Jimmie", "Barninger"),
Contact("myID", "Speach")
) options RequestOptions(
extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
)
}
}
|
1
2
3
4
5
6
7
8
9
10
| val firstname = Attribute("firstname")
val partials = listOf(
ObjectID("myID1") to Partial.Update(firstname, "Jimmie"),
ObjectID("myID2") to Partial.Update(firstname, "Warren")
)
val requestOptions = requestOptions {
headerAlgoliaUserId(UserID("user123"))
}
index.partialUpdateObjects(partials, requestOptions = requestOptions)
|
Update only the city attribute of an existing object
1
2
3
4
5
6
| $index->partialUpdateObject(
[
'city' => 'San Francisco',
'objectID' => 'myID'
]
);
|
1
2
3
4
| index.partial_update_object({
city: 'San Francisco',
objectID: 'myID'
})
|
1
2
3
4
5
6
7
8
| index.partialUpdateObject({
city: 'San Francisco',
objectID: 'myID'
}, (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
| index.partial_update_object({"objectID": "myID", "city": "San Francisco"})
|
1
2
| let partialObject = ["city": "San Francisco"]
index.partialUpdateObject(partialObject, withID: "myID")
|
1
2
3
4
5
| index.partialUpdateObjectAsync(
new JSONObject("{\"city\": \"San Francisco\"}"),
"myID",
null
);
|
1
2
3
4
5
6
| var contact = new Contact { ObjectID = "myID", City = "San Francisco"" };
index.PartialUpdateObject(contact);
// Asynchronous
await index.PartialUpdateObjectAsync(contact);
|
1
2
3
4
5
6
7
| Contact contact = new Contact().setObjectID("myID").setCity("San Francisco");
// Sync version
index.partialUpdateObject(contact);
// Sync version
index.partialUpdateObjectAsync(contact);
|
1
2
3
4
5
6
7
8
9
10
11
| type Contact struct {
ObjectID string `json:"objectID"`
City string `json:"city"`
}
contact := Contact{
ObjectID: "myID",
City: "San Francisco",
}
res, err := index.PartialUpdateObject(contact)
|
1
2
3
4
5
6
| client.execute {
partialUpdate from "index" `object` Contact(
objectID = "myID",
city = "San Francisco"
)
}
|
1
2
3
| val partial = Partial.Update(Attribute("city"), "San Francisco")
index.partialUpdateObject(ObjectID("myID"), partial)
|
Add a new state attribute to an existing object
1
2
3
4
5
6
| $index->partialUpdateObject(
[
'state' => 'California',
'objectID' => 'myID'
]
);
|
1
2
3
4
| index.partial_update_object({
state: 'California',
objectID: 'myID'
})
|
1
2
3
4
5
6
7
8
| index.partialUpdateObject({
state: 'California',
objectID: 'myID'
}, (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
| index.partial_update_object({'objectID': 'myID', 'state': 'California'})
|
1
2
| let partialObject = ["state": "California"]
index.partialUpdateObject(partialObject, withID: "myID")
|
1
2
3
4
5
| index.partialUpdateObjectAsync(
new JSONObject("{\"state\": \"California\"}"),
"myID",
null
);
|
1
2
3
4
| index.PartialUpdateObject(new Contact { ObjectID = "myID1", State = "California" });
// Asynchronous
await index.PartialUpdateObjectAsync(new Contact { ObjectID = "myID1", State = "California" });
|
1
2
3
4
5
6
7
| Contact contact = new Contact().setObjectID("myID").setState("California");
// Sync version
index.partialUpdateObject(contact);
// Sync version
index.partialUpdateObjectAsync(contact);
|
1
2
3
4
5
6
7
8
9
10
11
| type Contact struct {
ObjectID string `json:"objectID"`
State string `json:"state"`
}
contact := Contact{
ObjectID: "myID",
State: "California",
}
res, err := index.PartialUpdateObject(contact)
|
1
2
3
4
5
6
| client.execute {
partialUpdate from "index" `object` Contact(
objectID = "myID",
state = "California"
)
}
|
1
2
3
| val partial = Partial.Update(Attribute("state"), "California")
index.partialUpdateObject(ObjectID("myID"), partial)
|
1
| index.partialUpdateObject(new JSONObject().put("state", "California"), "myID");
|
Parameters
objects
|
|
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.
1
2
3
4
5
6
7
| {
"objectIDs": [
"myObjectID1",
"myObjectID2"
],
"taskID": 678,
}
|
objectIDs
|
List of objectIDs of the objects to be updated.
|
taskID
|
The taskID used with the waitTask method.
|
