API Reference / API Methods / Indexing / Add objects
Jan. 14, 2019

Add objects

Required API Key: any key with the addObject ACL
Method signature
// addObject was removed in the v2 of the PHP client
// use saveObjects with 'autoGenerateObjectIDIfNotExist' instead

$index->saveObjects(objects, [
  "autoGenerateObjectIDIfNotExist" => true
  // any other requestOptions
]

// add a single object
$index->saveObject(object, [
  "autoGenerateObjectIDIfNotExist" => true
  // any other requestOptions
]

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->addObjects($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

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

List of objectIDs of the inserted objects.

taskID
integer

The taskID used with the waitTask method.

Did you find this page helpful?