Primary updating expressions
Update expressions are the visible part of JSONiq Updates in the language. Each primary updating expression contributes an update primitive to the Pending Update List being built.
Nested updates (memory or persistent)
These expressions may appear in a copy-modify-return (transform) expression (for in-memory updates on cloned values), or outside (for persistent updates to an underlying storage).
Inserting values into an object or array
A JSON insert expression is used to insert new pairs into an object. It produces a jupd:insert-into-object update primitive. If the target is not an object, JNUP0008 is raised. If the content is not a sequence of objects, JNUP0019 is raised. These objects are merged prior to inserting the pairs into the target, and JNDY0003 is raised if the content to be inserted has colliding keys.
Example
copy $obj := { "foo" : "bar" }
modify insert json { "bar" : 123, "foobar" : [ true, false ] } into $obj
return $obj
Result: { "foo" : "bar", "bar" : 123, "foobar" : [ true, false ] }
A JSON insert expression is also used to insert a new member into an array. It produces a jupd:insert-into-array update primitive. If the target is not an array, JNUP0008 is raised. If the position is not an integer, JNUP0007 is raised.
Example
copy $arr := { "foo" : [1,2,3,4] }
modify insert json 5 into $arr.foo at position 3
return $arr
Result: { "foo" : [ 1, 2, 5, 3, 4 ] }
Deleting values in an object or array
A JSON delete expression is used to remove a pair from an object. It produces a jupd:delete-from-object update primitive. If the key is not a string, JNUP0007 is raised. If the key does not exist, JNUP0016 is raised.
Example
copy $obj := { "foo" : "bar", "bar" : 123 }
modify delete json $obj.foo
return $obj
Result: { "bar" : 123 }
A JSON delete expression is also used to remove a member from an array. It produces a jupd:insert-from-array update primitive. If the position is not an integer, JNUP0007 is raised. If the position is out of range, JNUP0016 is raised.
Example
copy $arr := [1,2,3,4,5,6]
modify delete json $arr[[3]]
return $arr
Result: [ 1, 2, 4, 5, 6 ]
Renaming a key
A JSON rename expression is used to rename a key in an object. It produces a jupd:rename-in-object update primitive. If the sequence on the left of the dot is not a single object, JNUP0008 is raised. If the new name is not a single string, JNUP0007 is raised. If the old key does not exist, JNUP0016 is raised.
Example 196. JSON rename expression
copy $obj := { "foo" : "bar", "bar" : 123 }
modify rename json $obj.foo as "foobar"
return $obj
Result: { "bar" : 123, "foobar" : "bar" }
Appending values to an array
A JSON append expression is used to add a new member at the end of an array. It produces a jupd:insert-into-array update primitive. JNUP0008 is raised if the target is not an array.
Example 197. JSON append expression
copy $obj := { "foo" : "bar", "bar" : [1,2,3] }
modify append json 4 into $obj.bar
return $obj
Result: { "foo" : "bar", "bar" : [ 1, 2, 3, 4 ] }
Replacing a value in an object or array.
A JSON replace expression is used to replace the value associated with a certain key in an object. It produces a jupd:replace-in-object update primitive. JNUP0007 is raised if the selector is not a single string. If the selector key does not exist, JNUP0016 is raised.
Example
copy $obj := { "foo" : "bar", "bar" : [1,2,3] }
modify replace value of json $obj.foo with { "nested" : true }
return $obj
Result: { "bar" : [ 1, 2, 3 ], "foo" : { "nested" : true } }
A JSON replace expression is also used to replace a member in an array. It produces a jupd:insert-in-array update primitive. JNUP0007 is raised if the selector is not a single position. If the selector position is out of range, JNUP0016 is raised.
Example
copy $obj := { "foo" : "bar", "bar" : [1,2,3] }
modify replace value of json $obj.bar[[2]] with "two"
return $obj
Result: { "foo" : "bar", "bar" : [ 1, "two", 3 ] }
Update expressions at the collection top-level (persistent only)
These expressions may not appear in a copy-modify-return (transform) expression because they can only be used for persistent updates to an underlying storage (document store, data lakehouse, etc).
Creating a collection
This expression creates an update primitive that creates a collection.
Example
create collection table("mytable") with ({"foo":1},{"foo":2}),
create collection delta-file("/path/to/file.delta") with ({"foo":1},{"foo":2})Deleting a collection
This expression creates an update primitive that deletes a collection.
Example
delete collection table("mytable"),
delete collection delta-file("/path/to/file.delta")Inserting into a collection
This expression creates an update primitive that inserts values at the beginning or end of a collection, or before or after specific values in that collection.
Example
insert {"foo":3} first into collection table("mytable"),
insert {"foo":4} last into collection delta-file("/path/to/file.delta"),
insert {"foo":3} before table("mytable")[3] into collection,
insert {"foo":3} after delta-file("/path/to/file.delta")[3] into collectionEditing a value in a collection
This expression creates an update primitive that modifies a value in a collection into the other supplied value.
Example
edit table("mytable")[1] into {"foo":3} in collectionDeleting a value from a collection
This expression creates an update primitive that deletes a specified value from its collection.
Example
delete table("mytable")[1] from collectionLast updated