XQuery Update Facility 1.0

2.2.1 Revalidation Declaration

The Prolog is extended by adding a new kind of Setter called a revalidation declaration. [Definition: A revalidation declaration sets the revalidation mode in the static context, overriding any implementation-defined default.] If a Prolog contains more than one revalidation declaration, a static error is raised [err:XUST0003]. Revalidation mode controls the process by which type information is recovered for an updated document, as described in [3.2.3 upd:revalidate]

Support for each of the three revalidation modes is implementation-defined; however, an implementation must support at least one of the three revalidation modes. If a revalidation declaration specifies a revalidation mode that is not supported by the current implementation, a static error is raised [err:XUST0026].

2.2.2 Variable Declaration

The following rule is added: If the expression on the right-hand-side of a variable declaration (the initializing expression) is not a simple expression, a static error is raised [err:XUST0001].

2.2.3 Function Declaration

The syntax of a function declaration is extended with an optional keyword: updating. [Definition: Functions whose declarations contain the keyword updating, and certain built-in functions including fn:put, are called updating functions.] The semantics of a function declaration, described in Section 4.15 of [XQuery 1.0], are extended as follows:

1. If updating is not specified:

   1. If external is not specified, the EnclosedExpr in the function declaration must be a simple expression; otherwise a static error is raised [err:XUST0001].

   2. If external is specified, the external function must not return a non-empty pending update list; otherwise a dynamic error is raised [err:XUDY0018].

2. If updating is specified:

   1. A return type must not be specified [err:XUST0028].

   2. If external is not specified, the EnclosedExpr in the function declaration must be an updating expression or a vacuous expression; otherwise a static error is raised [err:XUST0002].

   3. If external is specified, the external function may return a non-empty pending update list but it must not return a non-empty XDM instance; otherwise a dynamic error is raised [err:XUDY0019].

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

The following example illustrates a declaration of 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 xs:anyAtomicType) 
     {
     let $ea := $e/attribute()[fn:node-name(.) = $an]
     return
        if (fn:empty($ea))
        then insert node attribute {$an} {$av} into $e
        else replace value of node $ea with $av
     }

2.4.1 Insert

An insert expression is an updating expression that inserts copies of zero or more nodes into a designated position with respect to a target node. The keywords node and nodes may be used interchangeably, regardless of how many nodes are actually inserted. The position of the inserted nodes is determined as follows:

• If before (or after) is specified:

  • The inserted nodes become the preceding (or following) siblings of the target node.

  • If multiple nodes are inserted by a single insert expression, the nodes remain adjacent and their order preserves the node ordering of the source expression.

  • If multiple groups of nodes are inserted by multiple insert expressions in the same snapshot, adjacency and ordering of nodes within each group is preserved but ordering among the groups is implementation-dependent.

• If as first into (or as last into) is specified:

  • The inserted nodes become the first (or last) children of the target node.

  • If multiple nodes are inserted by a single insert expression, the nodes remain adjacent and their order preserves the node ordering of the source expression.

  • If multiple groups of nodes are inserted by multiple insert expressions in the same snapshot, adjacency and ordering of nodes within each group is preserved but ordering among the groups is implementation-dependent.

• If into is specified without as first or as last:

  • The inserted nodes become children of the target node.

  • If multiple nodes are inserted by a single insert expression, their order preserves the node ordering of the source expression.

  • The positions of the inserted nodes are chosen so as not to interfere with the intended position of nodes that are inserted with the specification before, after, as first into, or as last into. For example, If node B is inserted "after node A", no other node will be inserted between nodes A and B unless it is also inserted "after node A".

  • Subject to the above constraints, the positions of the inserted nodes among the children of the target node are implementation-dependent.

Examples:

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

  insert node <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 node $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. SourceExpr must be a simple expression; otherwise a static error is raised [err:XUST0001]. SourceExpr is evaluated as though it were an enclosed expression in an element constructor (see Rule 1e in Section 3.7.1.3 Content^XQ). 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:XUTY0004]. 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.

   Note:

   Either $alist or $clist or both may be empty.

2. The target expression must be a simple expression; otherwise a static error is raised [err:XUST0001]. The target expression is evaluated and checked as follows:

   1. If the result is an empty sequence, [err:XUDY0027] is raised.

   2. If any form of into is specified, the result must be a single element or document node; any other non-empty result raises a type error [err:XUTY0005].

   3. If before or after is specified, the result must be a single element, text, comment, or processing instruction node; any other non-empty result raises a type error [err:XUTY0006].

   4. If before or after is specified, the node returned by the target expression must have a non-empty parent property [err:XUDY0029].

   Let $target be the node returned by the target expression.

3. If $alist is not empty and any form of into is specified, the following checks are performed:

   1. $target must be an element node [err:XUTY0022].

   2. No attribute node in $alist may have a QName whose implied namespace binding conflicts with a namespace binding in the "namespaces" property of $target [err:XUDY0023], unless the namespace prefix for the attribute is absent.

   3. Multiple attribute nodes in $alist must not have QNames whose implied namespace bindings conflict with each other [err:XUDY0024].

4. If $alist is not empty and before or after is specified, the following checks are performed:

   1. parent($target) must be an element node [err:XUDY0030].

   2. No attribute node in $alist may have a QName whose implied namespace binding conflicts with a namespace binding in the "namespaces" property of parent($target) [err:XUDY0023] unless the namespace prefix for the attribute is absent.

   3. Multiple attribute nodes in $alist must not have QNames whose implied namespace bindings conflict with each other [err:XUDY0024].

5. The result of the insert expression is an empty XDM instance and a pending update list constructed as follows:

   1. If as first into 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:insertIntoAsFirst($target, $clist)

   2. If as last into 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:insertIntoAsLast($target, $clist)

   3. If into is specified with neither as first nor as last, 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.4.2 Delete

A delete expression deletes zero or more nodes from an XDM instance. The keywords node and nodes may be used interchangeably, regardless of how many nodes are actually deleted. A delete expression is an updating expression.

Examples:

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

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

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

  delete nodes /email/message
       [fn:currentDate() - date > xs:dayTimeDuration("P365D")]

The semantics of a delete expression are as follows:

1. The target expression must be a simple expression; otherwise a static error is raised [err:XUST0001]. The target expression is evaluated. The result must be a sequence of zero or more nodes; otherwise a type error is raised [err:XUTY0007]. Let $tlist be the list of nodes returned by the target expression.

2. If any node in $tlist has no parent, it is removed from $tlist (and is thus ignored in the following step). the node is removed from $tlist (and is thus ignored in the following step)an implementation may (but is not required to) raise a dynamic error [err:XUDY0020].

3. 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 (together with an empty XDM instance) is the result of the delete expression.

2.4.3 Replace

A replace expression is an updating expression. A replace expression has two forms, depending on whether value of is specified.

2.4.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 node fn:doc("bib.xml")/books/book[1]/author[1]
  as "principal-author"

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

  rename node fn:doc("bib.xml")/books/book[1]/author[1]
  as $newname

The semantics of a rename expression are as follows:

1. The target expression must be a simple expression; otherwise a static error is raised [err:XUST0001]. The target expression is evaluated and checked as follows:

   1. If the result is an empty sequence, [err:XUDY0027] is raised.

   2. If the result is non-empty and does not consist of a single element, attribute, or processing instruction node, [err:XUTY0012] is raised.

   Let $target be the node returned by the target expression.

2. NewNameExpr must be a simple expression; otherwise a static error is raised [err:XUST0001]. NewNameExpr is processed as follows:

   1. If $target is an element node, let $QName be the result of evaluating NewNameExpr as though it were the name expression of a computed element constructor (see Section 3.7.3.1 Computed Element Constructors^XQ). If the namespace binding of $QName conflicts with any namespace binding in the namespaces property of $target, a dynamic error is raised [err:XUDY0023].

   2. If $target is an attribute node, let $QName be the result of evaluating NewNameExpr as though it were the name expression of a computed attribute constructor (see Section 3.7.3.2 Computed Attribute Constructors^XQ). If $QName has a non-absent namespace URI, and if the namespace binding of $QName conflicts with any namespace binding in the namespaces property of the parent (if any) of $target, a dynamic error is raised [err:XUDY0023].

   3. If $target is a processing instruction node, let $NCName be the result of evaluating NewNameExpr as though it were the name expression of a computed processing instruction constructor (see Section 3.7.3.5 Computed Processing Instruction Constructors^XQ), and let $QName be defined as fn:QName((), $NCName).

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

for $node in $root//abc:*
let $localName := fn:local-name($node),
    $newQName := fn:concat("xyz:", $localName)
return (
   rename node $node as fn:QName("https://xyz/ns", $newQName),
   for $attr in $node/@abc:*
   let $attrLocalName := fn:local-name($attr),
       $attrNewQName := fn:concat("xyz:", $attrLocalName)
   return
      rename node $attr as fn:QName("https://xyz/ns", $attrNewQName)
)

2.4.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 simple expression because it does not modify the value of any existing nodes.

Examples:

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

  for $e in //employee[skill = "Java"]
  return 
     copy $je := $e
     modify delete node $je/salary
     return $je

• The following example copies a node, modifies the copy, and returns both the original node and the modified copy:

  let $oldx := /a/b/x
  return
     copy $newx := $oldx
     modify (rename node $newx as "newx", 
             replace value of node $newx with $newx * 2)
     return ($oldx, $newx)
  

  Note:

  No persistent changes to the underlying data result from this example.

A transform expression consists of three clauses, denoted by the keywords copy, modify, 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 be a simple expression; otherwise a static error is raised [err:XUST0001].

   2. The result of evaluating the source expression must be a single node [err:XUTY0013]. Let $node be this single node.

   3. A new copy is made of $node and all nodes that have $node as an ancestor, collectively referred to as copied nodes. Each copied node receives a new node identity. The parent, children, and attributes properties of the copied nodes are set so as to preserve their inter-node relationships. The parent property of the copy of $node is set to empty. Other properties of the copied nodes are determined as follows:

      1. For a copied element node, the type-name property is set to xs:untyped, and the nilled, is-id, and is-idrefs properties are set to false.

      2. For a copied attribute node, the type-name property is set to xs:untypedAtomic and the is-idrefs property is set to false. The is-id property is set to true if the qualified name of the attribute node is xml:id; otherwise it is set to false.

      3. The string value of each copied element and attribute node remains unchanged, and its typed value becomes equal to its string value as an instance of xs:untypedAtomic.

         Note:

         Implementations that store only the typed value of a node are required at this point to convert the typed value to a string form.

      4. If copy-namespaces mode in the static context specifies preserve, all in-scope-namespaces of the original element are retained in the new copy. If copy-namespaces mode specifies no-preserve, the new copy retains only those in-scope namespaces of the original element that are used in the names of the element and its attributes.

      5. All other properties of the copied nodes are preserved.

   4. The variable name is bound to the top-level copied node generated in the previous step. The scope of this variable binding includes all subexpressions of the containing transform expression that appear after the variable binding clause, including the source expressions of later variable bindings, but it does not include the source expression to which the current variable name is bound.

2. The modify clause must contain an updating expression or a vacuous expression contain either an updating expression, an empty expression ( ), or a call to the fn:error function; otherwise a static error is raised [err:XUST0002]. The expression in the modify 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:XUDY0014]. Let $pul be the pending update list generated by this step.

3. Let $pul be the pending update list generated by the previous step. Let $revalidation-mode be the value of the revalidation mode in the static context of the transform expression. Let $inherit-namespaces be true if the copy-namespaces mode specifies inherit, or false if the copy-namespaces mode specifies no-inherit. The following update operation is invoked: upd:applyUpdates($pul, $revalidation-mode, $inherit-namespaces). The effect of this operation is to make the updates specified in the modify clause effective on the copied nodes.

   Note:

   In the event of incompatible updates, the upd:applyUpdates operation may raise an error, as described in [3.2.2 upd:applyUpdates].

4. The return clause must contain a simple expression; otherwise a static error is raised [err:XUST0001]. 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.6 Compatibility of Updating Expressions

The rules defining compatibility of updating expressions within a snapshot are defined in [3.2.2 upd:applyUpdates].

2.5.1 FLWOR Expression

The syntax of the FLWOR expression is not changed. Its semantics are extended as follows:

1. If a for, let, where, or order by clause contains an updating expression, a static error is raised [err:XUST0001].

2. The return clause may contain any category of expression. The category of the FLWOR expression is the same as the category of the expression in its return clause (simple, vacuous, or updating.)

3. If the return clause contains a simple expression, the semantics of the FLWOR expression are as specified in Section 3.8 FLWOR Expressions^XQ.

4. If the return clause contains an updating expression, the semantics of the FLWOR expression are as follows:

   1. The semantics of the for, let, where, and order by clauses are as specified in Section 3.8 FLWOR Expressions^XQ. These clauses generate a stream of tuples of bound variables.

   2. For each tuple generated by the previous step, the updating expression in the return clause is evaluated, resulting in a pending update list.

   3. All the pending update lists generated by the previous step are merged by successive invocations of the upd:mergeUpdates operation. The resulting merged pending update list is the result of the FLWOR expression.

      Note:

      In the event of incompatible updates, the upd:mergeUpdates operation may raise an error, as described in [3.2.1 upd:mergeUpdates].

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]
  return 
      replace value of node $p/quantity
      with $p/quantity + $deltap/quantity

2.5.2 Typeswitch Expression

The syntax of the typeswitch expression is not changed. Its semantics are extended as follows. Let the expressions in the case and default clauses be called branches. Then:

1. If the operand expression of a typeswitch is an updating expression, a static error is raised [err:XUST0001].

2. If any branch is an updating expression, then all branches must be updating or vacuous expressions [err:XUST0001]. In this case, the typeswitch expression is an updating expression.

3. If all branches are vacuous expressions, the typeswitch expression is a vacuous expression.

4. Otherwise, the typeswitch expression is a simple expression.

5. If the typeswitch expression is a simple (including vacuous) expression, its semantics are as specified in Section 3.12.2 Typeswitch^XQ.

6. If the typeswitch expression is an updating expression, then selection of the effective case and binding of variables are performed as specified in Section 3.12.2 Typeswitch^XQ. The expression in the return clause of the effective case (or default) is then evaluated, resulting in a pending update list, which serves as the result of the typeswitch expression.

2.5.3 Conditional Expression

The semantics of conditional expressions are extended as follows. Let the expressions in the then and else clauses be called branches. Then:

1. If the if-clause contains an updating expression, a static error is raised [err:XUST0001].

2. If either branch is an updating expression, then both branches must be updating or vacuous expressions [err:XUST0001]. In this case, the conditional expression is an updating expression.

3. If both branches are vacuous expressions, the conditional expression is a vacuous expression.

4. Otherwise, the conditional expression is a simple expression.

5. If the conditional expression is a simple (including vacuous) expression, its semantics are as specified in Section 3.10 Conditional Expressions^XQ.

6. If the conditional expression is an updating expression, then selection of the effective branch performed as specified in Section 3.10 Conditional Expressions^XQ. The result of the conditional expression is the pending update list 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 node 
          $e/last-updated with fn:currentDate()
  else insert node 
          attribute last-updated {fn:currentDate()} into $e

2.5.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 Constructing Sequences^XQ) are extended as follows:

1. If any operand is an updating expression, then all operands must be updating or vacuous expressions [err:XUST0001]. In this case, the comma expression is an updating expression.

2. If all operands are vacuous expressions, the comma expression is a vacuous expression.

3. Otherwise, the comma expression is a simple expression.

4. If the comma expression is a simple (including vacuous) expression, its semantics are as specified in Section 3.3.1 Constructing Sequences^XQ.

5. If the comma expression is an updating expression, its operand expressions are evaluated (in any order), and the pending update lists returned by the operand expressions are merged by the upd:mergeUpdates operation. The resulting merged pending update list is the result of the comma expression.

The following example illustrates the use of an updating comma expression:

• 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
  return
     ( replace value of node $q with ( ),
       insert node attribute xsi:nil {"true"} into $q )

2.5.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 the expression enclosed in parentheses, which may have any category. The result of a parenthesized expression is also the same as the result of the expression enclosed in parentheses.

An empty parenthesized expression ( ) is a vacuous expression. Its result is an empty sequence and an empty pending update list.

2.5.6 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:XUST0001].

The expression category of a function call is as follows:

• A call to the built-in function fn:error is a vacuous expression.

• A call to an updating function is an updating expression.

• A call to any other function is a simple expression.

  Note:

  This includes calls to built-in functions other than fn:error and calls to user-defined functions that were not declared to be updating.

2.5.7 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:XUST0001].

2.6.1 fn:put

Summary: Stores a document or element to the location specified by $uri. This function is normally invoked to create a resource on an external storage system such as a file system or a database.

The external effects of fn:put are implementation-defined, since they occur outside the domain of XQuery. The intent is that, if fn:put is invoked on a document node and no error is raised, a subsequent query can access the stored document by invoking fn:doc with the same URI.

Semantics:

1. fn:put is an updating function.

2. If $node is not a document node or an element node, and the implementation does not support fn:put on the given node kind, a dynamic error is raised [err:FOUP0001].

3. If $uri is not a valid lexical representation of the xs:anyURI type, a dynamic error is raised [err:FOUP0002]. If $uri is a relative URI reference, it is resolved relative to the value of the base URI property in the static context.

4. The result of a call to fn:put is an empty XDM instance and a pending update list containing the following update primitive: upd:put($node, $uri).

3.1.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 xs:untyped, then upd:setToUntyped() is invoked on 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 at least one of the nodes in $content is an element or text node, upd:removeType(parent($target)) is invoked.

4. All the namespace bindings of parent($target) are marked for namespace propagation.