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

// map approach

public Future<Map?> Backendless.data.of('TABLE-NAME').save(Map entity, {bool isUpsert = false});

// class approach

public Future<T?> Backendless.data.withClass<T>().save(T entity, {bool isUpsert = false});

where:

Argument	Description
entity	Required parameter.A dictionary/map 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.
"TABLE-NAME"	Required parameter. String value. Name of the table where the object will be updated/inserted.

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.

// map approach

Map entity = {'objectId' : "297BEFCD-2992-4724-8AAC-F3EB00E413D2", 'email' : 'peter@yourmail.com', "age" : 55};

var result = await Backendless.data.of('Person').save(entity, isUpsert: true);
print(result);

// class approach

Person entity = Person()
  ..email = 'peter@yourmail.com'
  ..age = 55
  ..objectId = '297BEFCD-2992-4724-8AAC-F3EB00E413D2';

var result = await Backendless.data.withClass<Person>().save(entity, isUpsert: true);
print(result);

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