Skip to content

Transaction API

Block
Block name / Description
create-transaction-block
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.
add-op-to-tx-block
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"
get-op-ref-block
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.
get-op-result-ref
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:
  • index only - retrieves element at the index from a collection returned by the references operation.
  • property name only - retrieves property value for the specified property name from the result of the referenced operation. In this case the result must be a single object (not a collection).
  • both index and property name - retrieves object at the specified index from the collection returned from the referenced operation. Then from the retrieved at the index, retrieves property value using the specified property name.
run-tx-block
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-op-result-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.
get-tx-result-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.
get-tx-error-block
Returns the error the transaction resulted in.
Returns transaction error object if the transaction failed.
is-tx-successful-block
Checks if the transaction execution was successful.
Returns true if the transaction completed successfully, false otherwise.
find-op-tx-block
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.
create-op-tx-block
Saves new object in the database.
Saves object in the specified database table.
update-op-tx-block
Updates an existing object in the database.
Saves existing object (the update operation) in the specified database table.
update-op-tx-prev-opref-block
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:
changes-in-update-tx
The update operation will save "Joe" in the name column for all referenced objects.
update-op-tx-prev-op-specific-prop-block
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.
delete-op-tx-block
Deletes an object in the database.
delete-op-tx-prev-op-ref-block
Deletes an object in the database. The object is a result of a previous operation in the same transaction.
bulk-create-tx-block
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).
bulk-update-tx-block
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.
bulk-update-tx-prev-op-ref-block
Updates one or more objects in the database. Objects to update are from the result of a previous operation in the same transaction.
bulk-delete-tx-block
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.
bulk-delete-tx-prev-op-ref-block
Deletes one or more objects in the database. Objects to delete are from the result of a previous operation in the same transaction.
set-relation-tx-block
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).
add-relation-tx-block
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).
delete-rel-tx-block
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:

order-table-schema-tx

OrderItem table schema:

orderitem-table-schema-tx

createobjects-setrelation

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

find-then-update-in-tx

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:

person-table-parent.zoom70

You can see the wishlist column, which is a one-to-many relation with the Gift table shown below:

gifts-table-children.zoom70

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

set-relation-parent-objectid-children-objectids

Transaction result:

{
  "success": true,
  "error": null,
  "results": {
    "set_relationPerson1": {
      "result": 3,
      "operationType": "SET_RELATION"
    }
  }
}

set-relation-parent-objectid-children-objects

Transaction result:

{
  "success": true,
  "error": null,
  "results": {
    "set_relationPerson1": {
      "result": 3,
      "operationType": "SET_RELATION"
    }
  }
}

set-relation-parent-objectid-children-opresult

Transaction result:

{
  "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

set-relation-parent-object-children-objectids

Transaction result:

{
  "success": true,
  "error": null,
  "results": {
    "set_relationPerson1": {
      "result": 3,
      "operationType": "SET_RELATION"
    }
  }
}

set-relation-parent-object-children-objects

Transaction result:

{
  "success": true,
  "error": null,
  "results": {
    "set_relationPerson1": {
      "result": 3,
      "operationType": "SET_RELATION"
    }
  }
}

set-relation-parent-object-children-opresult

Transaction result:

{
  "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

set-relation-parent-opresult-children-objectids

Transaction result:

{
  "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"
    }
  }
}

set-relation-parent-opresult-chhildren-objects

Transaction result:

{
  "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"
    }
  }
}

set-relation-parent-opresult-children-opresult

Transaction result:

{
  "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"
    }
  }
}