Saving multiple objects

This is a transaction operation responsible for saving one or more new objects in the database. To add this operation to a Unit Of Work instance, use the following methods:

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

The method argument is a collection containing objects which will be stored in the database. As you can see from the method signatures, there are two approaches for storing new objects: class-based and map-based approaches. The former uses a class defined in your program. The signature defines that class as type E. In this case, the name of the table where the object will be stored is the same as the name of the class. The objectsToSave argument in both signatures is a collection of objects to save. Each object must conform to the rules defined in the Data Object section of this guide.

Return Value

The operation returns an OpResult object which represents the result of this operation - a collection of objectId values. Each element in the resulting collection is a string value. It is the objectId of the corresponding object stored in the database. The OpResult object can be used as an argument in other operations in the same transaction (same UnitOfWork instance). It is also possible to use OpResult to "extract" the value of a property of the saved object and use it in other operations. For more information see the Operation Result chapter of this guide.

Example

Consider the example below. In the example three objects are added to a collection. The collection is then added to a transaction with the bulkCreate method.

Using MapCustom Class

final unitOfWork = UnitOfWork();

final person1 = {
 "name": "Joe",
 "age": 25
};

final person2 = {
 "name": "Mary",
 "age": 32
};

final person3 = {
 "name": "Bob",
 "age": 22
};

final people = [person1, person2, person3];

unitOfWork.bulkCreate(people, "Person");

// add other operations
// ...

// use unitOfWork.execute() to run the transactio

Person class:

@reflector
class Person {
 String name;
 int age;
 String objectId;
}

Code to add a "create" operation to a transaction:

final unitOfWork = UnitOfWork();

final person1 = Person()
 ..name = "Joe"
 ..age = 25;

final person2 = Person()
 ..name = "Mary"
 ..age = 32;

final person3 = Person()
 ..name = "Bob"
 ..age = 22;

final people = [person1, person2, person3];

unitOfWork.bulkCreate(people);

// add other operations
// ...

// use unitOfWork.execute() to run the transaction

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 new records must be saved.
objects	A list containing objects to save in the database. Objects properties must match the names of the table columns. The objects must not have the objectId property.
return operation reference	Optional parameter. When this box is checked, after this operation is executed its reference is returned in the response as an object containing transaction details.

Consider the structure of the data table called Person:

To create a transaction and save new objects to 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 "Find", "Bulk Create", "Bulk Upsert", "Bulk Update" and "Bulk Delete".  This topic describes the "Bulk Create" operation type used in conjunction with these additional Codeless blocks. The example below shortly highlights how this block accepts the "Bulk Create" 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 Create" type.

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

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 saves a single object to 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 saved new objects to the data table: