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¶
PUT
Endpoint URL¶
The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.
https://xxxx.backendless.app/api/data/<table-name>/upsert
where:
| Argument | Description |
|---|---|
<table-name> |
Name of the data table where the operation must apply changes. |
Request Headers¶
None.
Request Body¶
Must be an object containing the mandatory "objectId" property, representing a unique identifier of a record stored in the database or a record that will be inserted into the database. Furthermore, the object properties must match the column names of the target data table.
// Sample object
{
"objectId":"297BEFCD-2992-4724-8AAC-F3EB00E413D2",
"email":"peter@yourmail.com",
"age":53
}
Response Body¶
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.
curl --location --request PUT 'https://xxxx.backendless.app/api/data/Person/upsert' \
--header 'Content-Type: application/json' \
--data-raw '{
"objectId":"297BEFCD-2992-4724-8AAC-F3EB00E413D2",
"email":"peter@yourmail.com",
"age": 55
}'
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".
