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¶

Custom ClassUsing Java Map

<E> OpResult upsert( E instance );

OpResult upsert( String tableName, Map<String, Object> objectMap );

where:

Argument	Description
`tableName`	Name of the table where the object will be upserted.
`instance`	Identifies an object to be upserted in the data table.
`objectMap`	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 of a class 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 a Map object (objectMap) that contains the column names and their corresponding values. This provides a more flexible way to specify the data to be upserted without requiring a specific object instance. The objectMap 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.

MapCustom Class

Map<String, Object> person = new HashMap<>();
person.put( "name", "Peter" );
person.put( "email", "peter@yourmail.com" );
person.put( "age", 30 );

UnitOfWork unitOfWork = new UnitOfWork();
unitOfWork.upsert( "Person", person );

UnitOfWorkResult result = unitOfWork.execute();

Person person = new Person();
person.setName( "Peter" );
person.setEmail( "peter@yourmail.com" );
person.setAge( 30 );

UnitOfWork unitOfWork = new UnitOfWork();
unitOfWork.upsert( person );

UnitOfWorkResult result = unitOfWork.execute();

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.