Api clients / Swift / V7 / Methods

Jan 16, 2025

Partial Update Objects | iOS API Client V7 (Deprecated)

Deprecated content

This documentation is for a deprecated version of iOS API client. Some features and settings may be missing or their usage may have changed. Refer to the documentation for the latest version of iOS API client for up-to-date information.

Required API Key: any key with the addObject ACL

Method signature

index.partialUpdateObjects([[String: Any]] objects, completionHandler)
index.partialUpdateObjects(
  [[String: Any]] objects,
  createIfNotExists: Bool,
  requestOptions: RequestOptions
  completionHandler
)

// update a single object
index.partialUpdateObject([String: Any] object, completionHandler)
index.partialUpdateObject(
  [String: Any] object,
  createIfNotExists: Bool,
  requestOptions: RequestOptions
  completionHandler
)

See code examples

About this method

Update one or more attributes of an existing object.

This method lets you update only a part of an existing object, either by adding new attributes or updating existing ones.

You can partially update several objects in a single method call.

When updating many or large objects, be aware of our rate limit.

Specifying existing attributes updates them in the object, while specifying new attributes adds them. You need to use the saveObjects method to completely redefine an existing object, or replace an object with a different one.

You can’t individually update nested attributes. Specifying a nested attribute treats it as a replacement of its first-level ancestor. To change nested attributes, you need to use the saveObjects method. You can retrieve the object’s data by using the getObjects method.

Built-in operations

For convenience, we provide five different built-in operations to update an attribute without pushing its entire value. These operations can be helpful if you don’t have access to your initial data.

Increment: increment a numeric attribute
Decrement: decrement a numeric attribute
Add: append a number or string element to an array attribute
Remove: remove all matching number or string elements from an array attribute
AddUnique: add a number or string element to an array attribute only if it’s not already present

You can specify an operation by providing an object with two following properties:

_operation: the operation to apply on the attribute
value: the right-hand side argument to the operation (e.g., increment or decrement step, value to add or remove)

The built-in operations aren’t idempotent, and can trigger unexpected side-effects. For example, if you’re using the Increment or Decrement operations in a concurrent or multi-threaded environment, you may trigger it more than once and end up with incorrect data in your records.

Note: This method also has a singular version.

Examples

Partially update multiple objects using one API call

Copy

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
8
9
10
11
const objects = [{
  firstname: 'Jimmie',
  objectID: 'myID1'
}, {
  firstname: 'Warren',
  objectID: 'myID2'
}];

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

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

Copy

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
index.partialUpdateObjects(objects, {
  createIfNotExists: true,
  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
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

Copy

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

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)

Add a new state attribute to an existing object

Copy

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

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)

Increment an existing numeric attribute

Copy

1
2
3
4
5
6
7
8
9
$index->partialUpdateObject(
  [
    'count'    => [
      '_operation' => 'Increment',
      'value'      => 2
    ],
    'objectID' => 'myID'
  ]
);

1
2
3
4
5
6
7
8
9
10
index.partialUpdateObject({
  count: {
    _operation: 'Increment',
    value: 2,
  },
  objectID: 'myID',
})
.then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class Record
{
    public string ObjectID { get; set; }

    public PartialUpdateOperation<int> Count { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Count = PartialUpdateOperation<int>.Increment(2),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class RecordWithPartialUpdate {
    private String objectID;
    private PartialUpdateOperation<Integer> count;

    public Record(String objectID, PartialUpdateOperation<Integer> count) {
        this.objectID = objectID;
        this.count = count;
    }

    // Getters and setters omitted for readability
}

BatchIndexingResponse res = index.partialUpdateObjects(Collections.singletonList(
    new Record("myID", PartialUpdateOperation.Increment(2))
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
type Record struct {
    ObjectID string                        `json:"objectID"`
    Count    search.PartialUpdateOperation `json:"count"`
}

res, err := index.PartialUpdateObjects([]Record{
    {
        ObjectID: "myID",
        Count: search.PartialUpdateOperation{
            Operation: "Increment",
            Value:     2,
        },
    },
})

Add a new value to an existing array attribute

Copy

1
2
3
4
5
6
7
8
9
$index->partialUpdateObject(
  [
    '_tags'    => [
      '_operation' => 'AddUnique',
      'value'      => 'public'
    ],
    'objectID' => 'myID'
  ]
);

1
2
3
4
5
6
7
8
9
10
index.partialUpdateObject({
  _tags: {
    _operation: 'AddUnique',
    value: 'public',
  },
  objectID: 'myID',
})
.then(({ objectIDs }) => {
  console.log(objectIDs);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
class Record
{
    public string ObjectID { get; set; }

    [JsonProperty(PropertyName = "_tags")]
    public PartialUpdateOperation<string> Tags { get; set; }
}

var record = new Record
{
    ObjectID = "myID",
    Tags = PartialUpdateOperation<string>.AddUnique("public"),
};

var res = index.PartialUpdateObjects(new List<Record>
{
    record
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class RecordWithPartialUpdate {
    private String objectID;

    @JsonProperty("_tags")
    private PartialUpdateOperation<String> tags;

    public Record(String objectID, PartialUpdateOperation<String> tags) {
        this.objectID = objectID;
        this.tags = tags;
    }

    // Getters and setters omitted for readability
}

BatchIndexingResponse res = index.partialUpdateObjects(Collections.singletonList(
    new Record("myID", PartialUpdateOperation.AddUnique("public"))
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
type Record struct {
    ObjectID string                        `json:"objectID"`
    Tags     search.PartialUpdateOperation `json:"_tags"`
}

res, err := index.PartialUpdateObjects([]Record{
    {
        ObjectID: "myID",
        Tags: search.PartialUpdateOperation{
            Operation: "AddUnique",
            Value:     "public",
        },
    },
})

Parameters

`objects`	type: list of object Required
`objectID`	type: integer Required objectID to update.
`createIfNotExists`	type: boolean default: true (false for .NET and Java) Optional When `true`, a partial update on a nonexistent object will create the object (generating the objectID and using the attributes as defined in the object). When `false`, a partial update on a nonexistent object will be ignored (but no error will be sent back). Note: Java and .NET default to `false`.
`requestOptions`	type: key/value mapping default: "" Optional A mapping of [`requestOptions`](/doc/api-client/getting-started/request-options/) to send along with the query.

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

Copy



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

      

`objectIDs`	list List of objectIDs of the objects to be updated.
`taskID`	integer The taskID used with the waitTask method.

Did you find this page helpful?

Partial Update Objects | iOS API Client V7 (Deprecated)

About this method

Built-in operations

Examples

Partially update multiple objects using one API call

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

Update only the city attribute of an existing object

Add a new state attribute to an existing object

Increment an existing numeric attribute

Add a new value to an existing array attribute

Parameters

objects ➔ object

Response

JSON format

On this page