Skip to content

Updating multiple objects

This operation updates one or more objects in a database table. The objects to be updated can be identified with:

  1. objectId values
  2. A query string (a where clause)
  3. Result of a previously ran bulkCreate or object retrieval operation in the same transaction.

To add this operation to a Unit Of Work instance, use the following methods. The methods are split into categories based on how the the objects are identified in the API:

// This operation explicitly lists the objectId values of the objects
// which will be updated in the database. These objectId values must
// be present in the objectsToUpdate argument. Each referenced
// object must be stored in the database table with the "tableName"
// name. Backendless identifies the objects in the database and
// updates them with the values from the changes argument.
// The "changes" argument is a collection of key/value pairs. Each
// key in the collection must correspond to a column/property of the
// updated objects. The value corresponding to the key is the update
// the objects will receive.
- (OpResult *)[unitOfWorkInstance
               bulkUpdateWithTableName:(NSString * _Nonnull)
               objectsToUpdate:(NSArray<NSString *> * _Nonnull)
               changes:(NSDictionary<NSString *,id> * _Nonnull)];
// This operation runs a query expressed through the whereClause
// argument. The query is executed in a table with the "tableName"
// name. For more information see the API documentation about
// querying with whereClause. Objects which match the query
// are updated with the values from the "changes" argument.
// The "changes" argument is a collection of key/value pairs.
// Each key in the collection must correspond to a column/property
// of the updated objects. The value corresponding to the key is
// the update the objects will receive
- (OpResult *)[unitOfWorkInstance
               bulkUpdateWithTableName:(NSString * _Nonnull)
               whereClause:(NSString * _Nonnull)
               changes:(NSDictionary<NSString *,id> * _Nonnull)];
// Update the objects identified by the objectIdsForChanges argument,
// which is a result of another operation in the same transaction.
// These operations can be either "Retrieving objects" or "Saving
// multiple objects". Objects identified by "objectIdsForChanges"
// are updated in the database with the values from the "changes"
// collection.
- (OpResult *)[unitOfWorkInstance
               bulkUpdateWithObjectIdsForChanges:(OpResult * _Nonnull)
               changes:(NSDictionary<NSString *,id> * _Nonnull)];

// This operation explicitly lists the objectId values of the objects
// which will be updated in the database. These objectId values must
// be present in the objectsToUpdate argument. Each referenced
// object must be stored in the database table with the "tableName"
// name. Backendless identifies the objects in the database and
// updates them with the values from the changes argument.
// The "changes" argument is a collection of key/value pairs. Each
// key in the collection must correspond to a column/property of the
// updated objects. The value corresponding to the key is the update
// the objects will receive.
unitOfWorkInstance.bulkUpdate(tableName: String,
                              objectsToUpdate: [String],
                              changes: [String : Any]) -> OpResult
// This operation runs a query expressed through the whereClause
// argument. The query is executed in a table with the "tableName"
// name. For more information see the API documentation about
// querying with whereClause. Objects which match the query
// are updated with the values from the "changes" argument.
// The "changes" argument is a collection of key/value pairs.
// Each key in the collection must correspond to a column/property
// of the updated objects. The value corresponding to the key is
// the update the objects will receive
unitOfWorkInstance.bulkUpdate(tableName: String,
                              whereClause: String,
                              changes: [String : Any]) -> OpResult
// Update the objects identified by the objectIdsForChanges argument,
// which is a result of another operation in the same transaction.
// These operations can be either "Retrieving objects" or "Saving
// multiple objects". Objects identified by "objectIdsForChanges"
// are updated in the database with the values from the "changes"
// collection.
unitOfWorkInstance.bulkUpdate(objectIdsForChanges: OpResult,
                              changes: [String : Any]) -> OpResult

Return Value

The operation returns an OpResult object which represents the result of this operation - number of objects updated in the database.

Example

Consider the example below. The example adds an operation to update multiple objects in the database. The change is to set the orderStatus property to "completed" for all orders which were delivered. This is the what the data table looks like before the transaction runs:

data-before-bulkupdate.zoom70

// compose a list of objects to be updated
// here we hard-code the objectId values,
// but in your code these values may be
// coming either from a query or from your
// data model on the client side.
NSArray *objectsForChanges = @[@"37ADFFA8-39E2-73A5-FF44-651EF5C4E900",
                               @"996E2034-4CC6-0BC4-FF01-E92077819700",
                               @"EB68A9E1-DC24-C961-FFC4-2EF9227BF700"];

// create a unit of work object
UnitOfWork *unitOfWork = [UnitOfWork new];

// compose the changes object. The change it
// has it to update the "orderStatus" column
// with the value "completed"
NSDictionary *changes = @{@"orderStatus": @"completed"};

// add the "bulkUpdate" operation to the transaction
[unitOfWork bulkUpdateWithTableName:@"Order"
                    objectsToUpdate:objectsForChanges
                            changes:changes];

// run the transaction
[unitOfWork executeWithResponseHandler:^(UnitOfWorkResult *result) {
    NSLog(@"Transaction complete - %@", result);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
// create a unit of work object
UnitOfWork *unitOfWork = [UnitOfWork new];

// set the where clause. It will identify all
// objects where the "orderStatus" column has the
// value of "delivery pending".
NSString *whereClause = @"orderStatus = 'delivery pending'";

// compose the changes object. The change it
// has it to update the "orderStatus" column
// with the value "completed"
NSDictionary *changes = @{@"orderStatus": @"completed"};

// add the "bulkUpdate" operation to the transaction
[unitOfWork bulkUpdateWithTableName:@"Order"
                        whereClause:whereClause
                            changes:changes];

// run the transaction
[unitOfWork executeWithResponseHandler:^(UnitOfWorkResult *result) {
    NSLog(@"Transaction complete - %@", result);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];
// create a unit of work object
UnitOfWork *unitOfWork = [UnitOfWork new];

// compose a query. It will identify all Order
// objects where the "orderStatus" column has the
// value of "delivery pending".
DataQueryBuilder *queryBuilder = [DataQueryBuilder new];
queryBuilder.whereClause = @"orderStatus = 'delivery pending'";
queryBuilder.pageSize = 100;

// fetch the order objects with the query.
OpResult *pendingOrdersResult = [unitOfWork findWithTableName:@"Order" queryBuilder:queryBuilder];

// compose the changes object. The change it
// has it to update the "orderStatus" column
// with the value "completed"
NSDictionary *changes = @{@"orderStatus": @"completed"};

// add the "bulkUpdate" operation to the transaction
// apply the "changes" to the result of the "find" operation
[unitOfWork bulkUpdateWithObjectIdsForChanges:pendingOrdersResult
                                      changes:changes];

// run the transaction
[unitOfWork executeWithResponseHandler:^(UnitOfWorkResult *result) {
    NSLog(@"Transaction complete - %@", result);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

// compose a list of objects to be updated
// here we hard-code the objectId values,
// but in your code these values may be
// coming either from a query or from your
// data model on the client side.
let objectsForChanges = ["37ADFFA8-39E2-73A5-FF44-651EF5C4E900",
                         "996E2034-4CC6-0BC4-FF01-E92077819700",
                         "EB68A9E1-DC24-C961-FFC4-2EF9227BF700"]

// create a unit of work object
let unitOfWork = UnitOfWork()

// compose the changes object. The change it
// has it to update the "orderStatus" column
// with the value "completed"
let changes = ["orderStatus": "completed"]

// add the "bulkUpdate" operation to the transaction
let _ = unitOfWork.bulkUpdate(tableName: "Order", objectsToUpdate: objectsForChanges, changes: changes)

// run the transaction
unitOfWork.execute(responseHandler: { result in
    print("Transaction complete - \(result)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})
// create a unit of work object
let unitOfWork = UnitOfWork()

// set the where clause. It will identify all
// objects where the "orderStatus" column has the
// value of "delivery pending".
let whereClause = "orderStatus = 'delivery pending'"

// compose the changes object. The change it
// has it to update the "orderStatus" column
// with the value "completed"
let changes = ["orderStatus": "completed"]

// add the "bulkUpdate" operation to the transaction
let _ = unitOfWork.bulkUpdate(tableName: "Order", whereClause: whereClause, changes: changes)

// run the transaction
unitOfWork.execute(responseHandler: { result in
    print("Transaction complete - \(result)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})
// create a unit of work object
let unitOfWork = UnitOfWork()

// compose a query. It will identify all Order
// objects where the "orderStatus" column has the
// value of "delivery pending".
let queryBuilder = DataQueryBuilder()
queryBuilder.whereClause = "orderStatus = 'delivery pending'"
queryBuilder.pageSize = 100

// fetch the order objects with the query.
let pendingOrdersResult = unitOfWork.find(tableName: "Order", queryBuilder: queryBuilder)

// compose the changes object. The change it
// has it to update the "orderStatus" column
// with the value "completed"
let changes = ["orderStatus": "completed"]

// add the "bulkUpdate" operation to the transaction
// apply the "changes" to the result of the "find" operation
let _ = unitOfWork.bulkUpdate(objectIdsForChanges: pendingOrdersResult, changes: changes)

// run the transaction
unitOfWork.execute(responseHandler: { result in
    print("Transaction complete - \(result)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

This is what the objects look like in the database after the transaction runs:

data-after-bulkupdate.zoom70