Save objects

Adds or replaces records.

Required ACL: addObject

Adds records to an index or replaces them.

If a record doesn’t contain an objectID, Algolia automatically adds it. If you specify an existing objectID, it completely replaces all the attributes except for objectID.

To update only some attributes of an existing record, use partialUpdateObjects instead. To add a single record, use the saveObject method.

C#, Go, Java, JavaScript, PHP, Python only: To ensure good performance, saveObjects automatically sends batches of 1,000 records. If you’re indexing many records and have a stable, high-speed internet connection, increase the batch size to send more records per request and shorten your indexing time.

When updating large numbers of records, be aware of the rate limitations on these processes and the impact on your analytics data.

Examples

Replace all attributes in existing records

C#

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

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)

// 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")
));

const objects = [{
  firstname: 'Jimmie',
  lastname: 'Barninger',
  objectID: 'myID1'
}, {
  firstname: 'Warren',
  lastname: 'Speach',
  objectID: 'myID2'
}];

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

// With JsonObject
val json = listOf(
    buildJsonObject {
        put("firstname", "Jimmie")
        put("lastname", "Barninger")
        put("objectID", "myID1")
    },
    buildJsonObject {
        put("firstname", "Warren")
        put("lastname", "Speach")
        put("objectID", "myID2")
    }
)
index.saveObjects(json)

// With serializable class
val contacts = listOf(
    MyContact("Jimmie", "Barninger", "myID1"),
    MyContact("Warren", "Speach", "myID2")
)

index.saveObjects(MyContact.serializer(), contacts)

$res = $index->saveObjects(
  [
    [
      'objectID'  => 'myID1',
      'firstname' => 'Jimmie',
      'lastname'  => 'Barninger'
    ],
    [
      'objectID'  => 'myID2',
      'firstname' => 'Warren',
      'lastname'  => 'Speach'
    ]
  ]
);

res = index.save_objects([
    {'firstname': 'Jimmie', 'lastname': 'Barninger', 'objectID': 'myID1'},
    {'firstname': 'Warren', 'lastname': 'Speach', 'objectID': 'myID2'}
])

res = index.save_objects([{
  firstname: 'Jimmie',
  lastname:  'Barninger',
  objectID:  'myID1'
}, {
  firstname: 'Warren',
  lastname:  'Speach',
  objectID:  'myID2'
}])

client.execute {
  index into "index1" objects Seq(
    Contact("myID1", "Jimmie", "Barninger"),
    Contact("myID2", "Warren", "Speach")
  )
}

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"),
]

index.saveObjects(contacts) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

Replace all attributes in a single record

C#

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

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)

// 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")
);

index.saveObject({
  firstname: 'Jimmie',
  lastname: 'Barninger',
  city: 'New York',
  objectID: 'myID'
}).then(() => {
  // done
});

// With JsonObject
val json = buildJsonObject {
    put("firstname", "Jimmie")
    put("lastname", "Barninger")
    put("objectID", "myID")
}

index.saveObject(json)

// / With serializable class
val contact = Contact("Jimmie", "Barninger", ObjectID("myID"))

index.saveObject(Contact.serializer(), contact)

$index->saveObject(
  [
    'firstname' => 'Jimmie',
    'lastname'  => 'Barninger',
    'city'      => 'New York',
    'objectID'  => 'myID'
  ]
);

index.save_object({
    'firstname': 'Jimmie',
    'lastname': 'Barninger',
    'city': 'New York',
    'objectID': 'myID'}
)

index.save_object({
  firstname: 'Jimmie',
  lastname:  'Barninger',
  city:      'New York',
  objectID:  'myID'
})

client.execute {
  index into "index1" `object` Contact("myID", "Jimmie", "Barninger")
}

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.saveObject(contact) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

Replace all attributes in existing records and send extra HTTP headers

C#

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

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)

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

const objects = [/* objects */];

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

val json = listOf(
    buildJsonObject {
        put("objectID", "myID1")
        put("firstname", "Jimmie")
        put("lastname", "Barninger")
    },
    buildJsonObject {
        put("objectID", "myID2")
        put("firstname", "Warren")
        put("lastname", "Speach")
    }
)
val requestOptions = requestOptions {
    headerForwardedFor("94.228.178.246")
}

index.saveObjects(json, requestOptions)

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

objects = [
    # Objects
]
res = index.save_objects(objects, {
    'X-Forwarded-For': '94.228.178.246'
})

res = index.save_objects(objects, {
  headers: {
    'X-Forwarded-For': '94.228.178.246'
  }
})

client.execute {
  index into "index1" objects Seq(
    Contact("myID", "Jimmie", "Barninger"),
    Contact("myID", "Speach")
  ) options RequestOptions(
    extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
  )
}

struct Contact: Encodable {
  let objectID: ObjectID
  let firstname: String
  let lastname: String
}

var requestOptions = RequestOptions()
requestOptions.headers["X-Forwarded-For"] = "94.228.178.246"

let contacts: [Contact] = [
  .init(objectID: "myID1", firstname: "Jimmie", lastname: "Barninger"),
  .init(objectID: "myID2", firstname: "Warren", lastname: "Speach"),
]

index.saveObjects(contacts, requestOptions: requestOptions) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

Increase the default batch size

C#

var config = new SearchConfig("YourApplicationID", "YourWriteAPIKey")
{
    BatchSize = 999999
};

var client = new SearchClient(config);

config := search.Configuration{
    AppID:        "YourApplicationID",
    APIKey:       "YourWriteAPIKey",
    MaxBatchSize: 999999,
}

client := search.NewClientWithConfig(config)

  SearchConfig config =
  new SearchConfig.Builder("YourApplicationID", "YourWriteAPIKey")
      .setBatchSize(999999)
      .build();

SearchClient client = DefaultSearchClient.create(config);

$config = new SearchConfig([
    'appId' => 'YourApplicationID',
    'apiKey' => 'YourWriteAPIKey',
    'batchSize' => 999999,
]);

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

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)

config = Algolia::Search::Config.new({
  application_id: 'YourApplicationID',
  api_key: 'YourWriteAPIKey',
  batch_size: 999999
})

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

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

Parameters

objects · object[] · required

A list of records to save.

autoGenerateObjectIDIfNotExist · boolean · default: false

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.

Ruby only: the parameter name is: auto_generate_object_id_if_not_exist.

objectIDKey · string

PHP only: The objectID is set from the value of the specified key.

requestOptions · object

A mapping of request options.

Response

objectID · string

The objectID of the saved record. This property is only returned when using save object.

objectIDs · list

List of objectIDs of the saved records in order. This property is only returned when using save objects.

taskID · integer

The task ID used with the waitTask method.

Response as JSON

This section shows the JSON response returned by the API. Each API client wraps this response in language-specific objects, so the structure may vary. To view the response, use the getLogs method. Don’t rely on the order of properties—JSON objects don’t preserve key order.

Save records

JSON

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

Save record

JSON

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