XQuery Update Facility 3.0

2.4.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.4.2 Function Declaration

The semantics of a function declaration, described in Section 4.18 Function Declaration ^XQ30, 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.3 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.6.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.9.1.3 Content ^XQ30). 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].

   3. Multiple attribute nodes in $alist may 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].

   3. Multiple attribute nodes in $alist may 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.6.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).

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.6.3 Replace

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

2.6.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.9.3.1 Computed Element Constructors ^XQ30). 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.9.3.2 Computed Attribute Constructors ^XQ30). 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.9.3.5 Computed Processing Instruction Constructors ^XQ30), 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("http://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("http://xyz/ns", $attrNewQName)
)

2.6.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 be an updating expression or a vacuous expressions; 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].

3. Let $revalidation-mode be the value of the revalidation mode in the static context of the transform expression. 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.6.6 Compatibility of Updating Expressions

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

2.7.1 FLWOR Expression

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

1. If a ForClause, LetClause, WindowClause, WhereClause, GroupByClause, or OrderByClause contains an updating expression, a static error is raised [err:XUST0001].

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

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

3. If the ReturnClause contains a simple expression, the semantics of the FLWOR expression are as specified in Section 3.10 FLWOR Expressions ^XQ30.

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

   1. The semantics of all clauses other than the ReturnClause are as specified in Section 3.10 FLWOR Expressions ^XQ30. These clauses generate a stream of tuples of bound variables.

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

   2. For each tuple generated by the previous step, the updating expression in the ReturnClause 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.7.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.16.2 Typeswitch ^XQ30.

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.16.2 Typeswitch ^XQ30. 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.7.4 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.12 Conditional Expressions ^XQ30.

6. If the conditional expression is an updating expression, then selection of the effective branch performed as specified in Section 3.12 Conditional Expressions ^XQ30. 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.7.6 Comma Expression

The semantics of comma expressions (composed of one or more expressions concatenated by the comma operator, as described in Section 3.4.1 Constructing Sequences ^XQ30) 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.4.1 Constructing Sequences ^XQ30.

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.7.7 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.7.10 Function Calls

The semantics of a function call or partial function application are extended as follows:

The function call is evaluated as specified in Section 3.1.5 Static Function Calls ^XQ30. If any input parameter argument expression^XQ30 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.7.12 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.8.1 fn:put

empty-sequence() put(node(), xs:string)

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.

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

3.1.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.1.3 upd:insertInto

Parameters

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

Summary

Inserts $content as the children of $target, in an implementation-dependent 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:insertInto are identical to the semantics of upd:insertBefore, except that $target is substituted everywhere for parent($target), and Rule 2a is changed as follows:

• The children property of $target is changed to add the nodes in $content in implementation-dependent positions, preserving their relative order.

3.1.4 upd:insertIntoAsFirst

Parameters

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

Summary

Inserts $content as the first 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:insertIntoAsFirst are identical to the semantics of upd:insertBefore, except that $target is substituted everywhere for parent($target), and Rule 2a is changed as follows:

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

3.1.5 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 substituted everywhere for parent($target), and Rule 2a is changed as follows:

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

3.1.6 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 xs:untyped, then upd:setToUntyped($A) is invoked.

2. The following properties of $target are changed:

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

   2. namespaces: Modified to add namespace bindings for any attribute namespace prefixes in $content that did not already have bindings. These bindings are marked for namespace propagation.

   3. upd:removeType($target) is invoked.

3.1.7 upd:delete

Parameters

upd:delete(
   $target as node())

Constraints

None

Semantics

1. If $target has a parent node $P, then:

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

   2. If $target is an attribute node, the attributes property of $P is modified to remove $target.

   3. If $target is a non-attribute node, the children property of $P is modified to remove $target.

   4. If $target is an element, attribute, or text node, and $P is an element node, then upd:removeType($P) is invoked.

2. If $target has no parent, the XDM instance is unchanged.

Note:

Deleted nodes are detached from their parent nodes; however, a node deletion has no effect on variable bindings or on the set of available documents or collections during processing of the current query.

Note:

Multiple upd:delete operations may be applied to the same node during execution of a query; this is not an error.

3.1.8 upd:replaceNode

Parameters

upd:replaceNode(
   $target as node(),
   $replacement as node()*)

Summary

Replaces $target with $replacement.

Constraints

$target must be a node that has a parent. If $target is an attribute node, $replacement must consist of zero or more attribute nodes. If $target is an element, text, comment, or processing instruction node, $replacement must be consist of zero or more element, text, comment, or processing instruction nodes.

Semantics

1. Effects on nodes in $replacement:

   1. For each node in $replacement, 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 node in $replacement.

2. Effect on $target:

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

3. Effects on parent($target):

   1. If $target is an attribute node, the attributes property of parent($target) is modified by removing $target and adding the nodes in $replacement (if any).

   2. If $target is an attribute node, the namespaces property of parent($target) is modified to add namespace bindings for any attribute namespace prefixes in $replacement that did not already have bindings. These bindings are marked for namespace propagation.

   3. If $target is an element, text, comment, or processing instruction node, the children property of parent($target) is modified by removing $target and adding the nodes in $replacement (if any) in the former position of $target, preserving their order.

   4. If $target or any node in $replacement is an element, attribute, or text node, upd:removeType(parent($target)) is invoked.

3.1.9 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. upd:removeType($target) is invoked.

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 that has a parent, upd:removeType(parent($target)) is invoked.

3.1.10 upd:replaceElementContent

Parameters

upd:replaceElementContent(
   $target as element(),
   $text as text()?)

Summary

Replaces the existing children of the element node $target by the optional text node $text. The attributes of $target are not affected.

Constraints

None.

Semantics

1. For each node $C that is a child of $target, the parent property of $C is set to empty.

2. The parent property of $text is set to $target.

3. Effects on $target:

   1. children is set to consist exclusively of $text. If $text is an empty sequence, then $target has no children.

   2. typed-value and string-value are set to the content property of $text. If $text is an empty sequence, then typed-value is an empty sequence and string-value is an empty string.

   3. upd:removeType($target) is invoked.

3.1.11 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. upd:removeType($target) is invoked.

   3. If $newname has no prefix and no namespace URI, the namespaces property of $target is modified by removing the binding (if any) for the empty prefix.

   4. The namespaces property of $target is modified to add a namespace binding derived from $newName, if this binding did not already exist. This binding is marked for namespace propagation.

2. If $target is an attribute node:

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

   2. upd:removeType($target) is invoked.

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

   4. If $target has a parent, the namespaces property of parent($target) is modified to add a namespace binding derived from $newName, if this binding did not already exist. This binding is marked for namespace propagation.

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

Note:

At the end of a snapshot, if multiple attribute nodes with the same parent have the same qualified name, an error will be raised by upd:applyUpdates.

3.1.12 upd:put

Parameters

upd:put(
   $node as node(),
   $uri as xs:string)

Summary

The XDM node tree rooted at $node is stored to the location specified by $uri.

Constraints

$uri must be a valid absolute URI.

Semantics

The external effects of upd:put are implementation-defined, since they occur outside the domain of XQuery. The intent is that, if upd: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.

3.2.1 upd:mergeUpdates

Parameters

upd:mergeUpdates(
   $pul1 as pending-update-list,
   $pul2 as pending-update-list)

Summary

Merges two pending update lists.

Constraints

None.

Semantics

1. The two pending update lists are merged and a single pending update list containing all the update primitives from both lists is returned.

2. Optionally, upd:mergeUpdates may raise a dynamic error if any of the following conditions are detected:

   1. Two or more upd:rename primitives on the merged list have the same target node [err:XUDY0015].

   2. Two or more upd:replaceNode primitives on the merged list have the same target node [err:XUDY0016].

   3. Two or more upd:replaceValue primitives on the merged list have the same target node [err:XUDY0017].

   4. Two or more upd:replaceElementContent primitives on the merged list have the same target node [err:XUDY0017].

   5. Two or more upd:put primitives on the merged list have the same $uri operand [err:XUDY0031].

   6. Two or more primitives on the merged list create conflicting namespace bindings for the same element node [err:XUDY0024]. The following kinds of primitives create namespace bindings:

      1. upd:insertAttributes creates one namespace binding on the $target element corresponding to the implied namespace binding of the name of each attribute node in $content.

      2. upd:replaceNode creates one namespace binding on the $target element corresponding to the implied namespace binding of the name of each attribute node in $replacement.

      3. upd:rename creates a namespace binding on $target, or on the parent (if any) of $target if $target is an attribute node, corresponding to the implied namespace binding of $newName.

3.2.2 upd:applyUpdates

Parameters

upd:applyUpdates(
   $pul as pending-update-list,
   $revalidation-mode as xs:string,
   $inherit-namespaces as xs:boolean)

Summary

This routine ends a snapshot by making effective the semantics of all the update primitives on a pending update list and by revalidating the resulting XDM instance.

Constraints

$revalidation-mode must be "strict", "lax", or "skip"

Semantics

1. Checks the update primitives on $pul for compatibility. Raises a dynamic error if any of the following conditions are detected:

   1. Two or more upd:rename primitives on $pul have the same target node [err:XUDY0015].

   2. Two or more upd:replaceNode primitives on $pul have the same target node [err:XUDY0016].

   3. Two or more upd:replaceValue primitives on $pul have the same target node [err:XUDY0017].

   4. Two or more upd:replaceElementContent primitives on $pul have the same target node [err:XUDY0017].

   5. Two or more upd:put primitives on the merged list have the same $uri operand [err:XUDY0031].

   6. Two or more primitives on $pul create conflicting namespace bindings for the same element node [err:XUDY0024]. The following kinds of primitives create namespace bindings:

      1. upd:insertAttributes creates one namespace binding on the $target element corresponding to the implied namespace binding of the name of each attribute node in $content.

      2. upd:replaceNode creates one namespace binding on the $target element corresponding to the implied namespace binding of the name of each attribute node in $replacement.

      3. upd:rename creates a namespace binding on $target, or on the parent (if any) of $target if $target is an attribute node, corresponding to the implied namespace binding of $newName.

2. The semantics of all update primitives on $pul, other than upd:put primitives, are made effective in the following order:

   1. First, all upd:insertInto, upd:insertAttributes, upd:replaceValue, and upd:rename primitives are applied.

   2. Next, all upd:insertBefore, upd:insertAfter, upd:insertIntoAsFirst, and upd:insertIntoAsLast primitives are applied.

   3. Next, all upd:replaceNode primitives are applied.

   4. Next, all upd:replaceElementContent primitives are applied.

   5. Next, all upd:delete primitives are applied.

3. If, as a net result of the above steps, the children property of some node 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 node identity of the resulting text node is implementation-dependent.

4. If, as a net result of the above steps, the children property of some node contains an empty text node, that empty text node is deleted from the children property.

5. If, after applying the updates, any XDM instance (including a node that has been deleted or detached from its parent, or that is a descendant of such a node) violates any constraint specified in [XQuery and XPath Data Model (XDM) 3.0], a dynamic error is raised [err:XUDY0021].

   Note:

   For example, a data model constraint violation might occur if multiple attributes with the same parent have the same qualified name (see Section 6.2.1 Overview^DM.)

   Note:

   During processing of a pending update list, an XDM instance may temporarily violate a data model constraint. An error is raised only if a constraint remains unsatisfied after all update primitives other than upd:put have been applied.

6. If $inherit-namespaces is true, then upd:propagate-namespace($element, $prefix, $uri) is invoked for each namespace binding that was marked for namespace propagation, where $element is the element node on which the namespace binding appears, $prefix is the namespace prefix, and $uri is the namespace URI. Each of these nodes is then unmarked.

7. For each document or element node $top that was marked for revalidation by one of the earlier steps, upd:revalidate($top, $revalidation-mode) is invoked. Each of these nodes is then unmarked.

8. As the final step, all upd:put primitives on $pul are applied.

9. The upd:applyUpdates operation is atomic with respect to the data model. In other words, if upd:applyUpdates terminates normally, the resulting XDM instance reflects the result of all update primitives; but if upd:applyUpdates raises an error, the resulting XDM instance reflects no changes. Atomicity is guaranteed only with respect to operations on XDM instances, and only with respect to error conditions specified in this document.

   Note:

   The results of implementation-dependent error conditions such as exceeding resource limits are beyond the scope of this specification.

10. Propagation of XDM changes to an underlying persistent store is beyond the scope of this specification. For example, the effect on persistent storage of deleting a node that has no parent is beyond the scope of this specification.

3.2.3 upd:revalidate

Parameters

upd:revalidate(
   $top as node(),
   $revalidation-mode as xs:string)

Constraints

$top must be a document node or an element node.

$revalidation-mode must be "strict", "lax", or "skip".

Summary

Schema validation is applied to the subtree rooted at $top in order to recover the types of updated nodes while preserving their node identities.

Semantics

If $revalidation-mode is skip, upd:revalidate performs no action. Otherwise:

1. If $revalidation-mode is lax, define $topV as the result of the XQuery expression validate lax {$top}. If $revalidation-mode is strict, define $topV as the result of the XQuery expression validate strict {$top}. During computation of $topV, it is necessary to maintain a mapping between each node in $topV and the corresponding node (if any) in the subtree rooted at $top (this mapping is maintained in an implementation-dependent way.)

   Note:

   • This step may raise an error [err:XQDY0027]^XQ30 if $top is found to be invalid.

   • Some of the nodes in $topV (for example, default attributes generated by the validation process) may have no corresponding nodes in $top.

2. For each node $nV in $topV that has a corresponding node $n in $top, replace the following properties of $n with the corresponding properties of $nV: type-name, typed-value, string-value, is-id, is-idrefs, namespace-bindings, nilled.

3. For each node $nV in $topV that does not have a corresponding node in $top, insert the node $nV into the subtree rooted at $top as a child or attribute of the node corresponding to the parent of $nV.

4. The result of upd:revalidate is to modify the properties of the nodes rooted at $top and possibly to add some new nodes to this subtree. When the revalidation process is complete, $topV can be discarded.

Note:

After revalidation, the type annotations of the nodes in the validated subtree are consistent with their content. It is expected that implementations will optimize the revalidation process by taking into account which nodes have been modified since they were last validated.

3.2.4 upd:removeType

Parameters

upd:removeType(
   $N as node())

Constraints

$N must be an element or attribute node

Summary

This routine is applied to a node whose name or content has been modified, in order to remove specific type information from the node and its ancestors, pending revalidation.

Semantics

1. If $N is an element node, its properties are changed as follows:

   1. If type-name is not equal to xs:untyped, then

      1. type-name is set to xs:anyType

      2. If the parent of N is an element node, then upd:removeType(parent($N)) is invoked.

   2. string-value is set equal to the concatenated contents of the text node descendants, in document order.

   3. typed-value is set equal to the string-value property, as an instance of xs:untypedAtomic.

      Note:

      The data model allows some flexibility to implementations regarding whether string-value and/or typed-value are stored or computed dynamically.

   4. nilled, is-id, and is-idrefs are set to false.

2. If $N is an attribute node, its properties are changed as follows:

   1. type-name is set to xs:untypedAtomic.

   2. typed-value is set equal to the string-value property, as an instance of xs:untypedAtomic.

   3. is-id and is-idrefs are set to false.

   4. If $N has a parent, upd:removeType(parent($N)) is invoked.

3. The topmost ancestor of $N is marked for revalidation.

   [Definition: To mark a node means to identify the node as participating in a later operation.] Marking of nodes is accomplished in an implementation-dependent way--for example, an implementation might maintain a list of marked nodes.

3.2.5 upd:setToUntyped

Parameters

upd:setToUntyped(
   $N as node())

Constraints

$N must be an element or attribute node

Summary

This routine is applied to a node that has been inserted into an untyped context, which requires that the node and its descendants be untyped as well.

Semantics

1. If $N is an element node, its properties are changed as follows:

   1. type-name is set to xs:untyped.

   2. typed-value is set equal to the string-value property, as an instance of xs:untypedAtomic.

      Note:

      The data model allows some flexibility to implementations regarding whether string-value and/or typed-value are stored or computed dynamically.

   3. nilled, is-id, and is-idrefs are set to false.

   4. upd:setToUntyped() is invoked on the attributes and child element nodes of $N.

2. If $N is an attribute node, its properties are changed as follows:

   1. type-name is set to xs:untypedAtomic.

   2. typed-value is set equal to the string-value property, as an instance of xs:untypedAtomic.

   3. is-idrefs is set to false.

   4. is-id is set to false if the attribute name is not xml:id.

3.2.6 upd:propagateNamespace

Parameters

upd:propagateNamespace(
   $element as element(), 
   $prefix as xs:NCName, 
   $uri as xs:anyURI)

Constraints

None

Summary

Propagates a namespace binding to all descendants of an element.

Semantics

For each element $child among the children of $element that does not have a namespace binding for $prefix,

1. add a namespace binding ($prefix, $uri) to $child

2. call upd:propagateNamespace($child, $prefix, $uri)