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

Custom Class ApproachDictionary/Map Approach

Objective-CSwift

- (void)saveWithEntity:(id)entity isUpsert:(BOOL)isUpsert responseHandler:^(NSDictionary<NSString *,id> *)responseHandler errorHandler:^(Fault *)errorHandler;

func save(entity: Any, isUpsert: Bool, responseHandler: ((Any) -> Void)!, errorHandler: ((Fault) -> Void)!)

Objective-CSwift

- (void)saveWithEntity:(NSDictionary<NSString *,id> *)entity isUpsert:(BOOL)isUpsert responseHandler:^(NSDictionary<NSString *,id> *)responseHandler errorHandler:^(Fault *)errorHandler;

func save(entity: [String : Any], isUpsert: Bool, responseHandler: (([String : Any]) -> Void)!, errorHandler: ((Fault) -> Void)!)

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.

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.

Custom Class ApproachDictionary/Map Approach

Objective-CSwift

@interface Person : NSObject

@property NSString* objectId;
@property NSString* email;
@property NSInteger age;

@end

// -----------------

Person *person = [Person new];
person.objectId = @"297BEFCD-2992-4724-8AAC-F3EB00E413D2";
person.email = @"peter@yourmail.com";
person.age = 55;

[[Backendless.shared.data of:[Person class]] saveWithEntity:person isUpsert:true responseHandler:^(NSDictionary *savedPerson) {
    // handle response
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

@objcMembers class Person: NSObject {
    var objectId: String?
    var objectId: email?
    var age = 0
}

// -----------------

let person = Person()
person.objectId = "297BEFCD-2992-4724-8AAC-F3EB00E413D2"
person.email = "peter@yourmail.com"
person.age = 55

Backendless.shared.data.of(Person.self).save(entity: person, isUpsert: true, responseHandler: { savedPerson in
    // handle response
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

Objective-CSwift

NSDictionary *person = @{@"objctId": @"297BEFCD-2992-4724-8AAC-F3EB00E413D2", @"email": @"peter@yourmail.com", @"age": @55};

[[Backendless.shared.data ofTable:@"Person"] saveWithEntity:person isUpsert:true responseHandler:^(NSDictionary *savedPerson) {
    // handle response
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

let person = ["objectId": "297BEFCD-2992-4724-8AAC-F3EB00E413D2", "email": "peter@yourmail.com", "age": 55]

Backendless.shared.data.ofTable("Person").save(entity: person, isUpsert: true, responseHandler: { savedPerson in
    // handle response
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

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