Skip to content

Saving a single object

This is a transaction operation responsible for saving a new object in the database. To add this operation to a Unit Of Work request, use the following operation in the request payload:

{
  "isolationLevelEnum" : "REPEATABLE_READ" | "READ_COMMITTED" | "READ_UNCOMMITTED" | "SERIALZABLE",
  "operations": [
    {
      "operationType": "CREATE",
      "table": "TABLENAME",
      "opResultId": "OPRESULT-ID",
      "payload": {
        "key1":"value",
        "key2": value
      }
    }
  ]
}

where:

Argument                Description
"operationType" The value must be "CREATE", this designates the operation as "saving a single object". The object to save in the database is defined in the "payload" property.
"table" The value must contain the name of the table where the object will be saved. The table must exist in the database before the transaction is executed.
"opResultId" This is an optional property. If present, must contain an Id for this operation. An operation Id is a free-form string that must be unique within the transaction. If the result of this operation is to be used as an input in another operation within the same transaction, the Id will be used to reference the result.
"payload" The value is mandatory. Must contain a JSON object which will be saved in a table identified with the "table" property.

Return Value

This operation returns the object saved in the database. The object will have the objectId property with the value assigned by the server. The object or any of its properties can be used in other operations of the same transaction. For more information see the Operation Result chapter of this guide.

Example

Consider the following example, it demonstrates saving an object into the Person table:

Request:

URL:

POST https://xxxx.backendless.app/api/transaction/unit-of-work
Request header:
Content-Type:application/json
Request body:
{
  "operations": [
    {
      "operationType": "CREATE",
      "table": "Person",
      "opResultId": "createPerson",
      "payload": {
        "name":"Joe",
        "age":25
      }
    }
  ]
}

Response:

{
    "success": true,
    "error": null,
    "results": {
        "createPerson": {
            "type": "CREATE",
            "result": {
                "name": "Joe",
                "age": 25.0,
                "___class": "Person",
                "objectId": "0A7DDC5D-C9D3-8D1C-FF15-F232F2B92500",
                "created": 1586020674000,
                "updated": null,
                "ownerId": null
            }
        }
    }
}

Codeless Reference

data_transactions_save_one_object

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 a new record must be saved.
object An object to save in the database. Object properties must match the names of the table columns. The object 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:

data_transactions_save_one_object_1

To create a transaction and save a new object 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.

data_transactions_save_one_object_6_additional

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.

data_transactions_save_one_object_7_additional

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

data_transactions_save_one_object_8_additional

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 "Create" type.

Now lets provide data to properties of the "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 object argument expects an object, whose properties must match the column names in the Person data table.

data_transactions_save_one_object_9_additional

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).

data_transactions_save_one_object_5_additional

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:

data_transactions_save_one_object_2

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:

data_transactions_save_one_object_10_additional

Furthermore, the operation has saved a new object to the  data table:

data_transactions_save_one_object_3