Upsert multiple objects

Description

When performing this operation, the system attempts to locate and update a specific set of objects first. If some or all of these objects cannot be found, any objects specified in the operation's invocation are inserted into the data table, while any remaining objects are simply updated. This process is based on using the unique identifiers (objectId) of the records to apply any necessary changes in the data table.

Method

unitOfWorkInstance.bulkUpsert<T>( List<T> instances, [String tableName] );

where:

Argument	Description
tableName	Name of the table where objects will be upserted.
instances	Identifies an array of objects that must be upserted in the data table.

The  signature accepts the name of the table (tableName) and an array of Map objects (instances) that contain the column names and their corresponding values. This provides a more flexible way to specify the data to be upserted without requiring specific object instances. The instances should have key-value pairs where the key represents the column name and the value represents the value to be upserted. The method will perform the bulk upsert operation using the provided table name and objects and return an OpResult object.

Return Value

This operation returns an instance of the OpResult class which represents an object containing the result of operation and also an array containing objectId values of updated or inserted objects. The OpResult object can be used as an argument in other operations in the same transaction (same UnitOfWork instance). For more information see the Operation Result chapter of this guide.

Example

The example below uses the value of the "objectId"  property of each object in the invocation to search the "Person" data table for objects that exist and can be updated. If objects are found in the table, they are updated accordingly, while any new objects that do not already exist in the table are inserted as new records.

MapCustom Class

var list = [
  {
    'email': 'alice@yourmail.com',
    'age': 20,
    'objectId': 'CB3C9021-E08E-4DB1-AB98-CEC00F83476F',
  },
  {
    'email': 'bob@yourmail.com',
    'age': 30,
    'objectId': '5F952BCC-1B74-47EB-BF52-C2B943C55B52',
  },
];
UnitOfWork uow = UnitOfWork();
uow.bulkUpsert(list, 'TestTable');
await uow.execute();

TestTable objFirst = TestTable()
..email = 'alice@yourmail.com'
..age = 20
..objectId = 'CB3C9021-E08E-4DB1-AB98-CEC00F83476F';

TestTable objSecond = TestTable()
..email = 'bob@yourmail.com'
..age = 30
..objectId = '5F952BCC-1B74-47EB-BF52-C2B943C55B52';


UnitOfWork uow = UnitOfWork();
uow.bulkUpsert([objFirst, objSecond]);
await uow.execute();

Codeless Reference

where:

Argument	Description
operation id	Unique identifier of the current operation which can be used later on in other subsequent operation within the same transaction. Refer to the Operation Result topic for more information.
table name	Name of the data table where the operation must apply changes.
objects	A list of objects that must be upserted into the data table. Each object within the list should include the "objectId" property which identifies an existing object in the database to be updated, or specifies a new object to be inserted into the data table.
return result	When this box is checked, the operation reference is returned alongside with a list containing updated or inserted objects.

Returns an object containing the operation result and also a list of records that were updated or inserted into the data table.

Consider the object stored in the data table called Person:

To create a transaction and upsert new objects in the data table, you must use the following additional Codeless blocks:

1 Create Transaction Codeless block is important, since it creates an empty object which is used as a placeholder for transaction information. Refer to the Transaction Isolation topic to learn more about the options of the isolation property. This empty object must be saved to a variable.

2  All operations stored inside a transaction must have a specific order. The following Codeless block sets this order for different operation types. The transaction property expects an empty object created with the Create Transaction Codeless block. This mandatory empty object is used to store transaction information. In the context of this description, the variable that was set for the Create Transaction Codeless block must be used in the transaction property to specify the empty object.

This block expects different operation types, such as "Bulk Create", "Bulk Upsert", "Bulk Update", "Bulk Delete"  and other. This topic describes the "Bulk Upsert" operation type used in conjunction with these additional Codeless blocks. The example below highlights how this block accepts the "Bulk Upsert" operation and also provides insight how the previous blocks are used to create the required logic structure:

As it was mentioned earlier, you need a variable(e.g. myTx)  that will store the empty object. Then this empty object myTx must be passed to the Add Operations to Transaction Codeless block, so that the logic can store the transaction details. And then inside this block you must declare operations; this example uses only one operation of the "Bulk Upsert" type.

Now lets provide data to properties of the "Bulk Upsert" Operation Codeless block. The table name argument must reference the data table where objects will be upserted. The operation id property must be set to the value of your choice, while the objects argument expects a list of objects, whose properties must match the column names in the Person data table.

To allow the operation to find and update existing objects or insert new records in case they do not exist, it is necessary to specify the value in the "objectId" property.

3  To run the logic above you must use an additional Codeless block that initiates the operation. The transaction property expects an object containing the transaction details(e.g. myTx variable).

where:

Argument	Description
transaction	Expects an object containing transaction details, this includes: operation type and data.
return result	When this box is checked, the operation is set to return an object containing the operation result.
throw error	Check this box to return an error in case if the operation cannot be executed.

The following example combines all Codeless blocks described above into the logic that upserts multiple objects in the data table called Person:

This example contains an additional variable called opRef(operation reference), that was added intentionally to highlight the operation reference returned after this Codeless logic runs:

Furthermore, the operation has upserted two existing objects in the data table: