Merge Insert Metadata Action

When accessing data from a remote system that acts as the "system of record" for certain data, you can acquire the data and do the following using the MERGE_INSERT metadata action tag:

  • (If the remote data is new) Insert new local rows.
  • (If the remote data has already been inserted, but needs to be updated) Update local rows.

This action is also referred to as "upsert". With the SysUtility.restPut interface, you can use options in the @metadata tag.

The MERGE_INSERT metadata action tag is a combination of the INSERT, UPDATEthe LOOKUP metadata action tag. The key is used to find a record as described in the , using de-aliased resource attribute names. If a single record is found, this record is updated with provided values. If a record is not found, the provided values are used to insert a new record. Checksum is not required and is implicitly "override".

For more information about the INSERT, UPDATE, and LOOKUP metadata actions, see Complex Transaction Processing.

Insert or Update using PUT

{"@metadata" : {"action":"MERGE_INSERT", "key":"name"}, "name":"David 1", "some_val":199}

Insert or update using id field, name field updated

{"@metadata" : {"action":"MERGE_INSERT", "key":"id"}, "id": 10, "name":"David 2", "some_val":199}

Insert or update using multiple fields id and name field updated using an array of field names

{"@metadata" : {"action":"MERGE_INSERT", "key":["id","name"]}, "id": 10, "name":"David 2", "some_val":199}

Insert or update using primary key (id field), name field updated

{"@metadata" : {"action":"MERGE_INSERT"}, "id": 10, "name":"David 2", "some_val":199}

{"@metadata" : {"action":"MERGE_INSERT", "key":"name"}, "name":"David 2", "some_val":200}

Combine Action Lookup and merge_insert

The following example shows an upsert on the parent and a lookup of the product name in the items using a resource from the Demo sample application:

PUT: http://localhost:8080/rest/default/demo/v1/OrderLookupParent
{
    "@metadata": {"action":"INSERT"},
    "Customer": {
       "@metadata": { "action":"MERGE_INSERT", "key":["Name","credit_limit"]},
       "Name":"Alpha and Son 2",
       "credit_limit": 1000
    },
    "Items":[
           {
           "Product":
           {
              "@metadata": {"action":"LOOKUP", "key":"ProductName"},
              "ProductName":"Hammer"
           },
              "Quantity": 1
           }
     ]
}

See the sample MergeInsertExample.