Upsert a single object

Description

With this operation, you can either update an existing object or insert a new one into the database. To update an existing object, the operation locates it using its objectId value. If the object cannot be found, the operation inserts a new object into the data table with the specified objectId.

Method

// An instance object or an object that must have 
// the ___class: “Person” property containing the name of the data table.
uow.upsert(object: object): OpResult;

// with data table name
uow.upsert(tableName: string, object: object): OpResult;

where:

Argument	Description
tableName	Name of the table where the object will be upserted.
object	Identifies an object that must be upserted in the data table.

The difference between the two signatures is in the type of input parameters they accept and the way they are used.

The Custom Class signature expects an instance of an object that represents the data you want to upsert into the Backendless database. This means you can pass an object that corresponds to a table in the database. The object should have the necessary properties and values that need to be upserted. The method will perform the upsert operation using the provided object and return an OpResult object that contains the result of the operation.

The Map/Dictionary signature accepts the name of the table (tableName) and an  object () that contains the column names and their corresponding values.  The  should have key-value pairs where the key represents the column name and the value represents the value to be upserted. The method will perform the upsert operation using the provided table name and object map and return an OpResult object.

Return Value

This operation returnsan instance of the OpResult class which represents an object containing the result of operation and also it contains an object that was upserted in the database. The OpResult object can be used as an argument in other operations in the same transaction (same UnitOfWork instance). For more information see the Operation Result chapter of this guide.

Example

In the example below, the "objectId" value is utilized to search the "Person" data table for an existing object. If the object is found, it is updated with new "age" and "email" values. If the object does not already exist, the operation inserts a new object into the data table with the specified "objectId" and other associated values.

// create a UnitOfWork instance - it represents a transaction and
// will accumulate all operations in it.
const uow = new Backendless.UnitOfWork();

// Create a person object
const person = {
        email:"alice@yourmail.com",
        age:20,
        objectId:"CB3C9021-E08E-4DB1-AB98-CEC00F83476F"
    }

// add a "upsert" operation to the transaction
// notice the result object will be reused later on
const createPersonOpResult = uow.upsert( "Person", person );

// execute the transaction.
const result = uow.execute()
.then( function( unitOfWorkResult ) {
        console.log("Transaction is successful " + unitOfWorkResult.isSuccess());
});

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 the operation must apply changes.
object	The object must contain the objectId property identifying an existing object in the database that must be updated, or a new object that must be inserted into the data table.
return result	When this box is checked, the operation reference is returned alongside with an updated or a new inserted object.

Returns an object containing the operation result and also a record that was updated or inserted into the data table.

Consider the object stored in the data table called Person:

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

Now lets provide data to properties of the "Upsert" Operation Codeless block. The table name argument must reference the data table where an object is upserted. 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.

You must also specify the value in the objectId property, so that the operation could find the object that must be updated or insert a new object in case the specified one doesn't exist.

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 upserts a single object in 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 upserted an existing object in the data table: