API clients / Methods / Indexing

Mar 27, 2025

Save objects

This is documentation for v3 of the PHP API clients, which is not the latest version. To see the documentation for the latest version, see PHP v4.

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 record
$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 record
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 record
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 record
index.save_object(dict object)'
index.save_object(dict object, {
    // All the following parameters are optional
    'autoGenerateObjectIDIfNotExist': bool,
    // + any requestOptions
})

index.saveObjects<T: Encodable>(
  _ objects: [T] ,
  requestOptions: RequestOptions? = nil,
  completion: @escaping ResultBatchesCallback,
)

// Save a single record
index.saveObject<T: Encodable>(
  _ object: T ,
  requestOptions: RequestOptions? = nil,
  completion: @escaping ResultTaskCallback<ObjectCreation>,
)

suspend fun <T> saveObject(
    serializer: _KSerializer<T>_,
    record: _T_,
    requestOptions: RequestOptions?
): CreationObject


suspend fun saveObject(
    record: JsonObject,
    requestOptions: RequestOptions?
): CreationObject

suspend fun <T> saveObjects(
    serializer: _KSerializer<T>_,
    records: List<T>,
    requestOptions: RequestOptions?
): ResponseBatch

suspend fun saveObjects(
    records: List<JsonObject>,
    requestOptions: RequestOptions?
): ResponseBatch

index.SaveObjects(
  IEnumerable<T> objects,

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

// Update a single record
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 objectID
index.saveObjects(List<T> objects, boolean true)

// Add a single record
index.saveObject(T object)
index.saveObject(T object, RequestOptions requestOptions)
// Auto-generate objectID
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 record
index into "index_name" `object` object
index into "index_name" `object` object options requestOptions

See code examples

About this method #

Adds or replaces records.

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.

Limitations#

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#

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// 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)

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 in a single record#

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.saveObject(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
// 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)

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 in existing records 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
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)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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)

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

Increase 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 records 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 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 request options.

objects ➔ object #

An objectID must be specified for each record.

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. Each API client encapsulates this response inside objects specific to the programming language, so that the actual response might be different. You can view the response by using the getLogs method. Don’t rely on the order of attributes in the response, as JSON doesn’t guarantee the ordering of keys in objects.

JSON format#

Save records#

Copy

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

        

Save record#

Copy

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

        

Field	Description
`objectIDs` #	list List of objectIDs of the saved records in order. This property is only returned when using save objects.
`objectID` #	string The objectID of the saved record. 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 # Found an issue?

Limitations#

Examples # Found an issue?

Replace all attributes in existing records#

Replace all attributes in a single record#

Replace all attributes in existing records and send extra HTTP headers#

Increase the default batch size#

Parameters # Found an issue?

objects ➔ object #

Response # Found an issue?

JSON format#

Save records#

Save record#

On this page

About this method #

Examples #

Parameters #

Response #