Transaction
Transactions are the unique way to apply a list of operations to the datacloud. A transaction can be merged into another transaction so that both are executed as a single set of operations.
All the operations for a transaction are executed atomically. Either all operations succeed, or none is applied.
There are 5 types of basic operations :
- Create instance: create a node in the database with specified properties.
- Update instance property: update an existing node in the database.
- Delete instance: delete a node from the database. Delete only works if all the relations are removed too. Cascade delete can be activated.
- Create relation: create a relation of a specific type between 2 existing node.
- Delete relation: remove the specified relation between 2 specified nodes.
In most cases, we apply the Transactions operations using the "execute()" method. The transaction size is limited but in real-time. It notifies observers of the data in real-time.
Larger transactions with big set of operations (batch updates) must be executed using "executeAsLarge()" method. However, no notification will be generated.
Callbacks can be registered on transaction using "afterExecution()" method. They are executed once the transaction is applied.
Example of transaction:
const tx = new Transaction(true);
const myNewInstanceTag = tx.create(<myModelTag>);
tx.update(myNewInstanceTag, <myPropertyTag>, <myPropertyValue>)
.execute()
.then(() => {
// success tx case
})
.catch((err) => {
// error during tx case
})
Concurrency transactions do not guarantee their execution order.
Constructors
new Transaction()
new Transaction(persist?): Transaction
Create a new transaction object.
Parameters
| Parameter | Type | Description |
|---|---|---|
persist? | boolean | if set to true, will persist to the data source the objects Transaction.create created in that transaction. (Default = true) |
Returns
Transaction
Methods
from()
static from($): Transaction
Start a transaction using an existing transaction in the provided context or a new one if there is none.
Parameters
| Parameter | Type | Description |
|---|---|---|
$ | BrickContext | context in which the transaction executes |
Returns
Transaction
transaction
process()
static process($, transaction): Promise<boolean>
Execute a given transaction if there is no open transaction in the context.
Parameters
| Parameter | Type | Description |
|---|---|---|
$ | BrickContext | context |
transaction | Transaction | transaction to process |
Returns
Promise<boolean>
boolean indicating if the argument transaction has been processed
afterExecution()
afterExecution(callback): this
Set a callback to be executed after all the operations in the transaction were executed successfully
Parameters
| Parameter | Type | Description |
|---|---|---|
callback | (success, message?) => void | the callback to be executed |
Returns
this
this transaction
create()
create(
model,
properties?,
source?,
tag?): string
Create a new instance.
A custom map can specify property values for the instance.
A source can be the orchestrator ({PredefinedDataSource.SERVER}), local ({PredefinedDataSource.SELF}) or an external data source (tag of DBConnector). The source is where the object is persisted and its true value outside local scopes.
Parameters
| Parameter | Type | Description |
|---|---|---|
model | InstanceOrTag | tag of the model of the instance to be created |
properties? | Map<InstanceOrTag, any> | custom map from tag to their value for properties of the instance to be created |
source? | string | optional source of the instance |
tag? | string | optional tag of the instance to be created and must be unique |
Returns
string
the tag of the instance to be created
createRelation()
createRelation(
relation,
from,
to): this
Create relation between two instances
Parameters
| Parameter | Type | Description |
|---|---|---|
relation | InstanceOrTag | tag of the relation to be created |
from | InstanceOrTag | tag of the ORIGIN instance of the relation |
to | InstanceOrTag | tag ofo the DESTINATION instance of the relation |
Returns
this
this transaction with the create relation operation registered
delete()
delete(instance): this
Delete an instance
Parameters
| Parameter | Type | Description |
|---|---|---|
instance | InstanceOrTag | tag of the instance to be deleted |
Returns
this
this transaction
deleteAllRelations()
deleteAllRelations(relation, origin): this
Delete any number of the relation starting from specified node.
The specified node might be the origin or (exclusive) the destination of the relation.
For the relations :
- a - [rel1] -> b,
- c - [inverseRel(rel1)] -> a,
- a - [rel1] -> d,
- a - [rel2] -> d
tx.deleteAllRelation(rel1, a) will remove the first and third relations
Parameters
| Parameter | Type | Description |
|---|---|---|
relation | Relation<any, any> | deleted relation, indicates relation tag and direction |
origin | InstanceOrTag | starting node |
Returns
this
deleteRelation()
deleteRelation(
relation,
from,
to): this
Delete a relation between two specified instances.
The relation is only deleted for the relation parameter direction.
Parameters
| Parameter | Type | Description |
|---|---|---|
relation | InstanceOrTag | tag of the relation to be deleted |
from | InstanceOrTag | origin instance tag |
to | InstanceOrTag | destination instance tag |
Returns
this
this transaction
execute()
execute(): Promise<TransactionResult>
Execute atomically the transaction at the data sources. Return the transaction result if succeeds.
Returns
Promise<TransactionResult>
promise resolving with the corresponding TransactionResult if the transaction succeeds, rejecting if the transaction fails
executeAsLarge()
executeAsLarge(): Promise<TransactionResult>
Execute atomically a transaction at the data source and returns the transaction result if succeeds.
The large mode sends the transaction over HTTP, this has the following incidence:
- Quicker processing of transaction
- Allows transactions with no limit of size
- Cannot be used when logged as Guest
Returns
Promise<TransactionResult>
promise resolving with the corresponding TransactionResult if the transaction succeeds, rejecting if the transaction fails.
getId()
getId(): string
Get the transaction id attached to this transaction
Returns
string
this transaction id
merge()
merge(otherTransaction): this
Add all operations of another transaction into this transaction
Parameters
| Parameter | Type | Description |
|---|---|---|
otherTransaction | Transaction | the other transaction to add operations from |
Returns
this
this transaction
model()
model(tag): string
Retrieve the tag of the model of the instance tag from the created instances in this transaction or from the local database.
Parameters
| Parameter | Type | Description |
|---|---|---|
tag | InstanceOrTag | the instance to find the model of |
Returns
string
the tag of the model of the given instance
multiUpdate()
multiUpdate(instance, properties): this
Update multiple properties of a single instance
Parameters
| Parameter | Type | Description |
|---|---|---|
instance | InstanceOrTag | tag of the instance to be updated |
properties | Map<InstanceOrTag, any> | map of properties to update |
Returns
this
this transaction
persist()
persist(instance, persist?): this
Set the specified instance to be persisted or not in this transaction. Default value of persist is true.
Parameters
| Parameter | Type | Description |
|---|---|---|
instance | InstanceOrTag | the instance to be persisted |
persist? | boolean | determine if the specified instance should be persisted or not (true by default). |
Returns
this
this transaction
persistInstance()
persistInstance(instance, persist?): this
Change the persistence mode for a single instance in this transaction
Parameters
| Parameter | Type | Description |
|---|---|---|
instance | InstanceOrTag | the instance to be persisted |
persist? | boolean | the persisting mode |
Returns
this
this transaction
Deprecated
use Transaction.persist instead
setSource()
setSource(source): this
Change the source of all instances created in this transaction
source can be specified as :
- a predefined source type {PredefinedDataSource}
- an external data source (Tag of a
DBConnector)
The source of a data object is where the object is persisted.
By default, the source is the default source configured in the project.
Parameters
| Parameter | Type | Description |
|---|---|---|
source | string | the new source for instances |
Returns
this
this transaction
update()
update<T>(
instance,
property?,
value?): this
Update the property of an instance
Type Parameters
| Type Parameter |
|---|
T |
Parameters
| Parameter | Type | Description |
|---|---|---|
instance | InstanceOrTag | tag of the instance to be updated |
property? | Property<T> | the property to be updated |
value? | T | the value of the property to be updated to |
Returns
this
this transaction