Api clients / JavaScript / V3 / Methods

Jun 25, 2024

Save 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.saveObjects(array objects, callback)

index.saveObject(object object, callback) // update a single object

See code examples

About this method

Replace an existing object with an updated set of attributes.

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

Saving objects has the same effect as the add objects method if you specify objectIDs for every record.

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

With save objects you define an object’s full set of attributes. Attributes not specified will no longer exist. For example, if an existing object contains attribute X, but X is not defined in a later update call, attribute X will no longer exist for that object.
In contrast, with partial update objects you can single out one or more attributes, and either remove them, add them, or update their content. Additionally, attributes that already exist but are not specified in a partial update are not impacted.

When updating 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

Replace all attributes from existing objects

Copy

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

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

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

index.saveObjects(objects, (err, content) => {
  if (err) throw err;

  console.log(content);
});

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

Copy
let obj1 = ["firstname": "Jimmie", "lastname": "Barninger", "objectID": "myID1"]
let obj2 = ["firstname": "Warren", "lastname": "Speach", "objectID": "myID2"]
index.saveObjects([obj1, obj2], completionHandler: { (content, error) -> Void in
  if error == nil {
      print("Object IDs: \(content!)")
  }
})

Copy
List<JSONObject> array = new ArrayList<JSONObject>();
array.add(
  new JSONObject()
    .put("firstname", "Jimmie")
    .put("lastname", "Barninger")
    .put("objectID", "myID")
);
array.add(
  new JSONObject()
    .put("firstname", "Warren")
    .put("lastname", "Speach")
    .put("objectID", "myID2")
);

index.saveObjectsAsync(new JSONArray(array), null);

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

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

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

Copy
// 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)

Replace all attributes of a single object

Copy

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

Copy
index.saveObject({
  firstname: 'Jimmie',
  lastname: 'Barninger',
  city: 'New York',
  objectID: 'myID'
}, (err, content) => {
  if (err) throw err;

  console.log(content);
});

Copy
JSONObject object = new JSONObject()
  .put("firstname", "Jimmie")
  .put("lastname", "Barninger")
  .put("city", "New York");

index.saveObjectAsync(object, "myID", null);

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

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

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

Copy
// 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)

Replace all attributes from existing objects and send extra HTTP headers

Copy

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

Copy
client.setExtraHeader('X-Forwarded-For', '94.228.178.246');
index.saveObjects([{
  firstname: 'Jimmie',
  lastname: 'Barninger',
  city: 'New York',
  objectID: 'myID'
}], (err, content) => {
  if (err) throw err;

  console.log(content);
});

Copy
let requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"

let obj1 = ["firstname": "Jimmie", "lastname": "Barninger", "objectID": "myID1"]
let obj2 = ["firstname": "Warren", "lastname": "Speach", "objectID": "myID2"]

index.saveObjects(
  [obj1, obj2],
  requestOptions: requestOptions,
  completionHandler: { (content, error) -> Void in
  if error == nil {
      print("Object IDs: \(content!)")
  }
})

Copy
List<JSONObject> array = new ArrayList<JSONObject>();

array.add(
  new JSONObject()
    .put("firstname", "Jimmie")
    .put("lastname", "Barninger")
    .put("objectID", "myID")
);
array.add(
  new JSONObject()
    .put("firstname", "Warren")
    .put("lastname", "Speach")
    .put("objectID", "myID2")
);

index.saveObjectsAsync(
  new JSONArray(array),
  new RequestOptions().setHeader("X-Algolia-User-ID", "94.228.178.246"), null
);

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

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

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

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

Copy
val json = listOf(
    ObjectID("myID1") to json {
        "firstname" to "Jimmie"
        "lastname" to "Barninger"
    },
    ObjectID("myID1") to json {
        "firstname" to "Warren"
        "lastname" to "Speach"
    }
)
val requestOptions = requestOptions {
    headerAlgoliaUserId(UserID("user123"))
}

index.replaceObjects(json, requestOptions)

Parameters

`objects`	type: list of object Required
`autoGenerateObjectIDIfNotExist`	type: boolean Optional If `false`, if any of the object do not contain an `objectID`, the method throws an error. If `true`, if any of the object do not contain an `objectID`, the object is automatically assigned an `objectID` by the engine. Only available for PHP.
`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`](/doc/api-client/getting-started/request-options/) to send along with the query.

objects ➔ object

An objectID needs to be specified for each object.

If the objectID exists, the record is replaced
If the objectID does not exist, a record will be created

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

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 | JavaScript API Client V3 (Deprecated)

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

Parameters

objects ➔ object

Response

JSON format

Save objects

Save object

On this page