Partial Update Objects | JavaScript API Client V3 (Deprecated)

This version of the JavaScript API client has been deprecated in favor of the latest version of the JavaScript API client.

index.partialUpdateObjects(array objects, callback)
index.partialUpdateObjects(array objects, boolean createIfNotExists, callback)

// update a single object
index.partialUpdateObject(object object, callback)
index.partialUpdateObject(object object, boolean createIfNotExists, callback)

About this method

Update one or more attributes of an existing object.

This method enables you to update only a part of an object by singling out one or more attributes of an existing object and performing the following actions:

• add new attributes
• update the content of existing attributes

You can perform the above actions on multiple objects in a single method call.

Specifying existing attributes will update them in the object, while specifying new attributes will add them. You need to use the save objects method if you want to completely redefine an existing object, replace an object with a different one, or remove attributes. You cannot individually remove attributes.

Nested attributes cannot be individually updated. If you specify a nested attribute, it will be treated as a replacement of its first-level ancestor. To change nested attributes, you will need to use the save object method. You can initially get the object’s data either from your own data or by using the get object method.

The same can be said about array attributes: you cannot update individual elements of an array. If you have a record in which one attribute is an array, you will need to retrieve the record’s array, change the element(s) of the array, and then resend the full array using this method.

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

Partially update multiple objects using one API call

1
2
3
4
5
6
7
8
9
10
11
12
$index->partialUpdateObjects(
    [
        [
            'objectID'  => 'myID1',
            'firstname' => 'Jimmie'
        ],
        [
            'objectID'  => 'myID2',
            'firstname' => 'Warren'
        ]
    ]
);

1
2
3
4
5
6
7
index.partial_update_objects([{
  firstname: 'Jimmie',
  objectID: 'myID'
}, {
  firstname: 'Warren',
  objectID: 'myID2'
}])

1
2
3
4
5
6
7
8
9
10
11
12
13
const objects = [{
  firstname: 'Jimmie',
  objectID: 'myID1'
}, {
  firstname: 'Warren',
  objectID: 'myID2'
}];

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

  console.log(content);
});

1
2
3
4
index.partial_update_objects([
    {'objectID': 'myID1', 'firstname': 'Jimmie'},
    {'objectID': 'myID2', 'firstname': 'Warren'}
])

1
2
3
4
5
6
7
8
9
10
11
let obj1 = ["firstname": "Jimmie", "objectID": "myID1"]
let obj2 = ["firstname": "Warren", "objectID": "myID2"]

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

1
2
3
4
5
6
7
8
9
10
List<JSONObject> array = new ArrayList<JSONObject>();

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

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

1
2
3
4
5
6
7
8
9
10
List<Contact> contacts = new List<Contact>
{
    new Contact { ObjectID = "myID1", Firstname = "Jimmie" },
    new Contact { ObjectID = "myID2", Firstname = "Warren" }
};

index.PartialUpdateObjects(contacts);

// Asynchronous
await index.PartialUpdateObjectsAsync(contacts);

1
2
3
4
5
6
7
8
9
10
List<Contact> contacts = Arrays.asList(
  new Contact().setCity("San Francisco").setObjectID("MyID"),
  new Contact().setCity("Paris").setObjectID("MyID2")
);

// Sync version
index.partialUpdateObjects(contacts);

// Async version
index.partialUpdateObjectsAsync(contacts);

1
2
3
4
5
6
objects := []map[string]string{
  {"objectID": "myID1", "lastname": "Barninger"},
  {"objectID": "myID2", "firstname": "Ray"},
}

res, err := index.PartialUpdateObjects(objects)

1
2
3
4
5
6
client.execute {
  partialUpdate from "index" objects Seq(
    Contact("myID", "Jimmie", "Barninger"),
    Contact("myID", "Speach")
  )
}

1
2
3
4
5
6
7
val firstname = Attribute("firstname")
val partials = listOf(
    ObjectID("myID1") to Partial.Update(firstname, "Jimmie"),
    ObjectID("myID2") to Partial.Update(firstname, "Warren")
)

index.partialUpdateObjects(partials)

Partially update multiple objects using one API call and send extra HTTP headers

1
2
3
4
5
6
$objects = [/* objects */];

$res = $index->partialUpdateObjects($objects, [
  'createIfNotExists' => true,
  'X-Forwarded-For' => '94.228.178.246'
]);

1
2
3
4
5
6
7
8
9
objects = []

create_if_not_exits = true

extra_headers = {
  'X-Forwarded-For': '94.228.178.246'
}

res = index.partial_update_objects(objects, create_if_not_exits, extra_headers)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const objects = [{
  firstname: 'Jimmie',
  objectID: 'myID1'
}, {
  firstname: 'Warren',
  objectID: 'myID2'
}];

client.setExtraHeader('X-Forwarded-For', '94.228.178.246');
index.partialUpdateObjects(objects, (err, content) => {
  if (err) throw err;

  console.log(content);
});

1
2
3
4
objects = [
      # Objects
]
index.partial_update_objects(objects, {'X-Forwarded-For': '94.228.178.246'})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
let requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
List<JSONObject> array = new ArrayList<JSONObject>();

array.add(
  new JSONObject().put("firstname", "Jimmie").put("objectID", "myID")
);
array.add(
  new JSONObject().put("firstname", "Warren").put("objectID", "myID2")
);
index.partialUpdateObjectsAsync(
  new JSONArray(array),
  true,
  new RequestOptions()
    .setHeader("X-Algolia-User-ID", "94.228.178.246"),
  null
);

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" },
    new Contact { ObjectID = "myID2", Firstname = "Warren" }
};

RequestOptions requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-User-ID", "user123" } }
};

index.PartialUpdateObjects(contacts, requestOptions);

// Asynchronous
await index.PartialUpdateObjectsAsync(contacts, requestOptions);

1
2
3
4
5
6
7
8
9
10
11
12
13
List<Contact> contacts = Arrays.asList(
  new Contact().setCity("San Francisco").setObjectID("MyID"),
  new Contact().setCity("Paris").setObjectID("MyID2")
);

RequestOptions requestOptions =
    new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")

// Sync version
index.partialUpdateObjects(contacts, requestOptions);

// Async version
index.partialUpdateObjectsAsync(contacts, requestOptions);

1
2
3
4
5
6
7
8
9
10
objects := []map[string]string{
  {"objectID": "myID1", "lastname": "Barninger"},
  {"objectID": "myID2", "firstname": "Ray"},
}

extraHeaders := opt.ExtraHeaders(map[string]string{
  "X-Algolia-User-ID": "userID2",
})

res, err := index.PartialUpdateObjects(objects, extraHeaders)

1
2
3
4
5
6
7
8
9
10
client.execute {
  client.execute {
    partialUpdate from "index" objects Seq(
      Contact("myID", "Jimmie", "Barninger"),
      Contact("myID", "Speach")
    ) options RequestOptions(
      extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
    )
  }
}

1
2
3
4
5
6
7
8
9
10
val firstname = Attribute("firstname")
val partials = listOf(
    ObjectID("myID1") to Partial.Update(firstname, "Jimmie"),
    ObjectID("myID2") to Partial.Update(firstname, "Warren")
)
val requestOptions = requestOptions {
    headerAlgoliaUserId(UserID("user123"))
}

index.partialUpdateObjects(partials, requestOptions = requestOptions)

Update only the city attribute of an existing object

1
2
3
4
5
6
$index->partialUpdateObject(
  [
    'city'     => 'San Francisco',
    'objectID' => 'myID'
  ]
);

1
2
3
4
index.partial_update_object({
  city: 'San Francisco',
  objectID: 'myID'
})

1
2
3
4
5
6
7
8
index.partialUpdateObject({
  city: 'San Francisco',
  objectID: 'myID'
}, (err, content) => {
  if (err) throw err;

  console.log(content);
});

1
index.partial_update_object({"objectID": "myID", "city": "San Francisco"})

1
2
let partialObject = ["city": "San Francisco"]
index.partialUpdateObject(partialObject, withID: "myID")

1
2
3
4
5
index.partialUpdateObjectAsync(
  new JSONObject("{\"city\": \"San Francisco\"}"),
  "myID",
  null
);

1
2
3
4
5
6
var contact = new Contact { ObjectID = "myID", City = "San Francisco"" };

index.PartialUpdateObject(contact);

// Asynchronous
await index.PartialUpdateObjectAsync(contact);

1
2
3
4
5
6
7
Contact contact = new Contact().setObjectID("myID").setCity("San Francisco");

// Sync version
index.partialUpdateObject(contact);

// Sync version
index.partialUpdateObjectAsync(contact);

1
2
3
4
5
6
7
8
9
10
11
type Contact struct {
	ObjectID string `json:"objectID"`
	City     string `json:"city"`
}

contact := Contact{
	ObjectID: "myID",
	City:     "San Francisco",
}

res, err := index.PartialUpdateObject(contact)

1
2
3
4
5
6
client.execute {
  partialUpdate from "index" `object` Contact(
    objectID = "myID",
    city = "San Francisco"
  )
}

1
2
3
val partial = Partial.Update(Attribute("city"), "San Francisco")

index.partialUpdateObject(ObjectID("myID"), partial)

Add a new state attribute to an existing object

1
2
3
4
5
6
$index->partialUpdateObject(
  [
    'state'    => 'California',
    'objectID' => 'myID'
  ]
);

1
2
3
4
index.partial_update_object({
  state: 'California',
  objectID: 'myID'
})

1
2
3
4
5
6
7
8
index.partialUpdateObject({
  state: 'California',
  objectID: 'myID'
}, (err, content) => {
  if (err) throw err;

  console.log(content);
});

1
index.partial_update_object({'objectID': 'myID', 'state': 'California'})

1
2
let partialObject = ["state": "California"]
index.partialUpdateObject(partialObject, withID: "myID")

1
2
3
4
5
index.partialUpdateObjectAsync(
  new JSONObject("{\"state\": \"California\"}"),
  "myID",
  null
);

1
2
3
4
index.PartialUpdateObject(new Contact { ObjectID = "myID1", State = "California" });

// Asynchronous
await index.PartialUpdateObjectAsync(new Contact { ObjectID = "myID1", State = "California" });

1
2
3
4
5
6
7
Contact contact = new Contact().setObjectID("myID").setState("California");

// Sync version
index.partialUpdateObject(contact);

// Sync version
index.partialUpdateObjectAsync(contact);

1
2
3
4
5
6
7
8
9
10
11
type Contact struct {
	ObjectID string `json:"objectID"`
	State    string `json:"state"`
}

contact := Contact{
	ObjectID: "myID",
	State:    "California",
}

res, err := index.PartialUpdateObject(contact)

1
2
3
4
5
6
client.execute {
  partialUpdate from "index" `object` Contact(
    objectID = "myID",
    state = "California"
  )
}

1
index.partialUpdateObject(new JSONObject().put("state", "California"), "myID");

1
2
3
val partial = Partial.Update(Attribute("state"), "California")

index.partialUpdateObject(ObjectID("myID"), partial)

Parameters

objects ➔ object

An object that matches part or all of your index’s object.

The object needs to contain an objectID.

If you supply an unknown objectID:

• When createIfNotExists is true, the method creates a new record with the supplied objectID and attributes.
• if createIfNotExists is false, the method will be ignored (but no error will be sent back).

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,
}