This document defines an update facility that extends the XML Query language, XQuery. The XQuery Update Facility provides expressions that can be used to make persistent changes to instances of the XQuery 1.0 and XPath 2.0 Data Model.
W3C publishes a
This document has been developed by the W3C
The
A test suite is available that tests each identified XQuery Update Facility feature, both required and optional.
Minimal Conformance to this specification, as defined in
The Working Group has responded formally to all issues raised during the CR period against this document.
Once the entrance criteria for Proposed Recommendation have been achieved,
the Director will be requested to advance this document to
The following features are considered to be at risk:
They may be removed if implementations of them do not exist at the end of the Candidate Recommendation period.
The XML Query WG is republishing this document on 1 August 2008, to reflect changes made in response to comments received so far during the Candidate Recommendation period.
The WG still solicits comment on a key design principle of this specification:
As indicated in
A Test Suite for this document is under development.
Implementors are encouraged to run this test suite and report their results.
The Test Suite can be found at
This document incorporates changes made against the
Please report errors in this document using W3C's
Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the
September 2005: First internal draft
November 2005: Second internal draft
27 January 2006: First public working draft
8 May 2006: Second public working draft
11 July 2006: Third public working draft
28 August 2007: Last Call working draft
14 March 2008: Candidate Recommendation
1 August 2008: Revised Candidate Recommendation
This document defines the syntax and semantics of an extension
to
The XQuery Update Facility 1.0 provides facilities to perform any or all
of the following operations on an
Insertion of a node.
Deletion of a node.
Modification of a node by changing
some of its properties while preserving its
Creation of a modified copy of a node with a new
Additionally, this document defines an XML syntax for the XQuery Update Facility 1.0.
The most recent versions of the two XQueryX XML Schemas and the
XQueryX XSLT stylesheet for the XQuery Update Facility 1.0 are available at
As described in
The basic building block of XQuery is the expression. XQuery 1.0 provides
several kinds of expressions that can be composed with each other in
arbitrary ways. An XQuery 1.0 expression takes zero or more
XQuery Update Facility 1.0 introduces a new category of expression called an
The extensions to XQuery 1.0 provided by XQuery Update Facility 1.0 may be characterized as follows:
XQuery Update Facility 1.0 introduces five new kinds of expressions, called insert, delete, replace, rename, and transform expressions, and specifies the syntax and semantics of each new kind of expression.
XQuery Update Facility 1.0 classifies XQuery expressions into the following categories: The definition of an
XQuery Update Facility 1.0 defines the places in which each type of expression can be used. In so doing, it makes small extensions to the syntax and semantics of certain existing expressions.
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.
XQuery Update Facility 1.0 defines the following extensions to the XQuery processing model:
In XQuery 1.0, the result of each expression is an
In XQuery Update Facility 1.0, no expression returns both a non-empty
XQuery Update Facility 1.0 also defines a set of
upd:applyUpdates operation.
upd:applyUpdates is an example of an update routine.
If the outermost expression in a query returns a 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 query module. This invocation of upd:applyUpdates may raise an error (see
upd:applyUpdates operation. XQuery Update Facility 1.0 defines an entire query as one snapshot.
This specification defines the semantics of updates to an
The Prolog is extended by adding a new kind of
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
The following rule is added: If the expression on the right-hand-side of a variable declaration (the initializing expression) is not a
The syntax of a function declaration is extended to include an optional keyword: updating. updating, and certain built-in functions including fn:put, are called
If updating is not specified:
If external is not specified, the EnclosedExpr in the function declaration must be a
If external is specified, the external function must not return a non-empty
If updating is specified:
A return type must not be specified
If external is not specified, the EnclosedExpr in the function declaration must be an
If external is specified, the external function may return a non-empty
The means by which an external function returns an
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.
The following definition is added to the XQuery static context
(documented in
strict, lax, or skip,
is a component of the static context that controls the behavior of the
upd:revalidate operation.
The following entry is added to the table of static context components
(documented in
Component: Revalidation mode
Default initial value: lax.
Can be overwritten by an implementation: Yes (implementation defined.)
Can be overwritten by a query: Yes, overwritable by declaration in query prolog.
Scope: Module.
Consistency rules: Must be strict, lax, or skip.
XQuery Update Facility 1.0 extends the syntax of
In general,
An insert expression is an 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
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
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.
Navigating by means of several bound variables, insert a new police report into the list of police reports for a particular accident.
The semantics of an insert expression are as follows:
$alist be the sequence of attribute nodes in the insertion sequence. Let $clist be the remainder of the insertion sequence, in its original order.
Either $alist or $clist or both may be empty.
The target expression must be a
If the result is an empty sequence,
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
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
If before or after
is specified, the node returned by the target expression must have a non-empty parent property
Let
$target be the node returned by the target expression.
If $alist is not empty and any form of into is specified, the following checks are performed:
$target must be an element node
No attribute node in $alist may have a QName whose $target
Multiple attribute nodes in $alist may not have QNames whose
If $alist is not empty and before or after is specified, the following checks are performed:
parent($target) must be an element node
No attribute node in $alist may have a QName whose parent($target)
Multiple attribute nodes in $alist may not have QNames whose
The result of the insert expression is an empty
If as first into is specified, the
If $alist is not empty, upd:insertAttributes($target, $alist)
If $clist is not empty, upd:insertIntoAsFirst($target, $clist)
If as last into is specified, the
If $alist is not empty, upd:insertAttributes($target, $alist)
If $clist is not empty, upd:insertIntoAsLast($target, $clist)
If into is specified with neither as first nor as last, the
If $alist is not empty, upd:insertAttributes($target, $alist)
If $clist is not empty, upd:insertInto($target, $clist)
If before is specified, let $parent be the parent node of $target. The
If $alist is not empty, upd:insertAttributes($parent, $alist)
If $clist is not empty, upd:insertBefore($target, $clist)
If after is specified, let $parent be the parent node of $target. The
If $alist is not empty, upd:insertAttributes($parent, $alist)
If $clist is not empty, upd:insertAfter($target, $clist)
A delete expression deletes zero or more nodes from an node and nodes may be used interchangeably, regardless of how many nodes are actually deleted. A delete expression is an
Examples:
Delete the last author of the first book in a given bibliography.
Delete all email messages that are more than 365 days old.
The semantics of a delete expression are as follows:
The target expression must be a $tlist be the list of nodes returned by
the target expression.
If any node in $tlist has no parent, an implementation may (but is not required to) raise a dynamic error
A new $tnode in $tlist, the following upd:delete($tnode). The resulting
pending update list (together with an empty
Since node deletions do not become effective until the end of a
The semantics of a delete expression are defined in terms of their effect on an
A replace expression is an value of
is specified.
If value of is not specified, a replace expression
replaces one node with a new sequence of zero or more nodes. The replacement nodes occupy the position in the node hierarchy that was formerly occupied by the node that was replaced. For this reason, an attribute node can be replaced only by zero or more attribute nodes, and an element, text, comment, or processing instruction node can be replaced only by zero or more element, text, comment, or processing instruction nodes. Example:
Replace the publisher of the first book with the publisher of the second book.
The semantics of this form of replace expression are as follows:
The expression following the keyword with must be a $rlist be the node sequence that results from this evaluation. If $rlist contains a document node, the document node is replaced in $rlist by its children.
The target expression must be a
If the result is an empty sequence,
If the result is non-empty and does not consist of a single element, attribute, text, comment, or processing instruction node,
If the result consists of a node whose parent property is empty,
Let
$target be the node returned by the target expression, and let $parent be its parent node.
If $target is an element, text, comment, or processing
instruction node, then $rlist must consist exclusively of zero or more element, text, comment, or processing instruction nodes
If $target is an attribute node, then:
$rlist must consist exclusively of zero or more attribute nodes
No attribute node in $rlist may have a QName whose $parent
Multiple attribute nodes in $rlist may not have QNames whose
The result of the replace expression is an empty upd:replaceNode($target, $rlist)
If value of is specified,
a replace expression is used to modify the value of a node while preserving
its
Increase the price of the first book by ten percent.
The semantics of this form of replace expression are as follows:
The expression following the keyword with must be a $text be the result of this step.
The target expression must be a
If the result is an empty sequence,
If the result is non-empty and does not consist of a single element, attribute, text, comment, or processing instruction node,
Let
$target be the node returned by the target expression.
If $target is an element node, the result of the replace
expression is an empty upd:replaceElementContent($target, $text)
If $target is an attribute, text, comment, or processing
instruction node, let $string be the string value of the text node
constructed in Step 1. If Step 1 did not construct
a text node, let $string be a zero-length string.
Then:
If $target is a comment node, and $string contains two adjacent hyphens or ends with a hyphen, a dynamic error is raised
If $target is a processing instruction node, and $string contains the substring "?>", a dynamic error is raised
In the absence of errors, the result of a replace expression is an empty upd:replaceValue($target, $string).
A rename expression replaces the name property of a
Examples:
Rename the first author element of the first book to principal-author.
Rename the first author element of the first book to the QName that is the value of the variable $newname.
The semantics of a rename expression are as follows:
The target expression must be a
If the result is an empty sequence,
If the result is non-empty and does not consist of a single element, attribute, or processing instruction node,
Let
$target be the node returned by the target expression.
If $target is an element node, let $QName be the result of evaluating
$QName
conflicts with any namespace binding in the namespaces property of $target, a
dynamic error is raised
If $target is an attribute node, let $QName be the result of evaluating
$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
If $target is a processing instruction node, let $NCName be the result of
evaluating $QName be
defined as fn:QName((), $NCName).
The result of the rename expression is an empty upd:rename($target, $QName).
The effects of a rename expression are limited to its target node. Attributes and descendants of the target node are not affected. If a global change of names or namespaces is intended, some form of explicit iteration must be used. The following example illustrates such a global change. The example operates on the node bound to variable $root and all its attributes and descendants, changing all QNames with the prefix abc to have a new prefix xyz and a new namespace URI http://xyz/ns.
A transform expression can be used to create modified copies of existing nodes in an
Examples:
Return a sequence consisting of all employee elements that have Java as a skill, excluding their salary child-elements:
The following example copies a node, modifies the copy, and returns both the original node and the modified copy:
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:
The copy clause contains one or more variable bindings, each of which consists of a variable name and an expression called the
The source expression must be a
The result of evaluating the source expression must be a single node $node be this single node.
A new copy is made of $node and all nodes that have $node as an ancestor,
collectively referred to as parent, children, and attributes properties of the copied nodes
are set so as to preserve their inter-node relationships. Other properties of
the copied nodes are determined as follows:
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.
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.
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.
Implementations that store only the typed value of a node are required at this point to convert the typed value to a string form.
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.
All other properties of the copied nodes are preserved.
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.
The modify clause must contain either an ( ), or a call to the fn:error function; otherwise a static error is raised modify clause is evaluated, resulting in a $pul be the pending update list generated by this step.
Let $revalidation-mode be the value of
the revalidation mode in the static context of the transform expression. The following upd:applyUpdates($pul, $revalidation-mode). The effect of this operation is to make the updates specified in the modify clause effective on the copied nodes.
In the event of incompatible updates, the upd:applyUpdates operation may raise an error, as described in
The return clause must contain a 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.
The rules defining compatibility of
The effect of these rules is as follows:
If any node is affected by more than one rename expression within a
If any node is affected by more than one replace expression (without value of being specified) within a
If any node is affected by more than one replace value of expression within a
If multiple calls to fn:put operate on the same URI in the same
Within a given E is the target of a replace value of expression, and the children of E are also modified by other expressions, the final children of E are determined by the replace value of expression. For example:
Suppose that $A is bound to an element node that has a child element named B. Suppose that the following expressions are evaluated in the same
The expressions on the left and right side of the comma can be evaluated in any order. No error is raised. At the end of the $A will consist of a single text node with the content "Goodbye".
XQuery Update Facility 1.0 provides extensions to the semantics of several existing kinds of XQuery expressions, as specified in this section.
The syntax of the FLWOR expression is not changed. Its semantics are extended as follows:
If a for,
let, where, or order by
clause contains an
The return clause may contain any category of expression. The category of the FLWOR expression is the same as the category of the expression in its return clause (simple, vacuous, or updating.)
If the return clause contains a
If the return clause contains an
The semantics of the for,
let, where, and order by
clauses are as specified in
For each tuple
generated by the previous step, the updating expression in the
return clause is evaluated, resulting in a
All the upd:mergeUpdates
operation. The resulting merged pending update list is the
result of the FLWOR expression.
In the event of incompatible updates, the upd:mergeUpdates operation may raise an error, as described in
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.
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
If the operand expression of a typeswitch is an
If any branch is an
If all branches are
Otherwise, the typeswitch expression is a
If the typeswitch expression is a
If the typeswitch expression is an return
clause of the effective case (or default) is then evaluated, resulting
in a
The semantics of
conditional expressions are extended as follows.
Let the expressions in the then and else clauses be called
If the if-clause contains an
If either branch is an
If both branches are
Otherwise, the conditional expression is a
If the conditional expression is a
If the conditional expression is an
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.
The semantics of
comma expressions (composed of one or more expressions concatenated by the comma operator, as described in
If any operand is an
If all operands are
Otherwise, the comma expression is a
If the comma expression is a
If the comma expression is an upd:mergeUpdates
operation. The resulting merged
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.
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
The semantics of a function call are extended as follows:
The function call is evaluated as specified in Section 3.1.5 of
The expression category of a function call is as follows:
A call to the built-in function fn:error is a
A call to an
A call to any other function is a
This includes calls to built-in functions other than fn:error and calls to user-defined functions that were not declared to be updating.
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
In addition, the initializing expression of a variable declaration in a Prolog may not be an
XQuery Update Facility 1.0 provides extensions to XQuery built-in function library, as specified in this section.
$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.
fn:put is an updating function.
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
If
$uri is not a valid lexical representation of the xs:anyURI type, a dynamic error is
raised $uri is a relative URI reference, it is resolved
relative to the value of the base URI property in the static
context.
The result of a call to fn:put is an empty upd:put($node, $uri).
The results of fn:put do not become effective until after completion of the current fn:put function has no effect on the set of available documents or collections seen by the current
If a node that is an operand of fn:put is affected by updating expressions in the current fn:put function operates on the node after these updating expressions are made effective. As a result, after completion of the current $node can be seen via $uri. (For details on application of updates, see
If multiple calls to fn:put in the same fn:put. For a normative description of this error, see
This section describes the update operations defined by XQuery Update Facility 1.0. Although these update operations are described using a functional notation, they are not true functions because many of them have no return value. These update operations are used in defining the semantics of XQuery expressions, but they are not directly available to users.
Update operations consist of
The update primitives described in this section may be held on upd:applyUpdates routine.
Inserts $content immediately before $target.
$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.
Effects on nodes in $content:
For each node in $content, the parent property is set to parent($target).
If the type-name property of parent($target) is xs:untyped, then upd:setToUntyped() is invoked on each element or attribute node in $content.
Effects on parent($target):
The children property of parent($target) is modified to add the nodes in $content just before $target, preserving their order.
If at least one of the nodes in $content is an element or text node, upd:removeType(parent($target)) is invoked.
Inserts $content immediately after $target.
$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.
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.
Inserts $content as the children of $target, in an implementation-dependent position.
$target must be an element or document node. $content must be a sequence containing only element, text, processing instruction,
and comment nodes.
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 include the nodes in $content in implementation-dependent positions, preserving their relative order.
Inserts $content as the first children of $target.
$target must be an element or document node. $content must be a sequence containing only element, text, processing instruction,
and comment nodes.
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 include the nodes in $content as the first children, preserving their order.
Inserts $content as the last children of $target.
$target must be an element or document node. $content must be a sequence containing only element, text, processing instruction,
and comment nodes.
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 include the nodes in $content as the last children, preserving their order.
Inserts $content as attributes of $target.
None
For each node $A in $content:
The parent property of $A is set to $target.
If the type-name property of $target is xs:untyped, then upd:setToUntyped($A) is invoked.
The following properties of $target are changed:
attributes: Modified to include the nodes in $content.
namespaces: Modified to include namespace bindings for any attribute namespace prefixes in $content that did not already have bindings.
upd:removeType($target) is invoked.
None
If $target has a parent node $P, then:
The parent property of $target is set to empty.
If $target is an attribute node, the attributes property of $P is modified to remove $target.
If $target is a non-attribute node, the children property of $P is modified to remove $target.
If $target is an element, attribute, or text node, and $P is an element node, then upd:removeType($P) is invoked.
If $target has no parent, the
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.
Multiple upd:delete operations may be applied to the same node during execution of a query; this is not an error.
Replaces $target with $replacement.
$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.
Effects on nodes in $replacement:
For each node in $replacement, the parent property is set to parent($target).
If the type-name property of parent($target) is xs:untyped, then upd:setToUntyped() is invoked on each element node in $replacement.
Effect on $target:
The parent property of $target is set to empty.
Effects on parent($target):
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).
If $target is an attribute node, the namespaces property of parent($target) is modified to include namespace bindings for any attribute namespace prefixes in $replacement that did not already have bindings.
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.
If $target or any node in $replacement is an element, attribute, or text
node, upd:removeType(parent($target)) is invoked.
Replaces the string value of $target with $string-value.
$target must be an attribute, text, comment, or processing instruction node.
If $target is an attribute node:
string-value of $target is set to $string-value.
upd:removeType($target) is invoked.
If $target is a text, comment, or processing instruction node: content of $target is set to $string-value.
If $target is a text node that has a parent, upd:removeType(parent($target)) is invoked.
Replaces the existing children of the element node $target by the optional text node $text. The attributes of $target are not affected.
None.
For each node $C that is a child of $target, the parent property of $C is set to empty.
The parent property of $text is set to $target.
Effects on $target:
children is set to consist exclusively of $text. If $text is an empty sequence, then $target has no children.
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.
upd:removeType($target) is invoked.
Changes the node-name of $target to $newName.
$target must be an element, attribute, or processing instruction node.
If $target is an element node:
node-name of $target is set to $newName.
upd:removeType($target) is invoked.
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.
The namespaces property of $target is modified to include a namespace binding derived from $newName, if this binding did not already exist.
If $target is an attribute node:
node-name of $target is set to $newName.
upd:removeType($target) is invoked.
If $newName is xml:id, the is-id property of $target is set to true.
If $target has a parent, the namespaces property of parent($target) is modified to include a namespace binding derived from $newName, if this binding did not already exist.
If $target is a processing instruction node, its target property is set to the local part of $newName.
At the end of a upd:applyUpdates.
The XDM node tree rooted at $node is stored to the location specified by $uri.
$uri must be a valid absolute URI.
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.
Merges two
None.
The two
Optionally, upd:mergeUpdates may raise a dynamic error if any of the following conditions are detected:
Two or more upd:rename primitives on the merged list have the same target node
Two or more upd:replaceNode primitives on the merged list have the same target node
Two or more upd:replaceValue primitives on the merged list have the same target node
Two or more upd:replaceElementContent primitives on the merged list have the same target node
Two or more upd:put primitives on the merged list have the same $uri operand
Two or more primitives on the merged list create
upd:insertAttributes creates one namespace binding on the $target element
corresponding to the $content.
upd:replaceNode creates one namespace binding on the $target element
corresponding to the $replacement.
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 $newName.
This routine ends a
$revalidation-mode must be "strict", "lax", or "skip"
Checks the update primitives on $pul for compatibility. Raises a dynamic error if any of the following conditions are detected:
Two or more upd:rename primitives on $pul have the same target node
Two or more upd:replaceNode primitives on $pul have the same target node
Two or more upd:replaceValue primitives on $pul have the same target node
Two or more upd:replaceElementContent primitives on $pul have the same target node
Two or more upd:put primitives on the merged list have the same $uri operand
Two or more primitives on $pul create
upd:insertAttributes creates one namespace binding on the $target element
corresponding to the $content.
upd:replaceNode creates one namespace binding on the $target element
corresponding to the $replacement.
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 $newName.
The semantics of all $pul, other than upd:put primitives, are made effective in the following order:
First, all upd:insertInto, upd:insertAttributes, upd:replaceValue, and upd:rename primitives are applied.
Next, all upd:insertBefore, upd:insertAfter, upd:insertIntoAsFirst, and upd:insertIntoAsLast primitives are applied.
Next, all upd:replaceNode primitives are applied.
Next, all upd:replaceElementContent primitives are applied.
Next, all upd:delete primitives are applied.
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
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.
If the resulting
For example, a data model constraint violation might occur if multiple attributes with the same parent have the same qualified name (see
During processing of a upd:put have been applied.
For each document or element node $top that was upd:revalidate($top, $revalidation-mode) is invoked.
As the final step, all upd:put primitives on $pul are applied.
The upd:applyUpdates operation is atomic with respect to the data model. In other words, if upd:applyUpdates terminates normally, the resulting upd:applyUpdates raises an error, the resulting
The results of implementation-dependent error conditions such as exceeding resource limits are beyond the scope of this specification.
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.
$top must be a document node or an element node.
$revalidation-mode must be "strict", "lax", or "skip".
Schema validation is applied to the subtree rooted at $top in order to recover the types of updated nodes while preserving their
If $revalidation-mode is skip, upd:revalidate performs no action. Otherwise:
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.)
This step may raise an error $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.
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.
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.
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.
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.
$N must be an element or attribute node
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.
If $N is an element node, its properties are changed as follows:
If type-name is not equal to xs:untyped, then
If the parent of type-name is set to xs:anyTypeN is an element node, then upd:removeType(parent($N)) is invoked.
string-value is set equal to the concatenated contents of the text node descendants, in document order.
typed-value is set equal to the string-value property, as an instance of xs:untypedAtomic.
The string-value and/or typed-value are stored or computed dynamically.
nilled, is-id, and is-idrefs are set to false.
If $N is an attribute node, its properties are changed as follows:
type-name is set to xs:untypedAtomic.
typed-value is set equal to the string-value property, as an instance of xs:untypedAtomic.
is-id and is-idrefs are set to false.
If $N has a parent, upd:removeType(parent($N)) is invoked.
The topmost ancestor of $N is
$N must be an element or attribute node
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.
If $N is an element node, its properties are changed as follows:
type-name is set to xs:untyped.
typed-value is set equal to the string-value property, as an instance of xs:untypedAtomic.
The string-value and/or typed-value are stored or computed dynamically.
nilled, is-id, and is-idrefs are set to false.
upd:setToUntyped() is invoked on the attributes and child element nodes of $N.
If $N is an attribute node, its properties are changed as follows:
type-name is set to xs:untypedAtomic.
typed-value is set equal to the string-value property, as an instance of xs:untypedAtomic.
is-id and is-idrefs are set to false.
XQuery 1.0 includes an optional static typing feature. This section
describes the static typing feature for the
XQuery Update Facility 1.0. Implementations of this specification that support
optional static typing must implement the following static typing
rules, along with the XQuery 1.0 static typing rules defined in
The concepts and notations used in this specification are the same
as those used to define the static typing feature for XQuery 1.0. For
convenience, we recall here some of the main concepts and
notations. We refer the reader to
The static typing feature for the XQuery Update Facility 1.0 is defined based on a
processing model similar to the one of XQuery 1.0. We first define the
XQuery Update Facility 1.0
Normalization rules map expressions in the XQuery Update Facility 1.0 into expressions in the XQuery Update Facility 1.0 Core. They are written as follows.
The static semantics is specified through a
The judgment
holds when, in the static environment statEnv, the
expression
The static environment is the same as the one defined in
| statEnv.revalidationMode |
|
XQuery 1.0 specifies that err:XPST0005 is raised if the Static Typing Feature is in effect and the static type assigned to an expression other than ( ) or data(( )) is empty-sequence( ). XQuery Update Facility 1.0 modifies this rule so that it applies only to
We extend the
XQuery Core defined in
The core grammar production for IfExpr can be found in
The core grammar production for OrExpr can be found in
The core grammar production for FLWORExpr can be found in
The core grammar production for QuantifiedExpr can be found in
The core grammar production for TypeswitchExpr can be found in
The core grammar production for VarName can be found in
In addition to the normalization rules defined in
Revalidation declarations are left unchanged through normalization.
The revalidation declaration modifies the revalidation mode in the static context.
In addition to the normalization and static typing rules
defined in
The following normalization rules applies to insert expressions. Note that whether the expression is written using the 'nodes' or 'node' modifier, the normalized expression always uses the 'nodes' modifier.
item-sequence-to-node-sequence(Where item-sequence-to-node-sequence is the special function used
for computing element content and is defined in
The static typing rule for insert depends on whether it is an
insert into, or an insert before or
after.
In the case of an insert into, the inference
depends on whether the target node is an element or a document
node (in which case it does not allow attribute nodes to be
inserted). This is expressed by the two following rules.
emptyemptyIn the case of an insert before or
after, the type of the target node must be either
an element, text, comment or processing-instruction node. This
is expressed by the following rule.
emptyThe following normalization rule applies to delete expressions. Note that whether the expression is written using the 'nodes' or 'node' modifier, the normalized expression always uses the 'nodes' modifier.
The static typing rule for delete is as follows.
emptyThe following normalization rules applies to replace expressions.
item-sequence-to-node-sequence(Normalization of replace value of expressions.
If the value of modifier is not specified, a
replace expression replaces one node with a new sequence of zero
or more nodes.
An attribute node can be replaced only by zero or more attribute nodes.
emptyAn element, text, comment, or processing instruction node can be replaced only by zero or more element, text, comment, or processing instruction nodes.
emptyIf the value of modifier is specified, a
replace expression replaces the content of a single node,
which must not be a document node by either a single text node
or empty.
emptyThe following normalization rule applies to rename expressions.
fn:data(The target of a rename expression must be either an
element, attribute or processing-instruction, and its new name
must be either of type xs:QName, xs:string, or
xs:untypedAtomic.
xs:QName | xs:string | xs:untypedAtomic)emptyThe following normalization rule applies to transform expressions.
| copy |
item-sequence-to-node-sequence( |
| ... |
item-sequence-to-node-sequence( |
| modify |
The transform expression is type checked using the following inference rule.
| copy |
| |
| ... |
| |
| modify |
Here are a few example queries and their corresponding static typing. In each case, if the query passes static typing, its static type is the empty type.
insert node <x/> into <a/>
Passes static typing
insert node 1 into <a/>
Passes static typing
insert node 1 into (<a/>,<a/>)
Fails static typing because the target expression does not return a single node
insert node (element a {()}, attribute b {()}) into <doc/>
Fails static typing because the attribute node is not at the head of the insertion list
insert node <x/> into //a
Fails static typing because the target expression may not
return a single node (assuming the schema allows //a
to return multiple a elements)
rename node <a/> as "b"
Passes static typing
rename node <a/> as 1
Fails static typing because the new name does not have one of the permissible types
This section defines the conformance criteria for an XQuery processor. In this section, the
following terms are used to indicate the requirement levels defined in
An XQuery processor that claims to conform to this specification
Minimal Conformance to this specification
Minimal Conformance to
Support for everything specified in this document
except those features specified in
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
Implementations are not required to define items specified to be implementation-dependent.
An implementation of XQuery that includes the Update
Facility
If an implementation claims support of the Static
Typing Feature, then it
If an implementation does not support the
An implementation that does not support the
This section defines the conformance criteria for an XQueryX processor that includes the Update Facility.
In this section, the terms
An XQueryX processor that claims to conform to this specification
The EBNF in this document and in this section is aligned with
the current XML Query 1.0 grammar (see
The following symbols are used only in the definition of
terminal symbols; they are not terminal symbols in the
grammar of
The following items in this specification are implementation-defined:
The revalidation modes that are supported by this implementation.
The default revalidation mode for this implementation.
Whether the implementation raises dynamic error
The mechanism (if any) by which an external function can return an XDM instance and/or a pending update list to the invoking query.
The semantics of fn:put(), including the kinds of nodes accepted as operands by this function.
It is a static error if an
The topmost expression in the body of a query.
The modify clause of a transform expression.
The return clause of a FLWOR expression.
The return clauses of a typeswitch expression in which every return clause contains an
The then and else clauses of a conditional statement in which both the then and else clauses contain either an
An operand of a comma expression in which each operand is either an
The content of a parenthesized expression.
The body of a function declaration in which the keyword updating is specified.
It is a static error if a
The modify clause of a transform expression.
The top-level expression in the body of a function declaration in which the keyword updating is specified.
It is a static error if a Prolog contains more than one revalidation declaration.
It is a type error if the insertion sequence of an insert expression contains an attribute node following a node that is not an attribute node.
In an insert expression where into, as first into, or as last into is specified, it is a type error if the target expression returns a non-empty result that does not consist of a single element or document node.
In an insert expression where before or after is specified, it is a type error if the target expression returns a non-empty result that does not consist of a single element, text, comment, or processing instruction node.
It is a type error if the target expression of a delete expression does not return a sequence of zero or more nodes.
In a replace expression, it is a type error if the target expression returns a non-empty result that does not consist of a single element, attribute, text, comment, or processing instruction node.
In a replace expression where value of is not specified, it is a dynamic error if the node returned by the target expression does not have a parent.
In a replace expression where value of is not specified and the target is an element, text, comment, or processing instruction node, it is a type error if the replacement sequence does not consist of zero or more element, text, comment, or processing instruction nodes.
In a replace expression where value of is not specified and the target is an attribute node, it is a type error if the replacement sequence does not consist of zero or more attribute nodes.
In a rename expression, it is a type error if the target expression returns a non-empty result that does not consist of a single element, attribute, or processing instruction node.
In a transform expression, it is a type error if a source expression in the copy clause does not return a single node.
In a transform expression, it is a dynamic error if the modify clause modifies any node that was not created by the copy clause.
It is a dynamic error if any node is the target of more than one rename expression within the same query.
It is a dynamic error if any node is the target of more than one replace expression (without value of being specified) within the same query.
It is a dynamic error if any node is the target of more than one replace value of expression within the same query.
It is a dynamic error if a function that was declared to be external but not updating returns a non-empty pending update list.
It is a dynamic error if a function that was declared to be both external and updating returns a non-empty data model instance.
An implementation may (but is not required to) raise a dynamic error if a node is deleted that had no parent before the beginning of the current snapshot.
It is a dynamic error if the
It is a type error if an insert expression specifies the insertion of an attribute node into a document node.
It is a dynamic error if an insert, replace, or rename expression affects an element node by introducing a new namespace binding that
It is a dynamic error if the effect of a set of updating expressions is to introduce
(Not currently used.)
It is a static error if a revalidation declaration in a Prolog specifies a revalidation mode that is not supported by the current implementation.
It is a dynamic error if the target expression of an insert, replace, or rename expression evaluates to an empty sequence.
It is a static error if a function declaration specifies both updating and a return type.
In an insert expression where before or after is specified, it is a dynamic error if the node returned by the target expression does not have a parent.
It is a dynamic error if an insert expression specifies the insertion of an attribute node before or after a child of a document node.
It is a dynamic error if multiple calls to fn:put in the same snapshot specify the same URI (after resolution of relative URIs).
It is a dynamic error if the first operand of fn:put is not a node of a supported kind.
It is a dynamic error if the second operand of fn:put is not a valid lexical representation of the xs:anyURI type.
During the analysis phase, it is a static error if the static type assigned to a simple expression other than ( ) or data(( )) is empty-sequence( ).
It is a dynamic error if a constructor or replace expression would result in a processing instruction node whose content includes the string "?>".
It is a dynamic error if the name assigned to a processing node by a constructor or rename expression cannot be cast to the type xs:NCName.
It is a dynamic error if a constructor or replace expression would result in a comment node whose content ends with a hyphen or contains two adjacent hyphens.
It is a dynamic error if the value of the name expression in a computed element constructor, computed attribute constructor, or rename expression cannot be converted to an expanded QName (for example, because it contains a namespace prefix not found in the statically known namespaces.)
The XML Schema specified in this appendix accomplishes its integration by importing
the XML Schema defined for XQueryX in
This section specifies the two XML Schemas that define the complex types and elements for XQueryX in support of XQuery Update Facility 1.0, including changes to the prolog and the addition of several new expressions.
This section specifies the XSLT stylesheet that defines the semantics of XQueryX
in support of XQuery Update Facility 1.0. It imports the XSLT stylesheet defined in
The following example is based on the data and queries in the use cases
in
Comparison of the results of the Update Facility XQueryX-to-XQuery Update Facility
transformation given in this document with the XQuery Update Facility solutions
in
The XQuery Update Facility Use Cases solution given for each example is provided only to assist readers of this document in understanding the Update Facility XQueryX solution. There is no intent to imply that this document specifies a "compilation" or "transformation" of XQuery Update Facility syntax into Update Facility XQueryX syntax.
In the following example, note that path expressions are expanded to show their structure. Also, note that the prefix syntax for binary operators like "and" makes the precedence explicit. In general, humans find it easier to read an XML representation that does not expand path expressions, but it is less convenient for programmatic representation and manipulation. XQueryX is designed as a language that is convenient for production and modification by software, and not as a convenient syntax for humans to read and write.
Finally, please note that white space, including new lines, have been added to some of the Update Facility XQueryX documents and XQuery Update Facility expressions for readability. That additional white space is not produced by the Update Facility XQueryX-to-XQuery Update Facility transformation.
This example is based on Q6 from
Application of the stylesheet in
In
insertAttribute, replaceValue, and rename primitives do not conflict with any
other primitives other than put.
insertInto primitives must be applied before insertIntoAsFirst/Last and
insertBefore/After primitives. Reason: if an unpositioned insert were applied after a
positioned insert, it might interfere with the position established by the earlier positioned insert. For example, suppose node A is inserted "before" node B. A later unpositioned insert into the common parent of A and B might intervene between A and B, which is not allowed by the semantics of "insert before."
insertBefore/After primitives must be applied before replaceNode primitives. Reason: After a node
has been replaced, it no longer has a parent, so "before" and "after" the replaced node
are no longer defined.
insertIntoAsFirst/Last primitives must be applied before replaceElementContent primitives. Reason:
this was a decision of the working group. The intent of this decision is that, if both of these primitives are applied to the same target node in a query, the effective result is determined by the replaceElementContent primitive.
replaceNode primitives must be applied before replaceElementContent primitives. Reason: if element
content that includes a node N has been replaced, then N no longer has a parent. In this case,
"replace node N" is undefined.
replaceNode primitives must be applied before delete primitives. Reason: After a node has been
deleted, it no longer has a parent. Replacing a node that has no parent is undefined.
put primitives must be applied after all other primitives in order that documents stored by a snapshot will reflect all update operations applied by the snapshot.
This log records the substantive changes that have been made to this document since the Candidate Recommendation of 14 March 2008. Minor editorial changes are not included in this log.
Added a rule: the expression on the right-hand-side of a variable declaration (the initializing expression) must be a simple expression. Resolves Bug 5699. Section affected:
When a rename expression operates on an attribute node, err:XUDY0023 can be raised only if the new name of the attribute is in a namespace. Renaming an attribute to a QName that has neither a namespace prefix nor a namespace URI is not an error, even if the parent element has a default namespace. Partial resolution of Bug 5629. Section affected:
When a upd:rename operation is applied to an element node, and the $newname operand is a QName that has neither a namespace prefix nor a namespace URI, part of the semantics of the operation is to remove the namespace binding for the empty prefix (if any) from the element node. Partial resolution of Bug 5629. Section affected:
Optional error err:XUDY0020 (deletion of a node that has no parent) is made part of the semantics of the delete expression (formerly it was described under the upd:delete primitive.) Partial resolution of Bug 5632. Sections affected:
Error err:XUDY0024 (updates introducing conflicting namespace bindings) is made part of the semantics of the insert and replace expressions. Also, consistency constraints on Pending Update Lists, raising err:XUDY0024 if multiple primitives on a PUL have conflicting namespace bindings, have been added to the semantics of upd:mergeUpdates and upd:applyUpdates. Checks for err:XUDY0024 are no longer part of the semantics of upd:insertAttributes, upd:replaceNode, or upd:rename. The net effect of these changes is to enable implementations to catch conflicting namespace bindings earlier and to associate them with specific expressions. Dynamic errors are no longer generated by individual update primitives on Pending Update Lists. Partial resolution of Bug 5632. Sections affected:
The following changes were made to the semantics of fn:put (resolving Bug 5646):
fn:put now generates an update primitive called upd:put, which is held on the pending update list and applied after all other update primitives. Sections:
It is an error to invoke fn:put more than once on the same URI within a snapshot. Sections:
fn:put is classified as an updating function. Section:
Moved the subsection on Function Declarations inside the section on Extensions to the Prolog. Resolves Bug 5701. Section affected:
In the Static Typing Feature for XQuery Update Facility, err:XPST0005 applies only to simple expressions (not to updating expressions.) Resolves Bug 5700. Sections affected: