Upsert 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 value.

Method

Blocking API:

Using Java MapCustom Class

public Map save( Map entity, boolean isUpsert ) throws BackendlessException

public T save( final T entity, boolean isUpsert ) throws BackendlessException

Non-blocking API:

Using Java MapCustom Class

public void save( Map entity, boolean isUpsert, AsyncCallback<Map> responder )

public void save( final T entity, boolean isUpsert, final AsyncCallback<T> responder )

where:

Argument	Description
entity	Required parameter. which is used for the upsert operation. It must contain the objectId property with the value identifying an existing object or a new object that must be inserted in the data table.
isUpsert	Optional parameter. Boolean value. When this property is set to true, the operation tries finding an existing object in the data table to update it. If it can't find the object, it creates (inserts) a new one in the data table.

Return Value

An object that was updated or inserted into the data table.

Example

The example below upserts an object in the "Person" table. It does it by checking if the object with the specified "objectId" already exists. In case it finds the object, it updates it with the new "age" and "email" values. If the object does not exist, the operation inserts a new object into the data table containing the specified "objectId" and the specified property values.

Blocking API:

Using Java MapCustom Class

Map<String, Object> entity = new HashMap<>();
entity.put( "name", "Peter" );
entity.put( "email", "peter@yourmail.com" );
entity.put( "age", 55 );
entity.put( "objectId", "297BEFCD-2992-4724-8AAC-F3EB00E413D2" );

Map person = Backendless.Data.of( "Person" ).save( entity, true );

Person entity = new Person();
entity.setName( "Peter" );
entity.setEmail( "peter@yourmail.com" );
entity.setAge( 55 );
entity.setObjectId( "297BEFCD-2992-4724-8AAC-F3EB00E413D2" );

Person person = Backendless.Data.of( Person.class ).save( entity, true );

Non-blocking API:

Using Java MapCustom Class

Map<String, Object> entity = new HashMap<>();
entity.put( "name", "Peter" );
entity.put( "email", "peter@yourmail.com" );
entity.put( "age", 55 );
entity.put( "objectId", "297BEFCD-2992-4724-8AAC-F3EB00E413D2" );

Backendless.Data.of( "Person" ).save( entity, true, new AsyncCallback<Map>()
{
 @Override
 public void handleResponse( Map response )
 {
 // result handling logic
 }

 @Override
 public void handleFault( BackendlessFault fault )
 {
 // error handling logic
 }
} );

Person entity = new Person();
entity.setName( "Peter" );
entity.setEmail( "peter@yourmail.com" );
entity.setAge( 55 );
entity.setObjectId( "297BEFCD-2992-4724-8AAC-F3EB00E413D2" );

Backendless.Data.of( Person.class ).save( entity, true, new AsyncCallback<Person>()
{
 @Override
 public void handleResponse( Person response )
 {
 // result handling logic
 }

 @Override
 public void handleFault( BackendlessFault fault )
 {
 // error handling logic
 }
} );

Codeless Reference

where:

Argument	Description
table name	Name of the data table where the operation must apply changes.
object	The object may 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 returns an updated or newly inserted object.

Returns an object that was updated or inserted into the data table.

Consider the following records in the Person data table:

The example below uses the "objectId" value to search the "Person" data table for an object that may exist. In case it finds the object, it just updates it with new "age" and "email" values. If the object does not exist, the operation inserts a new object into the data table containing the specified "objectId" and other values.

The output will look as shown below after the Codeless logic runs. The value in the "age" column was increased from 54 to 55, and the "email" was changed from "peter@yahoo.com" to "peter@yourmail.com".