Required API Key:
any key with the
addObject
ACL
About this method
Add new objects to an index.
This method allows you to create records on your index by sending one or more objects.
Each object contains a set of attributes and values,
which represents a full record on an index.
If the index targeted by this operation doesn’t exist yet, it’s automatically created.
There is no limit to the number of objects that can be passed, but a size limit of 1 GB on the total request. For performance
reasons, it’s recommended to push batches of ~10 MB of payload.
Batching records allows you to reduce the number of network calls required for multiple operations.
But note that each indexed object counts as a single indexing operation.
When adding 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
Add objects with automatic objectID assignments
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| $res = $index->saveObjects(
[
[
'firstname' => 'Jimmie',
'lastname' => 'Barninger'
],
[
'firstname' => 'Warren',
'lastname' => 'Speach'
]
],
[
'autoGenerateObjectIDIfNotExist' => true
]
);
|
1
2
3
4
5
6
7
| res = index.save_objects([{
firstname: 'Jimmie',
lastname: 'Barninger'
}, {
firstname: 'Warren',
lastname: 'Speach'
}], { autoGenerateObjectIDIfNotExist: true })
|
1
2
3
4
5
6
7
8
9
10
11
12
13
| const objects = [{
firstname: 'Jimmie',
lastname: 'Barninger'
}, {
firstname: 'Warren',
lastname: 'Speach'
}];
index
.saveObjects(objects, { autoGenerateObjectIDIfNotExist: true })
.then(({ objectIDs }) => {
console.log(objectIDs);
});
|
1
2
3
4
| res = index.save_objects([
{'firstname': 'Jimmie', 'lastname': 'Barninger'},
{'firstname': 'Warren', 'lastname': 'Speach'}
], {'autoGenerateObjectIDIfNotExist': True})
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| struct Contact: Encodable {
let firstname: String
let lastname: String
}
let contacts: [Contact] = [
.init(firstname: "Jimmie", lastname: "Barninger"),
.init(firstname: "Warren", lastname: "Speach"),
]
try index.saveObjects(contacts, autoGeneratingObjectID: true) { result in
if case .success(let response) = result {
print("Response: \(response)")
}
}
|
1
2
3
4
5
6
7
8
9
10
| List<JSONObject> array = new ArrayList<JSONObject>();
array.add(
new JSONObject().put("firstname", "Jimmie").put("lastname", "Barninger")
);
array.add(
new JSONObject().put("firstname", "Warren").put("lastname", "Speach")
);
index.addObjectsAsync(new JSONArray(array), null);
|
1
2
3
4
5
6
7
8
9
10
| List<Contact> contacts = new List<Contact>
{
new Contact { Firstname = "Jimmie", Lastname = "Barninger" },
new Contact { Firstname = "Warren", Lastname = "Speach" }
};
index.SaveObjects(contacts, autoGenerateObjectId: true);
// Asynchronous
await index.SaveObjectsAsync(contacts, autoGenerateObjectId: true);
|
1
2
3
4
5
6
7
8
9
| List<Contact> contacts = Arrays.asList(
new Contact().setFirstName("Jimmie").setLastName("Barninger"),
new Contact().setFirstName("Warren").setLastName("Speach"));
// Sync version
index.saveObjects(contacts, true);
// Async version
index.saveObjectsAsync(contacts, true);
|
1
2
3
4
5
6
7
8
9
10
11
| type Contact struct {
Firstname string `json:"firstname"`
Lastname string `json:"lastname"`
}
contacts := []Contact{
{Firstname: "Jimmie", Lastname: "Barninger"},
{Firstname: "Ray", Lastname: "Charles"},
}
res, err := index.SaveObjects(contacts, opt.AutoGenerateObjectIDIfNotExist(true))
|
1
2
3
4
5
6
| client.execute {
index into "index1" objects Seq(
Contact("Jimmie", "Barninger"),
Contact("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
| // With JsonObject
val json = listOf(
json {
"firstname" to "Jimmie"
"lastname" to "Barninger"
},
json {
"firstname" to "Warren"
"lastname" to "Speach"
}
)
index.saveObjects(json)
// With serializable class
@Serializable
data class Contact(val firstname: String, val lastname: String)
val contacts = listOf(
Contact("Jimmie", "Barninger"),
Contact("Warren", "Speach")
)
index.saveObjects(Contact.serializer(), contacts)
|
Add objects with manual objectID assignments
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| $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
| const objects = [{
objectID: 'myID1',
firstname: 'Jimmie',
lastname: 'Barninger'
}, {
objectID: 'myID2',
firstname: 'Warren',
lastname: 'Speach'
}];
index.saveObjects(objects).then(({ objectIDs }) => {
console.log(objectIDs);
});
|
1
2
3
4
| res = index.save_objects([
{"objectID": "myID1", "firstname": "Jimmie", "lastname": "Barninger"},
{"objectID": "myID2", "firstname": "Warren", "lastname": "Speach"}
])
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| struct Contact: Encodable {
let objectID: ObjectID
let firstname: String
let lastname: String
}
let contacts: [Contact] = [
.init(objectID: "myID1", firstname: "Jimmie", lastname: "Barninger"),
.init(objectID: "myID2", firstname: "Warren", lastname: "Speach"),
]
try index.saveObjects(contacts) { result in
if case .success(let response) = result {
print("Response: \(response)")
}
}
|
1
2
3
4
5
6
7
8
9
10
11
12
| List<JSONObject> array = new ArrayList<JSONObject>();
array.add(
new JSONObject().put("objectID", "myID1")
.put("firstname", "Jimmie").put("lastname", "Barninger")
);
array.add(
new JSONObject().put("objectID", "myID2")
.put("firstname", "Warren").put("lastname", "Speach")
);
index.addObjectsAsync(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
| 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);
// Async version
index.saveObjectsAsync(contacts);
|
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
29
30
| // With JsonObject
val json = listOf(
json {
"objectID" to ObjectID("myID1")
"firstname" to "Jimmie"
"lastname" to "Barninger"
},
json {
"objectID" to ObjectID("myID2")
"firstname" to "Warren"
"lastname" to "Speach"
}
)
index.saveObjects(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.saveObjects(Contact.serializer(), contacts)
|
Add a single object
1
2
3
4
5
6
7
| $index->saveObject(
[
'objectID' => 'myID',
'firstname' => 'Jimmie',
'lastname' => 'Barninger'
]
);
|
1
2
3
4
5
6
7
| res = index.save_object({
objectID: 'myID',
firstname: 'Jimmie',
lastname: 'Barninger'
})
puts 'ObjectID=' + res['objectID']
|
1
2
3
4
5
6
7
| index.saveObject({
objectID: 'myId',
firstname: 'Jimmie',
lastname: 'Barninger'
}).then(({ objectID }) => {
console.log(objectID);
});
|
1
2
3
4
5
| index.save_object({
'objectID': 'myID',
'firstname': 'Jimmie',
'lastname': 'Barninger'
})
|
1
2
3
4
5
6
7
8
9
10
11
12
13
| struct Contact: Encodable {
let objectID: ObjectID
let firstname: String
let lastname: String
}
let contact: Contact = .init(objectID: "myID1", firstname: "Jimmie", lastname: "Barninger")
try index.saveObject(contact) { result in
if case .success(let response) = result {
print("Response: \(response)")
}
}
|
1
2
3
4
5
| JSONObject object = new JSONObject()
.put("firstname", "Jimmie")
.put("lastname", "Barninger");
index.addObjectAsync(object, "myID", null);
|
1
2
3
4
5
6
| var contact = new Contact { ObjectID = "myID", Firstname = "Jimmie", Lastname = "Barninger" };
index.SaveObject(contact);
// Asynchronous
await index.SaveObjectAsync(contact);
|
1
2
3
4
5
6
7
8
9
10
| Contact contact = new Contact()
.setFirstName("Jimmie")
.setLastname("Barninger")
.setObjectID("objectID");
// Sync version
index.saveObject(contact);
// Async version
index.saveObjectAsync(contact);
|
1
2
3
4
5
6
7
8
9
10
11
12
13
| type Contact struct {
ObjectID string `json:"objectID"`
Firstname string `json:"firstname"`
Lastname string `json:"lastname"`
}
contact := Contact{
ObjectID: "myID",
Firstname: "Jimmie",
Lastname: "Barninger",
}
res, err := index.SaveObject(contact)
|
1
2
3
4
5
6
7
8
| client.execute {
index into "contacts" objectId "myID" `object` Contact(
"Jimmie",
"Barninger",
93,
"California Paint"
)
}
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| // With JsonObject
val json = json {
"firstname" to "Jimmie"
"lastname" to "Barninger"
"objectID" to "myID"
}
index.saveObject(json)
/// With serializable class
@Serializable
data class Contact(
val firstname: String,
val lastname: String,
override val objectID: ObjectID
) : Indexable
val contact = Contact("Jimmie", "Barninger", ObjectID("myID"))
index.saveObject(Contact.serializer(), contact)
|
Add objects and send extra HTTP headers
1
2
3
4
5
6
| $objects = [/* objects */];
$res = $index->saveObjects($objects, [
'autoGenerateObjectIDIfNotExist' => true,
'X-Forwarded-For' => '94.228.178.246'
]);
|
1
2
3
4
5
| res = index.add_objects(objects, {
headers: {
'X-Forwarded-For': '94.228.178.246'
}
})
|
1
2
3
4
5
6
7
8
| index.saveObjects(objects, {
autoGenerateObjectIDIfNotExist: true,
headers: {
'X-Forwarded-For': '94.228.178.246'
}
}).then(({ objectIDs }) => {
console.log(objectIDs);
});
|
1
2
3
4
5
6
7
| res = index.save_object(
{'objectIDfirstname': 'Jimmie', 'lastname': 'Barninger'},
{
'autoGenerateObjectIDIfNotExist': True,
'X-Forwarded-For': '94.228.178.246'
}
)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| struct Contact: Encodable {
let objectID: ObjectID
let firstname: String
let lastname: String
}
var requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"
let contacts: [Contact] = [
.init(objectID: "myID1", firstname: "Jimmie", lastname: "Barninger"),
.init(objectID: "myID2", firstname: "Warren", lastname: "Speach"),
]
try index.saveObjects(contacts, requestOptions: requestOptions) { result in
if case .success(let response) = result {
print("Response: \(response)")
}
}
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| List<JSONObject> array = new ArrayList<JSONObject>();
array.add(
new JSONObject().put("firstname", "Jimmie").put("lastname", "Barninger")
);
array.add(
new JSONObject().put("firstname", "Warren").put("lastname", "Speach")
);
index.addObjectsAsync(
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
| 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
| type Contact struct {
ObjectID string `json:"objectID"`
Firstname string `json:"firstname"`
Lastname string `json:"lastname"`
}
contacts := []Contact{
{Firstname: "Jimmie", Lastname: "Barninger"},
{Firstname: "Ray", Lastname: "Charles"},
}
res, err := index.SaveObjects(
contacts,
opt.ExtraHeaders(map[string]string{"X-Algolia-User-ID": "userID2"}),
)
|
1
2
3
4
5
6
7
8
| client.execute {
index into "index1" objects Seq(
Contact("Jimmie", "Barninger"),
Contact("Warren", "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
16
17
| val json = listOf(
json {
"objectID" to ObjectID("myID1")
"firstname" to "Jimmie"
"lastname" to "Barninger"
},
json {
"objectID" to ObjectID("myID2")
"firstname" to "Warren"
"lastname" to "Speach"
}
)
val requestOptions = requestOptions {
headerAlgoliaUserId(UserID("user123"))
}
index.saveObjects(json, requestOptions)
|
Parameters
objects
|
A schemaless set of key/value pairs representing index attributes.
|
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.
|
requestOptions
|
type: key/value mapping
default: No request options
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, when using this method.
|
objects âž”
object
The object is schemaless, so it can be any set of key/value pairs,
where each key is an attribute from your index.
Some attributes have special considerations:
The value you provide for objectIDs can be an integer or a string but will in any
case be converted to string by the engine.
You can create the ID yourself or Algolia will generate one.
Which means that you are not required to send an objectID.
- If you send an
objectID:
- If the
objectID doesn’t already exist in the index, the record will be created
- If the
objectID already exists, the record will be replaced
(same functionality as updating object)
- If you do not send an
objectID:
- Algolia will automatically create an
objectID that you will be able to
access in the response.
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.
Add objects
1
2
3
4
5
6
7
| {
"objectIDs": [
"myObjectID1",
"myObjectID2"
],
"taskID": 678,
}
|
Add 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 add objects.
|
objectID
|
The objectID of the saved object. This property is only returned when using add object.
|
taskID
|
The taskID used with the waitTask method.
|
