Transaction API¶
| Block |
Block name / Description |
|---|---|
 |
Create transaction object. Transaction object should be populated with operations first - use the "Add Operations to Transaction" block. After that use the "Run Transaction" block to execute the transaction. The isolation parameter defines the behavior of the transaction. To read more about supported isolation modes see Transaction Isolation section of the JS SDK guide. |
 |
Adding an operation to a transaction. This blocks adds transaction operations to the transaction. Transaction executes added operations in the same order they are added. If an operation fails, the entire transaction rolls back - this means any changes made by the operations prior to the failed one will be canceled out. Result of a previous operation may be referenced in the subsequent ones through "operation reference" |
 |
Obtains a reference to an operation. Operation reference is used when the result of one operation must be used as an input parameter in another operation. This block should be used when the entire result of the operation should be referenced. In cases when only a "subvalue" is needed, such as an element of a result collection of a specific property, use the "Get Operation Result Reference" block. |
 |
Obtains a reference to a "subvalue" from operation reference. This is similar to the block shown above with one major difference - it retrieves a subvalue of a result. For instance, suppose the entire result of a collection of objects returned by the "Find" Operation block. If another operation needs to reference only a specific element of that collection, this block can retrieve it by specifying the index argument. The block supports the following combinations:
|
 |
Runs transaction on the server. Runs the transaction identified by a variable (it is expected in the transaction connector). If an operation included in the transaction fails, all performed changes are rolled back and the transaction results in an error. If the throw error checkbox is selected, the error must be handled through the Try/Catch block. Otherwise, the returned result must be checked with the Is Transaction Successful block. |
 |
Get operation result Retrieves result of an individual operation after the transaction finished processing. Make sure to use this block after the Run Transaction block. |
 |
Returns transaction result object, if transaction is successful. Returns transaction result object if the transaction ran successfully. The connector must be the result of the Run Transaction block. The object returned by this block has property names that are individual operation IDs and the values are results of individual operations. |
 |
Returns the error the transaction resulted in. Returns transaction error object if the transaction failed. |
 |
Checks if the transaction execution was successful. Returns true if the transaction completed successfully, false otherwise. |
 |
Retrieves objects from a database table. Runs a database retrieval operation. Result of the operation (the entire collection of objects or individual ones) can be used in subsequent operations. |
 |
Saves new object in the database. Saves object in the specified database table. |
 |
Updates an existing object in the database. Saves existing object (the update operation) in the specified database table. |
 |
Updates an existing object in the database. Updates an object from one of a previous operations in the same transaction. The changes connector must contain an object that describes the changes. For example, if the changes connector object has the following:  The update operation will save "Joe" in the name column for all referenced objects. |
 |
Updates an existing object in the database. Performs database updates of a single object that is a result of a previous operation. The change is for a specific property identified by the property name connector. The value to be saved in the database for the property is property value. |
 |
Deletes an object in the database. |
 |
Deletes an object in the database. The object is a result of a previous operation in the same transaction. |
 |
Saves one or more new objects in the database. Creates one of more objects in the specified table in the database. The result of the operation is a collection of objectId values (as strings). |
 |
Updates one or more objects in the database. Updates objects in the specified table in the database. The objects to change are identified by a query attached to the where connector. Objects will be updated with the data provided in the changes connector - it expects an object. The changes object should contain property names with corresponding values that will be used in the update. |
 |
Updates one or more objects in the database. Objects to update are from the result of a previous operation in the same transaction. |
 |
Deletes one or more objects in the database. Deletes one or more objects in the specified database table. Objects to delete are identified by a where clause condition attached to the where connector. |
 |
Deletes one or more objects in the database. Objects to delete are from the result of a previous operation in the same transaction. |
 |
Sets one or more child objects as related for the parent object. This operation creates a relationship between a parent and child objects. If the parent object already has other related children, the relationship is reset - the child objects identified in this operation become the sole children of the parent. The parent object must be connected to the parent connector. The object must reside in a table identified in the table nameconnector. The relationship column must be present in the specified table, the column name is identified by the column name connector. The children connector may contain an explicit list of children or a reference to one of the previous operations that returned a collection of objects (or a collection of objectIdvalues). |
 |
Adds one or more child objects to an existing relationship in the parent object. This operation adds child objects to a parent in a relationship. Unlike the "Set Relation" Operation shown above, which removes any existing child objects and sets the provided children, this operation adds the children from the children connector to the existing ones in the database. The children connector may contain an explicit list of children or a reference to one of the previous operations that returned a collection of objects (or a collection of objectIdvalues). |
 |
Deletes a relationship between the parent object and the specified child objects. This operation deletes child objects from a parent in a relationship. The operation does not delete the actual objects, neither it deletes the relationship column. The operation simply disconnects the child objects from the parent. The parent object must be connected to the parent connector. The object must reside in a table identified in the table nameconnector. The relationship column must be present in the specified table, the column name is identified by the column name connector. The children connector may contain an explicit list of children or a reference to one of the previous operations that returned a collection of objects (or a collection of objectIdvalues). |
Examples¶
Save parent/child objects, create relation¶
This example demonstrates how a single transaction can be used to accomplish the following:
- Save the parent object in the database
- Save the child objects in the database
- Create a relation between the parent and the children
It is important that the schema for both tables used in the example is created before the transaction is executed. This is what the schema looks like:
Order table schema:
OrderItem table schema:
Transaction result:
{
"success": true,
"error": null,
"results": {
"set_relationOrder1": {
"result": 2,
"operationType": "SET_RELATION"
},
"createOrderItemsOp": {
"result": [
"43925FB1-1F7A-41E6-B8C5-0FB5F8566FE3",
"91026D1C-217E-4078-AEDD-2DBDBD10BF7E"
],
"operationType": "CREATE_BULK"
},
"createOrderOp": {
"result": {
"amount": 189.2,
"orderId": "061821-CV1",
"created": 1624004146000,
"___class": "Order",
"ownerId": null,
"updated": null,
"objectId": "3A04D2B6-44D3-4A08-AC56-A316366C5069"
},
"operationType": "CREATE"
}
}
}
Retrieve an object and update its property¶
Transaction result:
{
"success": true,
"error": null,
"results": {
"updateCountry1": {
"result": {
"IndepYear": 1947,
"created": 1623928473000,
"LifeExpectancy": 62.5,
"GNP": 447114,
"HeadOfState": "Kocheril Raman Narayanan",
"ownerId": null,
"LocalName": "Bharat/India",
"Name": "India",
"GovernmentForm": "Federal Republic",
"Continent": "Asia",
"SurfaceArea": 3287263,
"___class": "Country",
"Region": "Southern and Central Asia",
"Population": 1339000000,
"updated": 1623937978000,
"objectId": "IND"
},
"operationType": "UPDATE"
},
"findCountry1": {
"result": [
{
"IndepYear": 1947,
"created": 1623928473000,
"LifeExpectancy": 62.5,
"GNP": 447114,
"HeadOfState": "Kocheril Raman Narayanan",
"ownerId": null,
"LocalName": "Bharat/India",
"Name": "India",
"GovernmentForm": "Federal Republic",
"Continent": "Asia",
"SurfaceArea": 3287263,
"___class": "Country",
"Region": "Southern and Central Asia",
"Population": 1013662000,
"updated": null,
"objectId": "IND"
}
],
"operationType": "FIND"
}
}
}
Setting a Relation¶
The example below performs an operation of linking objects from the Gift table to an object from the Person table through a column called wishlist. This is what the parent table looks like:
You can see the wishlist column, which is a one-to-many relation with the Gift table shown below:
The examples are organized by two levels: first is how the parent object is represented in the program, then by the type of the child collection.
The parent object is represented as:
** The child objects are represented as**
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```
=== "Objects"
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```
=== "Op. Result"
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"findGift1": {
"result": [
{
"price": 399,
"created": 1623987958000,
"name": "Apple iPad",
"___class": "Gift",
"ownerId": null,
"updated": null,
"objectId": "0CED763F-13FB-4F29-96AD-F96FDE819925"
},
{
"price": 23,
"created": 1623987916000,
"name": "Selfie Stick",
"___class": "Gift",
"ownerId": null,
"updated": 1623987926000,
"objectId": "103856CD-08A3-4E8E-8236-1F397DD0E193"
},
{
"price": 899,
"created": 1623987949000,
"name": "Apple iPhone",
"___class": "Gift",
"ownerId": null,
"updated": null,
"objectId": "4441FC8C-9E2A-4A49-AAF3-BB7B2DD19BB9"
}
],
"operationType": "FIND"
},
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```
** The child objects are represented as**
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```
=== "Objects"
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```
=== "Operation Result"
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"findGift1": {
"result": [
{
"price": 399,
"created": 1623987958000,
"name": "Apple iPad",
"___class": "Gift",
"ownerId": null,
"updated": null,
"objectId": "0CED763F-13FB-4F29-96AD-F96FDE819925"
},
{
"price": 23,
"created": 1623987916000,
"name": "Selfie Stick",
"___class": "Gift",
"ownerId": null,
"updated": 1623987926000,
"objectId": "103856CD-08A3-4E8E-8236-1F397DD0E193"
},
{
"price": 899,
"created": 1623987949000,
"name": "Apple iPhone",
"___class": "Gift",
"ownerId": null,
"updated": null,
"objectId": "4441FC8C-9E2A-4A49-AAF3-BB7B2DD19BB9"
}
],
"operationType": "FIND"
},
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```
** The child objects are represented as**
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"findPerson1": {
"result": [
{
"created": 1623987881000,
"name": "Josh Doe",
"___class": "Person",
"ownerId": null,
"updated": 1623987888000,
"objectId": "2F3F04F0-BB65-45F6-B9E1-D9D656440C2A",
"age": 36
}
],
"operationType": "FIND"
},
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```
=== "Objects"
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"findPerson1": {
"result": [
{
"created": 1623987881000,
"name": "Josh Doe",
"___class": "Person",
"ownerId": null,
"updated": 1623987888000,
"objectId": "2F3F04F0-BB65-45F6-B9E1-D9D656440C2A",
"age": 36
}
],
"operationType": "FIND"
},
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```
=== "Operation Result"
Transaction result:
``` json
{
"success": true,
"error": null,
"results": {
"findGift1": {
"result": [
{
"price": 399,
"created": 1623987958000,
"name": "Apple iPad",
"___class": "Gift",
"ownerId": null,
"updated": null,
"objectId": "0CED763F-13FB-4F29-96AD-F96FDE819925"
},
{
"price": 23,
"created": 1623987916000,
"name": "Selfie Stick",
"___class": "Gift",
"ownerId": null,
"updated": 1623987926000,
"objectId": "103856CD-08A3-4E8E-8236-1F397DD0E193"
},
{
"price": 899,
"created": 1623987949000,
"name": "Apple iPhone",
"___class": "Gift",
"ownerId": null,
"updated": null,
"objectId": "4441FC8C-9E2A-4A49-AAF3-BB7B2DD19BB9"
}
],
"operationType": "FIND"
},
"findPerson1": {
"result": [
{
"created": 1623987881000,
"name": "Josh Doe",
"___class": "Person",
"ownerId": null,
"updated": 1623987888000,
"objectId": "2F3F04F0-BB65-45F6-B9E1-D9D656440C2A",
"age": 36
}
],
"operationType": "FIND"
},
"set_relationPerson1": {
"result": 3,
"operationType": "SET_RELATION"
}
}
}
```