API client / Methods / Indexing

Jan. 24, 2023

Save objects

Required API Key: any key with the addObject ACL

Method signature

$index->saveObjects(array objects);
$index->saveObjects(array objects, [
  // All the following parameters are optional
  'autoGenerateObjectIDIfNotExist' => boolean,
  'objectIDKey' => string
  // + any requestOptions
]);


// update a single object
$index->saveObject(array object)
$index->saveObject(array object, [
  // All the following parameters are optional
  'autoGenerateObjectIDIfNotExist' => boolean,
  'objectIDKey' => string
  // + any requestOptions
]);

index.save_objects(Array objects)

index.save_objects(Array objects, Hash opts = {
  Boolean auto_generate_object_id_if_not_exist: false
  # Any requestOptions
})

# add a single object
index.save_object(Hash object)

index.save_object(Hash object, Hash opts = {
  Boolean auto_generate_object_id_if_not_exist: false
  # Any requestOptions
})

index.saveObjects(array objects)
index.saveObjects(array objects, {
  autoGenerateObjectIDIfNotExist: boolean
  // Any other requestOptions
})

// update a single object
index.saveObject(object object)
index.saveObject(object object, {
  autoGenerateObjectIDIfNotExist: boolean
  // Any other requestOptions
})

index.save_objects(list objects)
index.save_objects(list objects, {
    // All the following parameters are optional
    'autoGenerateObjectIDIfNotExist': bool,
    // + any requestOptions
})

# update a single object'
index.save_object(dict object)'
index.save_object(dict object, {
    // All the following parameters are optional
    'autoGenerateObjectIDIfNotExist': bool,
    // + any requestOptions
})

index.replaceObjects<T: Encodable>(
  replacements: [(ObjectID, T)] ,
  requestOptions: RequestOptions? = nil,
  completion: Result<WaitableWrapper<BatchesResponse>> -> Void,
)

// update a single object
index.replaceObject<T: Encodable>(
  withID objectID: ObjectID,
  _ object: T ,
  requestOptions: RequestOptions? = nil,
  completion: Result<ObjectRevision> -> Void,
)

suspend fun <T : Indexable> Index.replaceObject(
    serializer: KSerializer<T>,
    record: T,
    requestOptions: RequestOptions? = null
): RevisionObject

suspend fun <T : Indexable> Index.replaceObjects(
    serializer: KSerializer<T>,
    records: List<T>,
    requestOptions: RequestOptions? = null
): ResponseBatch

suspend fun Index.replaceObject(
    objectID: ObjectID,
    record: JsonObject,
    requestOptions: RequestOptions? = null
): RevisionObject

suspend fun Index.replaceObjects(
    records: List<Pair<ObjectID, JsonObject>>,
    requestOptions: RequestOptions? = null
): ResponseBatch

index.SaveObjects(
  IEnumerable<T> objects,

  // All the following parameters are optional
  autoGenerateObjectIDIfNotExist: bool,
  requestOptions: RequestOptions
)

// Update a single object
index.SaveObject(
  T object,

  // All the following parameters are optional
  autoGenerateObjectIDIfNotExist: bool,
  requestOptions: RequestOptions
)

index.saveObjects(List<T> objects)
index.saveObjects(List<T> objects, RequestOptions requestOptions)
// Auto generate object ID
index.saveObjects(List<T> objects, boolean true)

// Add a single object
index.saveObject(T object)
index.saveObject(T object, RequestOptions requestOptions)
// Auto generate object ID
index.saveObject(T object, boolean true)

index.SaveObjects([]Object objects)
index.SaveObjects([]Object objects, RequestOptions requestOptions)

// Update a single object
index.SaveObject(Object object)
index.SaveObject(Object object, RequestOptions requestOptions)

index into "index_name" objects objects
index into "index_name" objects objects options requestOptions

// update a single object
index into "index_name" `object` object
index into "index_name" `object` object options requestOptions

See code examples

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

About this method

Add new objects to an index or replace existing objects with an updated set of attributes.

The save method is used to redefine the entire set of an object’s attributes (except its objectID). In other words, it fully replaces an existing object.

This method differs from partial update objects in a significant way:

With saveObjects, you define an object’s full set of attributes. Attributes not specified will no longer exist. For example, if an existing object contains the author attribute, but you don’t define it in your update call, it removes the author attribute from that object.
In contrast, when using partialUpdateObjects, you can single out one or more attributes and create or update their content. If you don’t define an existing attribute in your update call, it doesn’t impact it.

To ensure good performance, saveObjects automatically splits your records into batches of 1,000 objects. If you’re indexing many records and have a stable, high-speed internet connection, you can increase the batch size to send more records per request and shorten your indexing time.

When updating large numbers of objects, or large sizes, be aware of the rate limit. You’ll know you’ve reached the rate limit when you start receiving errors on your indexing operations. To resolve rate limiting errors, you need to wait before sending any further indexing operations.

Saving objects is a single transactional operation.

If there’s an error saving one of your objects, none of the objects are added to your index.

This method also has a singular version.

Examples

Read the Algolia CLI documentation for more information.

Replace all attributes from existing objects

Copy

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
const objects = [{
  firstname: 'Jimmie',
  lastname: 'Barninger',
  objectID: 'myID1'
}, {
  firstname: 'Warren',
  lastname: 'Speach',
  objectID: 'myID2'
}];

index.saveObjects(objects).then(({ objectIDs }) => {
  console.log(objectIDs);
});

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
8
9
10
11
12
13
14
15
16
17
18
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"),
]

let replacements = contacts.map {($0.objectID, $0) }

index.replaceObjects(replacements: replacements) { 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
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)

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
7
8
9
# Add new records from a new-line delimited JSON file
algolia objects import --file records.ndjson

# Add new records from the command line
echo '{ "objectID": "myID1", "firstName": "Jimmie", "lastName": "Barninger" }\n{ "objectID": "myID2", "firstName": "Warren", "lastName": "Speach" }\n' \
| algolia objects import <INDEX> --file -

# Add new records from a JSON (array) file; format with `jq`
cat records.json | jq '.[]' | algolia objects import <INDEX> --file -

Replace all attributes of a single object

Copy

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
7
8
9
10
11
12
13
14
struct Contact: Encodable {
  let objectID: ObjectID
  let firstname: String
  let lastname: String
  let city: String
}

let contact: Contact = .init(objectID: "myID1", firstname: "Jimmie", lastname: "Barninger", city: "New York")

index.replaceObject(withID: contact.objectID, by: contact) { 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
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)

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)

Replace all attributes from existing objects and send extra HTTP headers

Copy

1
2
3
4
$objects = [/* objects */];
$index->saveObjects($objects, [
  'X-Forwarded-For' => '94.228.178.246'
]);

1
2
3
4
5
6
7
8
9
const objects = [/* objects */];

index.saveObjects(objects, {
  headers: {
    'X-Forwarded-For': '94.228.178.246'
  }
}).then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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"),
]
let replacements: [(ObjectID, Contact)] = contacts.map { ($0.objectID, $0) }

index.replaceObjects(replacements: replacements, 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
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)

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"))
  )
}

Override the default batch size

Copy

1
2
3
4
5
6
7
$config = new SearchConfig([
    'appId' => 'YourApplicationID',
    'apiKey' => 'YourWriteAPIKey',
    'batchSize' => 999999,
]);

$client = SearchClient::createWithConfig($config);

1
2
3
4
5
6
7
config = Algolia::Search::Config.new({
  application_id: 'YourApplicationID',
  api_key: 'YourWriteAPIKey',
  batch_size: 999999
})

client = Algolia::Search::Client.create_with_config(config)

1
2
3
4
5
6
7
from algoliasearch.configs import SearchConfig
from algoliasearch.search_client import SearchClient

config = SearchConfig('YourApplicationID', 'YourWriteAPIKey')
config.batch_size = 999999

client = SearchClient.create_with_config(config)

1
2
3
let configuration = SearchConfiguration(applicationID: "YourApplicationID", apiKey: "YourWriteAPIKey")
  .set(\.batchSize, to: 999999)
let client = SearchClient(configuration: configuration)

1
2
3
4
5
6
SearchConfig config =
  new SearchConfig.Builder("YourApplicationID", "YourWriteAPIKey")
      .setBatchSize(999999)
      .build();

SearchClient client = DefaultSearchClient.create(config);

1
2
3
4
5
6
7
config := search.Configuration{
    AppID:        "YourApplicationID",
    APIKey:       "YourWriteAPIKey",
    MaxBatchSize: 999999,
}

client := search.NewClientWithConfig(config)

Parameters

`objects`	type: list of object Required A list of objects to save.
`autoGenerateObjectIDIfNotExist`	type: boolean default: false Optional `saveObjects` requires an `objectID` unless you set `autoGenerateObjectIDIfNotExist` to `true`. If the `objectID` exists, Algolia replaces the record If the `objectID` is present but doesn’t exist, Algolia creates the record If the `objectID` isn’t specified and `autoGenerateObjectID` is `false` (the default), the engine returns an error. If the `objectID` isn’t specified and `autoGenerateObjectID` is `true`, the engine generates an `objectID` and returns it in the response. In the Ruby API client, this parameter is spelled: `auto_generate_object_id_if_not_exist`.
`objectIDKey`	type: string Optional 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` 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

An objectID must be specified for each object.

If the objectID exists, the record is replaced
If the objectID doesn’t exist, the engine will create a record

Response

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language or implementation, the actual type in your language might differ from what’s written here. You can view the response in the logs (using the getLogs method).

JSON format

Save objects

Copy

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

        

Save object

Copy

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

        

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

Did you find this page helpful?

Save objects

About this method

Examples

Replace all attributes from existing objects

Replace all attributes of a single object

Replace all attributes from existing objects and send extra HTTP headers

Override the default batch size

Parameters

objects ➔ object

Response

JSON format

Save objects

Save object

On this page