Api clients / Ruby / V1 / Methods

Jan. 09, 2023

Add Objects | Ruby API Client V1 (Deprecated)

This version of the Ruby API client has been deprecated in favor of the latest version of the Ruby API client.

Required API Key: any key with the addObject ACL

Method signature

index.add_objects(Array objects)
index.add_objects(Array objects, request_options=Hash)

# add a single object
index.add_object(Hash object)
index.add_object(Hash object, request_options=Hash)

See code examples

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.

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 is 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

Copy

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
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
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

Copy

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
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

Copy

1
2
3
4
5
6
7
$index->saveObject(
  [
    '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
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
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

Copy

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
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`	type: list of object Required A schemaless set of key/value pairs representing index attributes.
`requestOptions`	type: key/value mapping default: No request options Optional A list of request options to send along with the query.

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 does not 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.

JSON format

Add objects

Copy

          {
  "objectIDs": [
    "myObjectID1",
    "myObjectID2"
  ],
  "taskID": 678,
}

        

Add object

Copy

          {
  "objectID": "myObjectID1",
  "taskID": 678,
}

        

`objectIDs`	list List of objectIDs of the saved objects in order. This property is only returned when using add objects.
`objectID`	string The objectID of the saved object. This property is only returned when using add object.
`taskID`	integer The taskID used with the waitTask method.

Did you find this page helpful?

Add Objects | Ruby API Client V1 (Deprecated)

About this method

Examples

Add objects with automatic objectID assignments

Add objects with manual objectID assignments

Add a single object

Add objects and send extra HTTP headers

Parameters

objects ➔ object

Response

JSON format

Add objects

Add object

On this page

Add objects with automatic `objectID` assignments

Add objects with manual `objectID` assignments