insert one or several nodes inside/after/before a specified node

delete one or several nodes

replace a node (and all its descendants if it is an element) by a sequence of nodes.

replace the contents (children) of a node with a sequence of nodes, or the value of a node with a string value.

rename a node (applicable to elements, attributes and processing instructions) without affecting its contents or attributes.

The disturbing consequence is that you don't see your updates until the end, therefore you cannot build on your changes to make other changes.

An example: suppose you have elements named PERSON. Inside a PERSON there can be a list of BID elements (representing bids made by this person), and you want the BID elements to be wrapped in a BIDS element. But initially the PERSON has no BIDS child.

Initially:

<PERSON id="p0234">
  <NAME>Joe</NAME>
</PERSON>

We want to insert <BID id="b0012">data</BID> to obtain:

<PERSON id="p0234">
  <NAME>Joe</NAME>
  <BIDS>
     <BID id="b0012">data</BID>
  <BIDS>
</PERSON>

Classically, for example using the DOM, we would proceed in two steps:

In XQuery Update this would (incorrectly) be written like this:

declare updating function insert-bid($person, $bid)
{
  if(empty($person/BIDS))
    then insert node <BIDS/> into $person
    else (),
  insert node $bid as last into $person/BIDS
}

Don't try that: it won't work! Why? Because the BIDS element will be created only at the very end, therefore the instruction insert ... as last into $person/BIDS will not find any node matching $person/BIDS, hence an execution error.

So what is a correct way of doing ? We need a self-sufficient solution for each of the two cases:

declare updating function insert-bid($person, $bid)
{
 if(empty($person/BIDS))
   then insert node <BIDS>{$bids}</BIDS> into $person
   else insert node $bid as last into $person/BIDS
}

The pleasant consequence is that the document(s) on which you are working are stable during execution of your script. You can rest assured that you are not sawing the branch you are sitting on. For example you can quietly write:

for $x in collection(...)//X
return delete node $x

This is perfectly predictable and won't stop prematurely. Or you can replicate an element after itself without risking looping forever:

for $x in collection(...)//X
return insert node $x after $x

First of all, let us remember that Updating Expressions do not return any value. They simply add an update request to a list. Eventually the updates in the list are applied at the end of a script execution (or at the end of the modify clause in the case of the transform expression).

Updating Expressions are therefore not allowed in places where a meaningful value is expected. For example the condition of a if, the right hand-side of a let :=, the in part of a for and so on.

Mixing Updating and Non-updating Expressions is not allowed in a sequence (the comma operator). Though technically feasible, it would not make much sense to mix expressions that return a value and expressions that don't (remember that the sequence operator returns the concatenation of the sequences returned by its components).

The fn:error() function and the empty sequence () are special as they can appear both in Updating and in non-updating expressions.

In the same way, the branches of a if or a typeswitch must be consistent: both Updating or both Non-updating. If both branches are Updating then the if itself is considered Updating, and conversely.

If the body of a function is an Updating Expression, then the function must be declared with the updating keyword. Example:

declare updating function insert-id($elem, $id-value) {
   insert node attribute id { $id-value } into $elem
}

A call to such a function is itself considered an Updating Expression. Logically enough, an updating function returns no value and therefore is not allowed to declare a return type.