Algolia DevCon
Oct. 2–3 2024, virtual.
Api clients / JavaScript / V3 / Methods

Add Objects | JavaScript API Client V3 (Deprecated)

Deprecated content
This documentation is for a deprecated version of JavaScript API client. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of JavaScript API client for up-to-date information.
Required API Key: any key with the addObject ACL
Method signature
index.addObjects(array objects, callback)

index.addObject(object, callback) // add a single object

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

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
  ]
);

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'
    ]
  ]
);

Add a single object

1
2
3
4
5
6
7
$index->saveObject(
  [
    'objectID' => 'myID',
    'firstname' => 'Jimmie',
    'lastname'  => 'Barninger'
  ]
);

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'
]);

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.

  1. 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)
  2. 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

1
2
3
4
5
6
7
{
  "objectIDs": [
    "myObjectID1",
    "myObjectID2"
  ],
  "taskID": 678,
}

Add object

1
2
3
4
{
  "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?