This version of the JavaScript API client has been deprecated in favor of the latest version of the JavaScript API client.
Required API Key: any key with the addObject ACL
About this method
Replace an existing object with an updated set of attributes.
The save method is used to redefine the entire set of an object’s attributes
(except of course its objectID).
In other words, it fully replaces an existing object.
Saving objects has the same effect as the add objects
method if you specify objectIDs for every record.
This method differs from partial update objects
in a significant way:
- With
save objects you define an object’s full set of attributes.
Attributes not specified will no longer exist.
For example, if an existing object contains attribute X,
but X is not defined in a later update call,
attribute X will no longer exist for that object.
- In contrast, with
partial update objects you can single out one or more attributes,
and either remove them, add them, or update their content.
Additionally, attributes that already exist but are not specified in a partial update are not impacted.
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
Replace all attributes from existing objects
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| $res = $index->saveObjects(
[
[
'objectID' => 'myID1',
'firstname' => 'Jimmie',
'lastname' => 'Barninger'
],
[
'objectID' => 'myID2',
'firstname' => 'Warren',
'lastname' => 'Speach'
]
]
);
|
1
2
3
4
5
6
7
8
9
| res = index.save_objects([{
firstname: 'Jimmie',
lastname: 'Barninger',
objectID: 'myID1'
}, {
firstname: 'Warren',
lastname: 'Speach',
objectID: 'myID2'
}])
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| const objects = [{
firstname: 'Jimmie',
lastname: 'Barninger',
objectID: 'myID1'
}, {
firstname: 'Warren',
lastname: 'Speach',
objectID: 'myID2'
}];
index.saveObjects(objects, (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
2
3
4
| res = index.save_objects([
{'firstname': 'Jimmie', 'lastname': 'Barninger', 'objectID': 'myID1'},
{'firstname': 'Warren', 'lastname': 'Speach', 'objectID': 'myID2'}
])
|
1
2
3
4
5
6
7
| let obj1 = ["firstname": "Jimmie", "lastname": "Barninger", "objectID": "myID1"]
let obj2 = ["firstname": "Warren", "lastname": "Speach", "objectID": "myID2"]
index.saveObjects([obj1, obj2], 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("lastname", "Barninger")
.put("objectID", "myID")
);
array.add(
new JSONObject()
.put("firstname", "Warren")
.put("lastname", "Speach")
.put("objectID", "myID2")
);
index.saveObjectsAsync(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", Lastname = "Barninger" },
new Contact { ObjectID = "myID2", Firstname = "Warren", Lastname = "Speach" }
};
index.SaveObjects(contacts);
// Asynchronous
await index.SaveObjectsAsync(contacts);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
| // Sync version
index.saveObjects(Arrays.asList(
new Contact()
.setFirstName("Jimmie")
.setLastName("Barninger")
.setObjectID("myID"),
new Contact()
.setFirstName("Warren")
.setLastName("Speach")
.setObjectID("myID2")
));
// Async version
index.saveObjectsAsync(Arrays.asList(
new Contact()
.setFirstName("Jimmie")
.setLastName("Barninger")
.setObjectID("myID"),
new Contact()
.setFirstName("Warren")
.setLastName("Speach")
.setObjectID("myID2")
));
|
1
2
3
4
5
6
7
8
9
10
11
12
| type Contact struct {
ObjectID string `json:"objectID"`
Firstname string `json:"firstname"`
Lastname string `json:"lastname"`
}
contacts := []Contact{
{ObjectID: "myID1", Firstname: "Jimmie", Lastname: "Barninger"},
{ObjectID: "myID2", Firstname: "Ray", Lastname: "Charles"},
}
res, err := index.SaveObjects(contacts)
|
1
2
3
4
5
6
| client.execute {
index into "index1" objects Seq(
Contact("myID1", "Jimmie", "Barninger"),
Contact("myID2", "Warren", "Speach")
)
}
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
| // With JsonObject
val json = listOf(
ObjectID("myID1") to json {
"firstname" to "Jimmie"
"lastname" to "Barninger"
},
ObjectID("myID1") to json {
"firstname" to "Warren"
"lastname" to "Speach"
}
)
index.replaceObjects(json)
// With serializable class
@Serializable
data class Contact(
val firstname: String,
val lastname: String,
override val objectID: ObjectID
) : Indexable
val contacts = listOf(
Contact("Jimmie", "Barninger", ObjectID("myID")),
Contact("Jimmie", "Barninger", ObjectID("myID"))
)
index.replaceObjects(Contact.serializer(), contacts)
|
Replace all attributes of a single object
1
2
3
4
5
6
7
8
| $index->saveObject(
[
'firstname' => 'Jimmie',
'lastname' => 'Barninger',
'city' => 'New York',
'objectID' => 'myID'
]
);
|
1
2
3
4
5
6
| index.save_object({
firstname: 'Jimmie',
lastname: 'Barninger',
city: 'New York',
objectID: 'myID'
})
|
1
2
3
4
5
6
7
8
9
10
| index.saveObject({
firstname: 'Jimmie',
lastname: 'Barninger',
city: 'New York',
objectID: 'myID'
}, (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
2
3
4
5
6
| index.save_object({
'firstname': 'Jimmie',
'lastname': 'Barninger',
'city': 'New York',
'objectID': 'myID'}
)
|
1
2
3
4
5
6
7
| let newObject = [
"firstname": "Jimmie",
"lastname": "Barninger",
"city": "New York",
"objectID": "myID"
]
index.saveObject(newObject)
|
1
2
3
4
5
6
| JSONObject object = new JSONObject()
.put("firstname", "Jimmie")
.put("lastname", "Barninger")
.put("city", "New York");
index.saveObjectAsync(object, "myID", null);
|
1
2
3
4
| index.SaveObject(new Contact { ObjectID = "myID", Firstname = "Jimmie", Lastname = "Barninger", City = "New York" });
// Asynchronous
await index.SaveObjectAsync(new Contact { ObjectID = "myID", Firstname = "Jimmie", Lastname = "Barninger", City = "New York" });
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| // Sync version
index.saveObject(
new Contact()
.setFirstname("Jimmie")
.setLastname("Barninger")
.setCity("New York")
.setObjectID("myID")
);
// Async version
index.saveObjectAsync(
new Contact()
.setFirstname("Jimmie")
.setLastname("Barninger")
.setCity("New York")
.setObjectID("myID")
);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| type Contact struct {
ObjectID string `json:"objectID"`
Firstname string `json:"firstname"`
Lastname string `json:"lastname"`
City string `json:"city"`
}
contact := Contact{
ObjectID: "myID",
Firstname: "Jimmie",
Lastname: "Barninger",
City: "New York",
}
res, err := index.SaveObject(contact)
|
1
2
3
| client.execute {
index into "index1" `object` Contact("myID", "Jimmie", "Barninger")
}
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| // With JsonObject
val json = json {
"firstname" to "Jimmie"
"lastname" to "Barninger"
"city" to "New York"
}
index.replaceObject(ObjectID("myID"), json)
// With serializable class
@Serializable
data class Contact(
val firstname: String,
val lastname: String,
val city: String,
override val objectID: ObjectID
) : Indexable
val contact = Contact("Jimmie", "Barninger", "New York", ObjectID("myID"))
index.replaceObject(Contact.serializer(), contact)
|
Replace all attributes from existing objects and send extra HTTP headers
1
2
3
4
| $objects = [/* objects */];
$index->saveObjects($objects, [
'X-Forwarded-For' => '94.228.178.246'
]);
|
1
2
3
4
5
6
7
| objects = []
extra_headers = {
'X-Forwarded-For': '94.228.178.246'
}
res = index.save_objects(objects, nil, extra_headers)
|
1
2
3
4
5
6
7
8
9
10
11
| client.setExtraHeader('X-Forwarded-For', '94.228.178.246');
index.saveObjects([{
firstname: 'Jimmie',
lastname: 'Barninger',
city: 'New York',
objectID: 'myID'
}], (err, content) => {
if (err) throw err;
console.log(content);
});
|
1
2
3
4
5
6
| objects = [
# Objects
]
res = index.save_objects(objects, {
'X-Forwarded-For': '94.228.178.246'
})
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| let requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"
let obj1 = ["firstname": "Jimmie", "lastname": "Barninger", "objectID": "myID1"]
let obj2 = ["firstname": "Warren", "lastname": "Speach", "objectID": "myID2"]
index.saveObjects(
[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
16
17
18
19
| List<JSONObject> array = new ArrayList<JSONObject>();
array.add(
new JSONObject()
.put("firstname", "Jimmie")
.put("lastname", "Barninger")
.put("objectID", "myID")
);
array.add(
new JSONObject()
.put("firstname", "Warren")
.put("lastname", "Speach")
.put("objectID", "myID2")
);
index.saveObjectsAsync(
new JSONArray(array),
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", Lastname = "Barninger" },
new Contact { ObjectID = "myID2", Firstname = "Warren", Lastname = "Speach" }
};
RequestOptions requestOptions = new RequestOptions
{
Headers = new Dictionary<string,string>{ { "X-Algolia-User-ID", "user123" } }
};
index.SaveObjects(contacts, requestOptions);
// Asynchronous
await index.SaveObjectsAsync(contacts, requestOptions);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| List<Contact> contacts = Arrays.asList(
new Contact()
.setObjectID("MyID1")
.setFirstName("Jimmie")
.setLastName("Barninger"),
new Contact()
.setObjectID("MyID2")
.setFirstName("Warren")
.setLastName("Speach"));
// Sync version
index.saveObjects(
contacts,
new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);
// Async version
index.saveObjectsAsync(
contacts,
new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| type Contact struct {
ObjectID string `json:"objectID"`
Firstname string `json:"firstname"`
Lastname string `json:"lastname"`
}
contacts := []Contact{
{ObjectID: "myID1", Firstname: "Jimmie", Lastname: "Barninger"},
{ObjectID: "myID2", Firstname: "Ray", Lastname: "Charles"},
}
extraHeaders := opt.ExtraHeaders(map[string]string{
"X-Algolia-User-ID": "userID2",
})
res, err := index.SaveObjects(contacts, extraHeaders)
|
1
2
3
4
5
6
7
8
| client.execute {
index into "index1" 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
11
12
13
14
15
| val json = listOf(
ObjectID("myID1") to json {
"firstname" to "Jimmie"
"lastname" to "Barninger"
},
ObjectID("myID1") to json {
"firstname" to "Warren"
"lastname" to "Speach"
}
)
val requestOptions = requestOptions {
headerAlgoliaUserId(UserID("user123"))
}
index.replaceObjects(json, requestOptions)
|
Parameters
objects
|
|
autoGenerateObjectIDIfNotExist
|
If false, if any of the object do not contain an objectID, the method throws an error.
If true, if any of the object do not contain an objectID, the object is automatically assigned an objectID by the engine.
Only available for PHP.
|
objectIDKey
|
If specified, for each record, the objectID is set from the value of the specified key.
Only available for PHP.
|
requestOptions
|
type: key value mapping
default: No request options
Optional
A mapping of [`requestOptions`](/doc/api-client/getting-started/request-options/) to send along with the query.
|
objects ➔
object
An objectID needs to be specified for each object.
- If the
objectID exists, the record is replaced
- If the
objectID does not exist, a record will be created
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.
Save objects
1
2
3
4
5
6
7
| {
"objectIDs": [
"myObjectID1",
"myObjectID2"
],
"taskID": 678,
}
|
Save object
1
2
3
4
| {
"objectID": "myObjectID1",
"taskID": 678,
}
|
objectIDs
|
List of objectIDs of the saved objects in order. This property is only returned when using save objects.
|
objectID
|
The objectID of the saved object. This property is only returned when using save object.
|
taskID
|
The taskID used with the waitTask method.
|
