XQuery Update Facility

2.3.1 Insert

An insert expression inserts copies of one or more nodes into a designated position in an XDM instance. If into is specified without as first or as last, the position of the inserted nodes within their parent is implementation-dependent. An insert expression is an updating expression.

Examples:

• Insert a year element after the publisher of the first book.

  insert <year>2005</year>
      after fn:doc("bib.xml")/books/book[1]/publisher
  

• Navigating by means of several bound variables, insert a new police report into the list of police reports for a particular accident.

  insert {$new-police-report}
     as last into fn:doc("insurance.xml")/policies
        /policy[id = $pid]
        /driver[license = $license]
        /accident[date = $accdate]
        /police-reports
  

The semantics of an insert expression are as follows:

1. If a DirectConstructor is specified, it is evaluated according to the rules in Section 3.7 of [XQuery 1.0]. The result is a single element, comment, or processing instruction node. Let $clist be this node, and let $alist be the empty sequence.

2. If a SourceExpr is specified, it must not be an updating expression; otherwise a static error is raised [err:XUST0101]. The SourceExpr is evaluated as though it were an enclosed expression in an element constructor (see Rule 1e in Section 3.7.1.3 of [XQuery 1.0]). The result of this step is either an error or a sequence of nodes to be inserted, called the insertion sequence. If the insertion sequence contains a document node, the document node is replaced in the insertion sequence by its children. If the insertion sequence contains an attribute node following a node that is not an attribute node, a type error is raised [err:TBD]. Let $alist be the sequence of attribute nodes in the insertion sequence. Let $clist be the remainder of the insertion sequence, in its original order.

3. The target expression must not be an updating expression; otherwise a static error is raised [err:XUST0101]. The target expression is evaluated. If into is specified, the result must be a single element node or a single document node; otherwise a type error is raised [err:TBD]. If before or after is specified, the result must be a single element node whose parent property is not empty; otherwise a dynamic error is raised [err:TBD]. Let $target be the node returned by the target expression.

4. The result of the insert expression is a pending update list constructed as follows:

   1. If as first is specified and $target has at least one child, let $child be the first child node of $target. The pending update list consists of the following update primitives:

      1. If $alist is not empty, upd:insertAttributes($target, $alist)

      2. If $clist is not empty, upd:insertBefore($child, $clist)

   2. If as last is specified, or as first is specified and $target has no children, the pending update list consists of the following update primitives:

      1. If $alist is not empty, upd:insertAttributes($target, $alist)

      2. If $clist is not empty, upd:insertIntoAsLast($target, $clist)

   3. If into is specified and neither as first nor as last is specified, the pending update list consists of the following update primitives:

      1. If $alist is not empty, upd:insertAttributes($target, $alist)

      2. If $clist is not empty, upd:insertInto($target, $clist)

   4. If before is specified, let $parent be the parent node of $target. The pending update list consists of the following update primitives:

      1. If $alist is not empty, upd:insertAttributes($parent, $alist)

      2. If $clist is not empty, upd:insertBefore($target, $clist)

   5. If after is specified, let $parent be the parent node of $target. The pending update list consists of the following update primitives:

      1. If $alist is not empty, upd:insertAttributes($parent, $alist)

      2. If $clist is not empty, upd:insertAfter($target, $clist)

2.3.2 Delete

A delete expression deletes one or more nodes from an XDM instance. A delete expression is an updating expression.

Examples:

• Delete the last author of the first book in a given bibliography.

  delete {fn:doc("bib.xml")/books/book[1]/author[last()]}
  

• Delete all email messages that are more than 365 days old.

  delete {/email/message
       [fn:currentDate() - date > xdt:dayTimeDuration("P365D")]}
  

The semantics of a delete expression are as follows:

1. The target expression must not be an updating expression; otherwise a static error is raised [err:XUST0101]. The target expression is evaluated. The result must be a sequence of nodes; otherwise a type error is raised [err:TBD]. Let $tlist be the list of nodes returned by the target expression.

2. A new pending update list is created. For each node $tnode in $tlist, the following update primitive is appended to the pending update list: upd:delete($tnode). The resulting pending update list is the result of the delete expression.

2.3.3 Replace

A replace expression is an updating expression. A replace expression has two forms, depending on whether value of is specified. In either case, a replace expression consists of one or more replacements, separated by commas. [Definition: A replacement is an operation that replaces a node or modifies the value of a node.]

If value of is not specified, each replacement replaces one node with a new sequence of zero or more nodes. Example:

• Replace the publisher of the first book with the publisher of the second book.

  replace {fn:doc("bib.xml")/books/book[1]/publisher}
  with fn:doc("bib.xml")/books/book[2]/publisher
  

The semantics of this form of replace expression are as follows:

1. The individual replacements can be processed in any order. Each replacement is processed as follows:

   1. The expression following the keyword with must not be an updating expression; otherwise a static error is raised [err:XUST0101]. This expression is evaluated as though it were an enclosed expression in an element constructor (see Rule 1e in Section 3.7.1.3 of [XQuery 1.0]). The result of this step is either an error or a sequence of nodes called the replacement sequence. If the replacement sequence contains a document node, the document node is replaced in the replacement sequence by its children. If the replacement sequence contains an attribute node following a node that is not an attribute node, a type error is raised [err:TBD]. Let $alist be the sequence of attribute nodes in the replacement sequence. Let $clist be the remainder of the replacement sequence, in its original order.

   2. The target expression must not be an updating expression; otherwise a static error is raised [err:XUST0101]. The target expression is evaluated. The result must be a single node whose parent property is not empty; otherwise a dynamic error is raised [err:TBD]. Let $target be the node returned by the target expression, and let $parent be its parent node.

      Note:

      $target may not be a document node, since a document node does not have a parent property.

   3. If $target is an element, text, comment, or processing instruction node, the replacement generates a pending update list consisting of the following update primitives:

      1. upd:insertAttributes($parent, $alist)

      2. upd:insertBefore($target, $clist)

      3. upd:delete($target)

   4. If $target is an attribute node, the replacement generates a pending update list consisting of the following update primitives:

      1. upd:insertAttributes($parent, $alist)

      2. upd:insertIntoAsLast($parent, $clist)

      3. upd:delete($target)

2. The pending update lists generated by the individual replacements are merged by successive invocations of the upd:mergeUpdates operation. If the upd:mergeUpdates operation signals an incompatibility, a dynamic error is raised [err:TBD]. Otherwise, the result of the replace expression is the merged pending update list returned by the final upd:mergeUpdates operation.

If value of is specified, a replace expression is used to modify the value of a node while preserving its node identity. Example:

• Increase the price of the first book by ten percent.

  replace value of {fn:doc("bib.xml")/books/book[1]/price}
  with fn:doc("bib.xml")/books/book[1]/price * 1.1
  

The semantics of this form of replace expression are as follows:

1. The individual replacements can be processed in any order. Each replacement is processed as follows:

   1. The expression following the keyword with must not be an updating expression; otherwise a static error is raised [err:XUST0101]. This expression is evaluated as though it were the content expression of a text node constructor (see Section 3.7.3.4 of [XQuery 1.0].) The result of this step is either an error or a single text node. Let $text be the text node resulting from this step.

   2. The target expression must not be an updating expression; otherwise a static error is raised [err:XUST0101]. The target expression is evaluated. The result must be a single node; otherwise a type error is raised [err:TBD]. Let $target be the node returned by the target expression.

   3. If $target is an element node, let $clist be a list of the children of $target. The result of the replace expression is a pending update list consisting of the following update primitives:

      1. For each node $cnode in $clist, upd:delete($cnode).

      2. upd:insertIntoAsLast($target, $text)

   4. If $target is an attribute, text, comment, or processing instruction node, let $string be the string value of the text node constructed in Step 1. The result of the replace expression is a pending update list containing the following update primitive: upd:replaceValue($target, $string).

   5. If $target is a document node, a type error is raised [err:TBD].

2. The pending update lists generated by the individual replacements are merged by successive invocations of the upd:mergeUpdates operation. If the upd:mergeUpdates operation signals an incompatibility, a dynamic error is raised [err:TBD]. Otherwise, the result of the replace expression is the merged pending update list returned by the final upd:mergeUpdates operation.

2.3.4 Rename

A rename expression replaces the name property of a data model node with a new QName. A rename expression is an updating expression.

Examples:

• Rename the first author element of the first book to principal-author.

  rename {fn:doc("bib.xml")/books/book[1]/author[1]}
  to "principal-author"
  

• Rename the first author element of the first book to the QName that is the value of the variable $newname.

  rename {fn:doc("bib.xml")/books/book[1]/author[1]}
  to $newname
  

The semantics of a rename expression are as follows:

1. The target expression must not be an updating expression; otherwise a static error is raised [err:XUST0101]. The target expression is evaluated. The result must be a single element, attribute, or processing instruction node; otherwise a type error is raised [err:TBD]. Let $target be the node returned by the target expression.

2. NewNameExpr must not be an updating expression; otherwise a static error is raised [err:XUST0101]. NewNameExpr is evaluated as though it were the name expression of a computed element constructor (see Section 3.7.3.1 of [XQuery 1.0].) The result is either an error or an expanded QName. Let $QName be this expanded QName.

3. The result of the rename expression is a pending update list containing the following update primitive: upd:rename($target, $QName).

2.3.5 Transform

A transform expression can be used to create modified copies of existing nodes in an XDM instance. Each node created by a transform expression has a new node identity. The result of a transform expression is an XDM instance that may include both nodes that were created by the transform expression and other, previously existing nodes. A transform expression is a non-updating expression.

Example:

• Return a sequence containing of all employee elements that have Java as a skill, excluding their salary child-elements:

  for $e in //employee[skill = "Java"]
  return
     transform 
        copy $je := $e
        do delete {$je/salary}
        return $je
  

A transform expression consists of three clauses, denoted by the keywords copy, do, and return. The semantics of a transform expression are as follows:

1. The copy clause contains one or more variable bindings, each of which consists of a variable name and an expression called the source expression. Each variable binding is processed as follows:

   1. The source expression must not be an updating expression; otherwise a static error is raised [err:XUST0101]. The source expression is evaluated as though it were an enclosed expression in an element constructor (see Rule 1e in Section 3.7.1.3 of [XQuery 1.0].) The result of this step is either an error or a sequence of nodes called the copied node sequence.

      Note:

      Each node in the copied node sequence is a newly created node with a new nodeid.

   2. The variable name is bound to the copied node sequence. The scope of this variable binding includes all subexpressions of the containing transform expression that appear after the variable binding clause, but it does not include the source expression to which the variable is bound.

2. The do clause must contain either an updating expression, an empty expression ( ), or a call to the fn:error function; otherwise a static error is raised [err:TBD]. The expression in the do clause is evaluated, resulting in a pending update list. If the target node of any update primitive on this pending update list is a node that was not newly created in Step 1, a dynamic error is raised [err:TBD]. Let $pul be the pending update list generated by this step.

3. The following update operation is invoked: upd:applyUpdates($pul). The effect of this operation is to make the updates specified in the do clause effective on the nodes in the copied node lists.

4. The return clause must not contain an updating expression; otherwise a static error is raised [err:XUST0101]. The return clause is evaluated, and its result is the result of the transform expression. During evaluation of the return clause, changes applied to copied nodes by the preceding step are visible.

2.4.1 FLWOR Expression

The syntax of the FLWOR expression is extended to include a new clause, called a do clause, that can be substituted for the return clause. The semantics of the FLWOR expression are extended as follows:

1. If the FLWOR expression contains a return clause, the return clause must contain a non-updating expression; otherwise, a static error is raised [err:XUST0101]. The FLWOR expression is a non-updating expression, and its semantics are as specified in Section 3.8 of [XQuery 1.0].

2. If the FLWOR expression contains a do clause, the do clause must contain either an updating expression, an empty expression ( ), or a call to the fn:error function; otherwise, a static error is raised [err:XUST0101]. The FLWOR expression is an updating expression, and its semantics are as follows:

   1. The semantics of the for, let, where, and order by clauses are as specified in Section 3.8 of [XQuery 1.0]. If any of these clauses contains an updating expression, a static error is raised [err:XUST0101]. These clauses generate a stream of tuples of bound variables.

   2. For each tuple generated by the previous step, the expression in the do clause is evaluated, resulting in a pending update list and an XDM instance.

   3. All the pending update lists generated by the previous step are merged by successive invocations of the upd:mergeUpdates operation. If the upd:mergeUpdates operation signals an incompatibility, a dynamic error is raised [err:TBD]. Otherwise, the result of the FLWOR expression is the merged pending update list returned by the final upd:mergeUpdates operation, and the concatenation of the XDM instances returned by the evaluations of the do clauses.

The following example illustrates the use of an updating expression in a FLWOR expression:

• Update an inventory of parts according to a set of changes provided in the bound variable $changes. Both /inventory and $changes contain a set of part elements, each with a partno and a quantity.

  for $p in /inventory/part
  let $deltap := $changes/part[partno eq $p/partno]
  do replace value of {$p/quantity}
        with $p/quantity + $deltap/quantity
  

2.4.2 Typeswitch Expression

The syntax of the typeswitch expression is extended to allow each return clause to be replaced by a do clause. The semantics of the typeswitch expression are extended as follows (the term "branch" refers to any case or default clause in the typeswitch expression):

1. If any branch contains a return clause, all branches must contain return clauses; otherwise a static error is raised [err:TBD]. In this case:

   1. If any branch contains an updating expression, a static error is raised [err:XUST0101].

   2. The typeswitch expression is a non-updating expression and its semantics are as specified in Section 3.12.2 of [XQuery 1.0].

2. If any branch contains a do clause, all branches must contain do clauses; otherwise a static error is raised [err:TBD]. In this case:

   1. Every branch must contain either an updating expression, an empty expression ( ), or a call to the fn:error function; otherwise a static error is raised [err:TBD].

   2. The typeswitch expression is an updating expression. Selection of the effective case and binding of variables is performed as specified in Section 3.12.2 of [XQuery 1.0]. The expression in the do clause of the effective case (or default) is then evaluated, resulting in a pending update list and an XDM instance, which serve as the result of the typeswitch expression.

2.4.3 Conditional Expression

The semantics of conditional expressions are extended as follows (the term "branch" refers to the then and else clauses in the conditional expression):

1. If at least one branch contains a non-updating expression other than the empty expression ( ) or a call to the fn:error function, the other branch must contain a non-updating expression; otherwise a static error is raised [err:XUST0101]. In this case, the conditional expression is a non-updating expression, and its semantics are as specified in Section 3.10 of [XQuery 1.0].

2. If at least one branch contains an updating expression, the conditional expression is an updating expression. In this case, the test expression is evaluated and the then or else clause is selected and evaluated as specified in Section 3.10 of [XQuery 1.0]. The result of the conditional expression is the pending update list and XDM instance returned by the selected branch.

The following example illustrates the use of updating expressions in a conditional expression:

• If the element bound to variable $e has a last-updated attribute, update its value to the current date; otherwise insert such an attribute.

  if ($e/@last-updated)
  then replace value of {$e/last-updated} with fn:currentDate()
  else insert {attribute last-updated {fn:currentDate()}} into $e
  

2.4.4 Comma Expression

The semantics of comma expressions (composed of one or more expressions concatenated by the comma operator, as described in Section 3.3.1 of [XQuery 1.0]) are extended as follows:

1. If any operand of the comma expression is an updating expression, the comma expression is an updating expression; otherwise, the comma expression is a non-updating expression.

2. The XDM instance returned by the comma expression is the concatenation of the XDM instances returned by its operand expressions, as specified in Section 3.3.1 of [XQuery 1.0].

3. The pending update lists returned by the operand expressions of the comma expression are merged by the upd:mergeUpdates operation. If the upd:mergeUpdates operation reports an incompatibility, a dynamic error is raised [err:TBD]. Otherwise, the comma expression returns the merged pending update list returned by the upd:mergeUpdates operation.

The following examples illustrate the use of comma expressions:

• This example makes the value of an element empty and gives the element an xsi:nil="true" attribute. Both of these operations may be necessary in order to preserve the validity of the element.

  let $q := /inventory/item[serialno = "123456"]/quantity
  do
     replace value of {$q} with ( ),
     insert {attribute xsi:nil {"true"}} into $q
  

• This example increases the salary of all employees that meet certain criteria, and returns the names of the employees who received salary increases (illustrates a comma expression that combines updating and non-updating expressions):

  for $e in //employee
  do 
     if ($e/sales > $e/quota
         and fn:currentDate() - $e/last-raise 
                  > xdt:dayTimeDuration("P365D"))
     then 
        (replace value of {$e/salary} with $e/salary * 1.1,
         replace value of {$e/last-raise} with fn:currentDate(),
         $e/name)
     else ( )
  

2.4.5 Parenthesized Expression

The semantics of a parenthesized expression (any XQuery expression enclosed in parentheses) are extended as follows:

The category of a parenthesized expression is the same as the category of its operand expression, which may be an updating expression or a non-updating expression. The result of a parenthesized expression is also the same as the result of its operand expression, which includes both an XDM instance and a pending update list.

2.4.6 Function Declaration

The syntax of a function declaration is extended to include an optional keyword: updating. The semantics of a function declaration are extended as follows:

1. If external is not specified:

   1. If updating is specified, the EnclosedExpr in the function declaration must be an updating expression; otherwise a static error is raised [err:XUST0101].

   2. If updating is not specified, the EnclosedExpr in the function declaration must be a non-updating expression; otherwise a static error is raised [err:TBD].

2. If external is specified:

   1. If updating is not specified, the pending update list returned by the external function must be empty; otherwise a dynamic error is raised [err:TBD].

   The means by which an external function returns an XDM instance and a pending update list is implementation-defined.

The following example illustrates an updating function.

• This function takes an element, a QName, and an atomic value. If the given element has an attribute with the given QName, the function updates the attribute with the given value; otherwise it inserts a new attribute with the given name and value.

  declare updating function 
     upsert($e as element(), 
            $an as xs:QName, 
            $av as xdt:anyAtomicType) 
        as element()
     {
     let $ea := $e/attribute()[fn:node-name(.) = $an]
     do
        if (fn:empty($ea))
        then insert {attribute {$an} {$av}} into $e
        else replace value of {$ea} with $av
     }
  

2.4.7 Function Call

The semantics of a function call are extended as follows:

The function call is evaluated as specified in Section 3.1.5 of [XQuery 1.0]. If any input parameter of the function call is an updating expression, a static error is raised [err:XUST0101]. If the called function was declared with the updating keyword, the function call is an updating expression. If the called function was declared without the updating keyword, the function call is a non-updating expression.

2.4.8 Other Expressions

The semantics of all XQuery expressions other than FLWOR expressions, typeswitch expressions, conditional expressions, comma expressions, parenthesized expressions, and function calls are extended as follows:

If any operand of this expression is an updating expression, a static error is raised [err:XUST0101].

3.4.1 upd:insertBefore

Parameters

upd:insertBefore(
   $target as node(),
   $content as node()+)

Summary

Inserts $content immediately before $target.

Constraints

$target must be an element, text, processing instruction, or comment node with a non-empty parent property. $content must be a sequence containing only element, text, processing instruction, and comment nodes.

Semantics

1. Effects on nodes in $content:

   1. For each node in $content, the parent property is set to parent($target).

   2. If the type-name property of parent($target) is xdt:untyped, then set-to-untyped is applied to each element or attribute node in $content.

2. Effects on parent($target):

   1. The children property of parent($target) is modified to add the nodes in $content just before $target, preserving their order.

   2. If, as a result of the previous step, the children property of parent($target) contains adjacent text nodes, these adjacent text nodes are merged into a single text node. The string-value of the resulting text node is the concatenated string-values of the adjacent text nodes, with no intervening space added. The nodeid of the resulting text node is implementation-dependent.

   3. If at least one of the nodes in $content is an element or text node, remove-type is invoked on parent($target).

3.4.2 upd:insertAfter

Parameters

upd:insertAfter(
   $target as node(),
   $content as node()+)

Summary

Inserts $content immediately after $target.

Constraints

$target must be an element, text, processing instruction, or comment node with a non-empty parent property. $content must be a sequence containing only element, text, processing instruction, and comment nodes.

Semantics

The semantics of upd:insertAfter are identical to the semantics of upd:insertBefore, except that Rule 2a is changed as follows:

• The children property of parent($target) is modified to add the nodes in $content just after $target, preserving their order.

3.4.3 upd:insertInto

Parameters

upd:insertInto(
   $target as node(),
   $content as node()+)

Summary

Inserts $content as the children of $target, in an implementation-defined position.

Constraints

$target must be an element or document node. $content must be a sequence containing only element, text, processing instruction, and comment nodes.

Semantics

The semantics of upd:insertIntoAsLast are identical to the semantics of upd:insertBefore, except that $target is substuted everywhere for parent($target), and Rule 2a is changed as follows:

• The children property of $target is changed to include the nodes in $content. The order among the new children, and their position within the parent node, is implementation-dependent.

3.4.4 upd:insertIntoAsLast

Parameters

upd:insertIntoAsLast(
   $target as node(),
   $content as node()+)

Summary

Inserts $content as the last children of $target.

Constraints

$target must be an element or document node. $content must be a sequence containing only element, text, processing instruction, and comment nodes.

Semantics

The semantics of upd:insertIntoAsLast are identical to the semantics of upd:insertBefore, except that $target is substuted everywhere for parent($target), and Rule 2a is changed as follows:

• The children property of $target is changed to include the nodes in $content as the last children, preserving their order.

3.4.5 upd:insertAttributes

Parameters

upd:insertAttributes(
   $target as element(),
   $content as attribute()+)

Summary

Inserts $content as attributes of $target.

Constraints

None

Semantics

1. For each node A in $content:

   1. The parent property of A is set to $target.

   2. If the type-name property of $target is xdt:untyped, then set-to-untyped is applied to A.

2. The following properties of $target are changed:

   1. attributes: Modified to include the nodes in $content.

   2. namespaces: Modified to include namespace bindings for any attribute namespace prefixes in $content that did not already have bindings.

   3. Remove-type is applied to $target.

3.4.6 upd:delete

Parameters

upd:delete(
   $target as node())

Summary

Deletes $target and all its attributes and descendants.

Constraints

None

Semantics

1. $target and all of its attributes and descendants (if any) are deleted from their XDM instance.

   Note:

   The effect on variable bindings in which the deleted node participates, and the effect on available documents and collections, are under discussion.

2. Effect on parent($target), if any:

   1. If $target is an attribute node, attributes is modified to delete $target.

   2. If $target is a non-attribute node, children is modified to delete $target.

   3. If, as a result of the previous step, the children property of parent($target) contains adjacent text nodes, these adjacent text nodes are merged into a single text node. The string-value of the resulting text node is the concatenated string-values of the adjacent text nodes, with no intervening space added. The nodeid of the resulting text node is implementation-dependent.

   4. If $target is an element, attribute, or text node, and parent($target) is an element node, then remove-type is applied to parent($target).

3.4.7 upd:replaceValue

Parameters

upd:replaceValue(
   $target as node(),
   $string-value as xs:string)

Summary

Replaces the string value of $target with $string-value.

Constraints

$target must be an attribute, text, comment, or processing instruction node.

Semantics

1. If $target is an attribute node:

   1. string-value of $target is set to $string-value.

   2. remove-type is applied to $target.

2. If $target is a text, comment, or processing instruction node: content of $target is set to $string-value.

3. If $target is a text node, remove-type is applied to parent($target).

3.4.8 upd:rename

Parameters

upd:rename(
   $target as node(),
   $newName as xs:QName)

Summary

Changes the node-name of $target to $newName.

Constraints

$target must be an element, attribute, or processing instruction node.

Semantics

1. If $target is an element node:

   1. node-name of $target is set to $newName.

   2. Remove-type is applied to $target.

2. If $target is an attribute node:

   1. node-name of $target is set to $newName.

   2. Remove-type is applied to $target.

   3. If $newName is xml:id, the is-id property of $target is set to true.

   4. The namespaces property of parent($target) is modified to include a namespace binding derived from $newName, if this binding did not already exist.

3. If $target is a processing instruction node, its target property is set to $newName.