upsertData()

Overview

public struct function upsertData(
      required string  objectName             
    , required struct  data                   
    , required array   matchColumns           
    ,          array   updateColumns          
    ,          boolean insertManyToManyRecords = false
    ,          boolean isDraft                 = false
    ,          boolean useVersioning           = automatic
    ,          numeric versionNumber           = 0
    ,          boolean clearCaches             = Defaults to whether query caching is enabled or not for this object
    ,          numeric timeout                
)

Inserts a record or updates an existing record when a matching unique key already exists. Uses a single atomic database upsert statement where the adapter supports it, avoiding read-then-write races that can occur with separate update and insert calls.

Arguments

Name	Type	Required	Description
objectName	string	Yes	Name of the object whose record you want to upsert
data	struct	Yes	Structure of data to insert or update. Keys should map to properties on the object. All match columns must be present.
matchColumns	array	Yes	Array of property names whose combined values identify an existing record via a unique index
updateColumns	array	No	Array of property names to update when a matching record already exists. Defaults to all data properties that are not match columns.
insertManyToManyRecords	boolean	No (default=false)	Whether or not to insert multiple relationship records for properties that have a many-to-many relationship
isDraft	boolean	No (default=false)	Whether or not the record change is a draft change
useVersioning	boolean	No (default=automatic)	Whether or not to use the versioning system with the upsert
versionNumber	numeric	No (default=0)	If using versioning, specify a version number to save against
clearCaches	boolean	No (default=Defaults to whether query caching is enabled or not for this object)	Whether or not to clear caches related to the object
timeout	numeric	No	Timeout, in seconds, of the main upsert DB query

Examples

result = presideObjectService.upsertData(
objectName   = "system_config"
, data         = { category="myapp", setting="mysetting", value="myvalue", site="", tenant_id="" }
, matchColumns = [ "category", "setting", "site", "tenant_id" ]
);
// result.id       = record id
// result.inserted = true when a new record was created, false when an existing record was updated