XQuery Update Facility 3.0

1.1 Terminology

[Definition: Within this document, the term XQuery 3.0 refers to the language specified by [XQuery 3.0: An XML Query Language].] [Definition: The term data model refers to the data model specified by [XQuery and XPath Data Model (XDM) 3.0].] [Definition: The term XDM instance denotes an unconstrained sequence of zero or more nodes and/or atomic values as defined by the data model.] [Definition: The term node identity denotes the unique identity that is a property of every node in an XDM instance (see Section 2.3 Node Identity ^DM30.)]

As described in Section 3.3.3 QNames and NOTATIONS ^DM30, names in XQuery are qualified names (QNames) that consist of an optional namespace prefix, a local name, and an optional namespace URI. [Definition: The implied namespace binding of a QName is the association of its namespace prefix (or absence thereof) with its namespace URI (or absence thereof).] [Definition: Two namespace bindings are said to conflict if their namespace prefixes (or absence thereof) are the same but their namespace URI's (or absence thereof) are different.] Update operations that result in conflicting namespace bindings generally raise errors, as described in this document. However, if the namespace prefix of an attribute is absent, it is in no namespace, and its implied namespace binding is not added to the namespace bindings of its parent element. Therefore, an update operation can create such an attribute in an element even though its implied namespace binding conflicts with a namespace binding in the "namespaces" property of the element.

In this document, examples and material labeled as "Note" are provided for explanatory purposes and are not normative.

2.1 Pending Update Lists

[Definition: A pending update list is an unordered collection of update primitives, which represent node state changes that have not yet been applied. ] The term "result" used in Section 2.3.4 Errors and Optimization ^XQ30 includes both the XDM instance and the pending update list returned by an expression.

XQuery Update Facility 3.0 relaxes many of the constraints placed on the position of updating expressions in [XQuery Update Facility 1.0] with the goal of allowing expressions to return both a non-empty pending update list and a non-empty XDM instance. Existing expressions are extended with new rules to determine the category and resulting pending update list when they are executed.

2.2 Updating Expressions

XQuery Update Facility 3.0 introduces a new category of expression, called an updating expression. Unlike expressions defined in [XQuery 3.0: An XML Query Language], updating expressions can potentially result in the modification of the state of an existing node. [Definition: An updating expression is an expression that can return a non-empty pending update list. This includes basic updating expressions, static function calls to an updating function, or any expression that directly contains an updating expression (other than the modify expression of a copy modify or transform with expression). ] [Definition: A simple expression is any XQuery expression that is not an updating expression. ]

The classification of each expression into one of the above categories is performed by static analysis, according to rules specified in this document for each type of expression.

[Definition: Five new kinds of expressions named basic updating expression are introduced, including insert, delete, replace, rename, and dynamic updating function invocation expressions. Basic updating expression are always classified as updating expressions. ] In addition two new kinds of expressions named transform with, and copy modify expressions can apply pending update lists to copies of nodes. These expressions are usually classified as simple expressions rather than updating expressions.

2.3 Updating Functions

[Definition: An updating function is a function^DM30 which can return a non-empty pending update list when called. ] [Definition: If a function is not an updating function, then it is a simple function. ]

2.4 Update Operations

XQuery Update Facility 3.0 also defines a set of update operations. [Definition: Update operations are used in defining the semantics of XQuery updates, but are not directly available to users. Update operations are defined in [8 Update Operations]. ] Update operations fall into the following categories:

1. [Definition: Update primitives are the components of pending update lists. Each update primitive represents a node state change that has not yet been applied. ] [Definition: The first argument of an update primitive, called its target node, is the principal node to be affected by the update primitive. ] Update primitives are held on pending update lists until they are made effective by a upd:applyUpdates operation.

2. [Definition: Update routines are sequences of actions that are used in the definition of XQuery semantics but do not appear on pending update lists. ] upd:applyUpdates is an example of an update routine.

2.5 Applying Pending Updates

If the outermost expression in a query returns a non-empty pending update list, upd:applyUpdates is implicitly invoked, supplying as arguments (a) the pending update list, and (b) the value of the revalidation mode in the static context of the main module. This invocation of upd:applyUpdates may raise an error (see [8.2.3 upd:applyUpdates] for possible error codes.)

[Definition: A snapshot is a scope within which expressions are evaluated with respect to a fixed XDM instance and updates are held pending. ] A snapshot is terminated by invocation of the upd:applyUpdates operation. XQuery Update Facility 3.0 defines an entire query as one snapshot.

2.6 Revalidation

In general, updating expressions cause a loss of type information from nodes that are affected by the update. Type information for these nodes may be recovered by a revalidation process at the end of the snapshot. Revalidation is defined by the upd:revalidate update routine. More information about type loss during update operations can be found in [8.1 Update Primitives], as well as [8.2.5 upd:removeType].

3.1 Revalidation Mode

[Definition: Revalidation mode, which may be strict, lax, or skip, is a component of the static context that controls the behavior of the upd:revalidate operation. ]

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 [4.1 Revalidation Declaration] specifies a revalidation mode that is not supported by the current implementation, a static error is raised [err:XUST0026].

The table of static context components Section C.1 Static Context Components ^XQ30 is augmented with the following new row:

• Component: Revalidation mode

• Default initial value: lax.

• Can be overwritten or augmented by an implementation: Overwritable (implementation defined.)

• Can be overwritten or augmented by prolog: Overwritable using a prolog declaration.

• Can be overwritten or augmented by expressions: No.

• Consistency rules: Must be strict, lax, or skip.

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 of the module, 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 [8.2.4 upd:revalidate]

4.2 Function Declaration

Functions can be declared as updating functions using the %updating annotation, or the equivalent backwards-compatible bare keyword updating. The built-in function fn:put is also specified as an updating function. If a function is not declared with the %updating annotation, or if it is declared with the %simple annotation it is a simple function.

Category Rules:

• If a simple function is not declared as external, its FunctionBody must be a simple expression [err:XUST0001].

• If a simple function is declared as external, evaluation of the external function must not return a non-empty pending update list; otherwise a dynamic error is raised [err:XUDY0018].

• An updating function may have a FunctionBody of any category.

Additional Semantics:

XQuery Update Facility 3.0 allows an updating function to return both a non-empty pending update list and a non-empty XDM instance.

If the result of an updating function does not match its declared return type (after applying function conversion rules as specified in Section 3.1.5 Function Calls^XQ), a type error is raised [err:XPTY0004]^XQ30. The default return type of an updating function is item()*.

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

Example:

• 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
     }

4.3 Variable Declaration

Category Rules:

• The VarValue or VarDefaultValue of a variable declaration must be a simple expression [err:XUST0001].

4.4 Context Item Declaration

Category Rules:

• The VarValue or VarDefaultValue of a context item declaration must be a simple expression [err:XUST0001].

5.1 Insert

An insert expression 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.

Category Rules:

• An insert expression is an updating expression.

• The SourceExpr and TargetExpr can be expressions of any category.

Semantics:

1. 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. TargetExpr 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 by merging the pending update lists returned by the SourceExpr and TargetExpr with the following update primitives using upd:mergeUpdates:

   1. If as first into is specified, the pending update list includes 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 includes 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 includes 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 includes 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 includes the following update primitives:

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

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

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

5.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.

Category Rules:

• A delete expression is an updating expression.

• The TargetExpr can be an expression of any category.

Semantics:

1. TargetExpr 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 is merged with the pending update list returned by the TargetExpr using upd:mergeUpdates, and together with an empty XDM instance forms the result of the delete 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")]

5.3 Replace

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

5.4 Rename

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

Category Rules:

• A rename expression is an updating expression.

• The NewNameExpr and TargetExpr can be expressions of any category.

Semantics:

1. TargetExpr 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 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 constructed by merging the pending update lists returned by the NewNameExpr and TargetExpr with the following update primitives using upd:mergeUpdates: upd:rename($target, $QName).

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

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)
)

5.5 Dynamic Updating Function Invocation

A dynamic updating function call dynamically invokes an updating function. A dynamic updating function call is constrained by the grammar so that it cannot be a partial function application^XQ30.

Category Rules:

• A dynamic updating function call is an updating expression.

• The PrimaryExpr and any argument expressions^XQ30 can be expressions of any category.

Semantics:

A dynamic updating function call is evaluated like a dynamic function invocation, as specified in Section 3.2.2 Dynamic Function Call ^XQ30. However unlike [7.11 Dynamic Function Invocation] it can invoke either an updating function or a simple function, and could therefore potentially return a non-empty pending update list.

The result of the dynamic updating function call is the XDM instance returned by the function invoked, as well as a pending update list constructed by merging the pending update lists returned by the PrimaryExpr and any argument expressions^XQ30, with the pending update list returned by the function invoked using upd:mergeUpdates.

Example:

• Dynamically call the fn:put() function.

  let $f := fn:put#2
  return invoke updating $f(<newnode/>,"newnode.xml")

5.6 Copy Modify

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

A copy modify expression consists of three clauses, denoted by the keywords copy, modify, and return.

Category Rules:

• If all of the copy modify expression's copy and return clauses have operand expressions that are simple expressions, then the copy modify expression is a simple expression.

• If any of the copy modify expression's copy or return clauses have operand expressions that are updating expressions, then the copy modify expression is a updating expression.

• The operand expressions of any of the clauses of a copy modify expression can be expressions of any category.

Semantics:

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 result of evaluating the source expression must be a single node [err:XUTY0013]. Let $node be this single node.

   2. 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 document node, the document-uri property is set to empty.

      2. 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.

      3. 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.

      4. 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.

      5. 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.

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

   3. 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 copy modify 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 expression in the modify clause is evaluated, resulting in a pending update list (denoted $pul) and an XDM instance. The XDM instance is discarded, and does not form part of the result of the copy modify expression.

   If the target node of any update primitive in $pul is a node that was not newly created in Step 1, a dynamic error is raised [err:XUDY0014]. If $pul contains a upd:put update primitive, a dynamic error is raised [err:XUDY0037].

3. Let $revalidation-mode be the value of the revalidation mode in the static context of the library or main module containing the copy modify expression, and $inherit-namespaces be the value of inherit-namespaces in the static context of the copy modify 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 [8.2.3 upd:applyUpdates].

4. The return clause is evaluated, resulting in a pending update list and an XDM instance. The result of the copy modify expression is the XDM instance returned, as well as a pending update list constructed by merging the pending update lists returned by any of the copy modify expression's copy or return clause operand expressions using upd:mergeUpdates. During evaluation of the return clause, changes applied to copied nodes by the preceding step are visible.

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.

5.7 Transform With

The TransformWithExpr is a convenient short hand for the common use case of wanting to apply updates to a copy of a single node. If N and U are arbitrary expressions, and $v is a variable name that is otherwise unused in U, then the following TransformWithExpr:

N transform with { U }

is equivalent to the following longer form CopyModifyExpr:

copy $v := N
modify $v!(U)
return $v

5.8 Compatibility of Updating Expressions

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

6.1 fn:put

The fn:put function 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.

The $params argument is used to identify a set of serialization parameters. These are supplied in the form of an output:serialization-parameters element, having the format described in Section 3.1 Setting Serialization Parameters by Means of a Data Model Instance ^SER30. The two-argument version of this function, or the three argument version with the empty sequence as the third argument, are equivalent to passing an output:serialization-parameters element with no child elements.

Category Rules:

fn:put is an updating function.

Semantics:

1. 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].

2. 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.

3. An implementation that serializes $node during storage MUST use the serialization parameters to determine how serialization is performed. In this case, the implementation should raise a dynamic error if setting the serialization parameters produces a serialization error or if an invalid parameter value is detected. An implementation may ignore the $params argument (because it does not perform serialization) but must not raise an error because serialization parameters are specified.

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,$params).

7.1 FLWOR Expression

The syntax of the FLWOR expression is not changed.

Category Rules:

• The category of the FLWOR expression is the same as the category of the expression in its ReturnClause.

• If any ForClause, LetClause, WindowClause, WhereClause, GroupByClause, or OrderByClause has operand expressions that are an updating expression, an error is raised [err:XUST0001].

• The ReturnClause may contain any category of expression.

Additional Semantics:

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.

2. The result of the FLWOR expression is the concatenation of the XDM instances and pending update lists returned by evaluating the ReturnClause on each tuple generated by the previous step. Pending update lists are concatenated by the upd:mergeUpdates operation.

   Note:

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

Example:

• 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

7.2 Typeswitch Expression

The syntax of the typeswitch expression is not changed. The return expressions in the CaseClauses and default clause are called branches, and the expression in parentheses after the keyword typeswitch is called the test.

Category Rules:

• If all branches of the typeswitch expression are simple expressions, then the typeswitch expression is a simple expression.

• If any branch of the typeswitch expression is an updating expression, then the typeswitch expression is an updating expression.

• If test is an updating expression, an error is raised [err:XUST0001].

• The branches of a typeswitch expression can be expressions of any category.

Additional Semantics:

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 an XDM instance and pending update list, which serves as the result of the typeswitch expression.

7.3 Switch Expression

The syntax of the switch expression is not changed. The return expressions in the CaseClauses and default clause are called branches, and the expression in parentheses after the keyword switch is called the test.

Category Rules:

• If all branches of the switch expression are simple expressions, then the typeswitch expression is a simple expression.

• If any branch of the switch expression is an updating expression, then the switch expression is an updating expression.

• If test or a SwitchCaseOperand is an updating expression, an error is raised [err:XUST0001].

• The branches of a switch expression can be expressions of any category.

Additional Semantics:

Selection of the effective case is performed as specified in Section 3.13 Switch Expression ^XQ30. The expression in the return clause of the effective case (or default) is then evaluated, resulting in an XDM instance and pending update list, which serves as the result of the switch expression.

7.4 Conditional Expression

The syntax of conditional expression is not changed. The operands of the then and else clauses are called branches, and the expression in parentheses after the keyword if is called the test.

Category Rules:

• If all branches of the conditional expression are simple expressions, then the conditional expression is a simple expression.

• If any branch of the conditional expression is an updating expression, then the conditional expression is an updating expression.

• If test is an updating expression, an error is raised [err:XUST0001].

• The branches of a conditional expression can be expressions of any category.

Additional Semantics:

Selection of the effective branch performed as specified in Section 3.12 Conditional Expressions ^XQ30. The result of the conditional expression is the XDM instance and pending update list returned by the selected branch.

Example:

• 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

7.5 Try/Catch Expression

Category Rules:

• If the TryTargetExpr and all of the catch expressions are simple expressions, then the try/catch expression is a simple expression.

• If the TryTargetExpr or one of the catch expressions is an updating expression, then the conditional expression is an updating expression.

• If the TryTargetExpr and all of the catch expressions can be expressions of any category.

Additional Semantics:

The TryTargetExpr is evaluated, resulting in a pending update list or raising an error. If a pending update list is returned, it is checked for compatibility using upd:compatibilityCheck, which may also raise an error. If an error has not been raised, the result of the try/catch expression is the XDM instance and pending update list returned by it. However if it raises an error the result of the try/catch expression is the XDM instance and pending update list returned by executing the CatchClause matching the error, as defined in Section 3.15 Try/Catch Expressions ^XQ30.

7.6 Comma Expression

The comma expressions is composed of one or more expressions concatenated by the comma operator, as described in Section 3.4.1 Constructing Sequences ^XQ30.

Category Rules:

• If the operand expressions of the comma expression are simple expressions, then the comma expression is a simple expression.

• If any of the operand expressions of the comma expression is an updating expression, then the comma expression is an updating expression.

• The operand expressions of a comma expression can be expressions of any category.

Additional Semantics:

The operand expressions of the comma expression are evaluated, and the XDM instances and pending update lists returned are concatenated in operand order. Pending update lists are concatenated by the upd:mergeUpdates operation.

Examples:

• 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 )

7.7 Parenthesized Expression

Category Rules:

The category of a parenthesized expression is the same as the category of the expression enclosed in parentheses, which may have any category.

Additional Semantics:

The result of a parenthesized expression is the same as the result of the expression enclosed in parentheses.

7.8 Extension Expression

Category Rules:

The category of an extension (pragma) expression is the same as the category of the enclosed expression, which may have any category.

Additional Semantics:

The result of an extension (pragma) expression is the same as the result of the enclosed expression.

7.9 Inline Functions

The %simple and %updating annotations can be specified at the start of the inline function expression, to force the creation of a simple or updating function repectively.

Category Rules:

1. If neither %simple nor %updating is specified:

   1. The FunctionBody can be an expression of any category.

   2. If the FunctionBody is an updating expression, the inline function expression is a simple expression, returning an updating function.

   3. If the FunctionBody is a simple expression, the inline function expression is a simple expression, returning a simple function.

2. If %simple is specified:

   1. The FunctionBody must not be an updating expression [err:XUST0001]

   2. The inline function expression is a simple expression, returning a simple function.

3. If %updating is specified:

   1. The FunctionBody can be an expression of any category.

   2. The inline function expression is a simple expression, returning an updating function.

4. It is a static error to use more than one %updating or %simple annotation in a given annotation set [err:XUST0033].

7.10 Function Calls

Function calls can either be a partial function application^XQ30 or not.

Category Rules:

• If the function call is a partial function application^XQ30 of an updating function, then it is a simple expression returning an updating function.

• If the function call is a partial function application^XQ30 of a simple function, then it is a simple expression returning an simple function.

• A function call of a simple function is a simple expression.

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

• The argument expressions^XQ30 of a function call or partial function application^XQ30 can be expressions of any category.

Additional Semantics:

The function call is evaluated as specified in Section 3.1.5 Static Function Calls ^XQ30. All pending update lists returned by the evaluation of argument expressions^XQ30 are concatenated with the pending update list returned by evaluating the function to form the pending update list returned from the function call expression.

7.11 Dynamic Function Invocation

Dynamic function invocation can either be a partial function application^XQ30 or not.

Category Rules:

• A dynamic function invocation is a simple expression.

• The PrimaryExpr and the argument expressions^XQ30 of a dynamic function invocation can be expressions of any category.

Additional Semantics:

The dynamic function invocation is evaluated as specified in Section 3.2.2 Dynamic Function Call ^XQ30.

If the function returned by the PrimaryExpr is an updating function, and the dynamic function invocation is not a partial function application^XQ30, a dynamic error is raised [err:XUDY0038]. To perform dynamic function invocation of an updating function, [5.5 Dynamic Updating Function Invocation] should be used.

All pending update lists returned by the evaluation of the PrimaryExpr or argument expressions^XQ30 are concatenated to form the pending update list returned from the dynamic function invocation expression.

7.12 Direct and Computed Node Constructors

Category Rules:

• If all operand expressions of the node constructor are simple expressions then the node constructor is a simple expression.

• If any operand expression of the node constructor is an updating expression then the node constructor is an updating expression.

• The operand expressions of a node constructor may be expressions of any category.

Additional Semantics:

The pending update lists returned by each of the operand expressions are merged by calling upd:mergeUpdates, and returned as the pending update list part of the result of the node constructor.

7.13 Other Expressions

All other XQuery expressions not listed in the sections preceeding this are extended as follows:

Category Rules:

• The expression is a simple expression.

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

8.1 Update Primitives

The update primitives described in this section may be held on pending update lists. When an update primitive is held on a pending update list, its node operands are represented by their node identities. The semantics of an update primitive do not become effective until their pending update list is processed by the upd:applyUpdates routine.

8.2 Update Routines

9.1 Minimal Conformance

Minimal Conformance to this specification MUST include all of the following items:

1. Minimal Conformance to [XQuery 3.0: An XML Query Language].

2. Support for everything specified in this document except those features specified in [9.2 Optional Features] to be optional and [E XML Syntax (XQueryX) for XQuery Update Facility 3.0]. If an implementation does not provide a given optional feature, it MUST implement any requirements specified in [9.2 Optional Features] for implementations that do not provide that feature.

3. A definition of every item specified to be implementation-defined, unless that item is part of an optional feature that is not supported by the implementation. A list of implementation-defined items can be found in [B Implementation-Defined Items].

   Note:

   Implementations are not required to define items specified to be implementation-dependent.

9.2 Optional Features

An implementation of XQuery that includes the Update Facility MAY also support the Optional Features of [XQuery 3.0: An XML Query Language]. These are Schema Import Feature, Schema Validation Feature, Full Axis Feature, Module Feature, and Serialization Feature.

9.3 XQuery with Multiple Results

A subset of the XQuery Update 3.0 specification called "XQuery with Multiple Results" is defined for the purposes of implementations only wishing to allow multiple results to be returned from an XQuery program. Implementations claiming conformance to the "XQuery with Multiple Results" subset MUST include all of the following items:

1. Minimal Conformance to [XQuery 3.0: An XML Query Language].

2. Support for the facilities described in the following sections of this document:

   • [2 Extensions to the Processing Model]

   • [4.2 Function Declaration] excluding %updating and %simple annotations.

   • [4.3 Variable Declaration] excluding %updating and %simple annotations.

   • [4.4 Context Item Declaration]

   • [3 Extensions to the Static Context]

   • [7 Extensions to Existing Expressions]

   • [6.1 fn:put]

   • [8.1.12 upd:put]

   • [8.2 Update Routines]

3. Use of other types of XQuery Update 3.0 expression SHOULD result in an error [err:XPST0003]^XP30.