Product SiteDocumentation Site

Chapter 7. JSON updates

7.1. JSON udpate primitives
7.2. Update syntax: new updating expressions
7.2.1. Deleting expressions
7.2.2. Inserting expressions
7.2.3. Renaming expressions
7.2.4. Replacing expressions
7.2.5. Appending expressions
JSONiq introduces new update primitives for updating Objects and Arrays. Update primitives can be generated with new JSONiq updating expressions.
An individual function may create an invalid JSON instance; however, an updating query must produce a valid JSON instance once the entire query is evaluated, or an error is raised and the entire update fails, leaving the instance in its original state.

7.1. JSON udpate primitives

The following new update primitives are introduced.
  • jupd:insert-into-object($o as object(), $p as object())
    Inserts all pairs of the object $p into the object $o.
  • jupd:insert-into-array($a as array(), $i as xs:integer, $c as item()*)
    Inserts all items in the sequence $c before position $i into the array $a.
  • jupd:delete-from-object($o as object(), $s as xs:string*)
    Removes the pairs the names of which appear in $s from the object $o.
  • jupd:delete-from-array($a as array(), $i as xs:integer)
    Removes the item at position $i from the array $a (causes all following items in the array to move one position to the left).
  • jupd:replace-in-array($a as array(), $i as xs:integer, $v as item())
    Replaces the item at position $i in the array $a with the item $v (do nothing if $i is not comprised between 1 and jdm:size($a)).
  • jupd:replace-in-object($o as object(), $n as xs:string, $v as item())
    Replaces the value of the pair named $n in the object $o with the item $v (do nothing if there is no such pair).
  • jupd:rename-in-object($o as object(), $n as xs:string, $p as xs:string)
    Renames the pair originally named $n in the object $o as $p (do nothing if there is no such pair).
Update primitives within a PUL are applied with strict snapshot semantics. For examples, the positions are resolved against the array before the updates. Names are resolved on the object before the updates.
In the middle of a program, several PULs can be produced against the same snapshot. They are then merged with upd:mergeUpdates, which is extended as follows.
  • Several deletes on the same object are replaced with a unique delete on that object, with a list of all selectors (names) to be deleted, where duplicates have been eliminated.
  • Several deletes on the same array and selector (position) are replaced with a unique delete on that array and with that selector.
  • Several inserts on the same array and selector (position) are equivalent to a unique insert on that array and selector with the content of those original inserts appended in an implementation-dependent order (like XQUF).
  • Several inserts on the same object are equivalent to a unique insert where the objects containing the pairs to insert are merged. An error jerr:JNUP0005 is raised if a collision occurs.
  • Several replaces on the same object or array and with the same selector raise an error jerr:JNUP0009.
  • Several renames on the same object and with the same selector raise an error jerr:JNUP0010.
  • If there is a replace and a delete on the same object or array and with the same selector, the replace is omitted in the merged PUL.
  • If there is a rename and a delete on the same object or array and with the same selector, the rename is omitted in the merged PUL.
At the end of an updating program, the resulting PUL is applied with upd:applyUpdates, which is extended as follows:
  • First, before applying any update, each update primitive (except the jupd:insert-into-object primitives, which do not have any target) locks onto its target by resolving the selector on the object or array it updates. If the selector is resolved to the empty sequence, the update primitive is ignored in step 2. After this operation, each of these update primitives will contain a reference to either the pair (for an object) or the value (for an array) on or relatively to which it operates
  • Then each update primitive is applied, using the target references that were resolved at step 1. The order in which they are applied is not relevant and does not affect the final instance of the data model. After applying all updates, an error jerr:JNUP0006 is raised upon pair name collision within the same object.