This document defines an update facility that extends the XML Query language, XQuery. The XQuery Update Facility 3.0 provides expressions that can be used to make persistent changes to instances of the XQuery and XPath Data Model 3.0.
This document is governed by the
This is a
This is a Last Call Working Draft of XQuery Update Facility 3.0. Currently there are no substantive changes from the previous Working Draft. The reason for publishing this Working Draft is to provide the XQuery Update grammar fully integrated with the XQuery 3.0 grammar. Reviewers are expressly requested to submit candidate requirements for XQuery Update Facility 3.0, either by using the Bugzilla system or the public comments mailing list, as described just below.
No implementation report currently exists. However, a Test Suite for XQuery Update Facility 3.0 is under development.
This document incorporates changes made against the previous publication
of the Working Draft.
Changes to this document since the previous publication of the Working Draft
are detailed in
Please report errors in this document using W3C's
Publication as a Last Call Working Draft 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
This document defines the syntax and semantics of an extension
to
The XQuery Update Facility 3.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 3.0.
The most recent versions of the two XQueryX XML Schemas and the
XQueryX XSLT stylesheet for the XQuery Update Facility 3.0 are available at
As described in
In this document, examples and material labeled as Note
are provided for
explanatory purposes and are not normative.
Expressions in XQuery Update Facility 3.0 can return a
XQuery Update Facility 3.0 relaxes many of the constraints placed on the position of
XQuery Update Facility 3.0 introduces a new category of expression, called an
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 3.0 defines the %updating
annotation which can be used to declare an updating
is
also allowed on a function declared in the prolog for backwards compatibility with XQuery Update 1.0, and behaves
exactly as if the %updating
annotation was specified instead.
For completeness, the %simple
annotation is also defined. This can be used to explicitly label
a %updating
or %simple
annotation is also considerd a
If an %updating
or %simple
annotation is used on a %updating
or %simple
annotation in a given annotation set
Function Assertion | Matching Behaviour | Default? |
---|---|---|
%simple , or %updating("prohibited") | Matches only | true |
%updating , or %updating("allowed") | Matches both | false |
%updating("required") | Matches only | false |
A
It is a static error to use more than one
XQuery Update Facility 3.0 also defines a set of
If the outermost expression in a query returns a non-empty
In general,
The following definitions are 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
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
The table of static context components
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
.
The Prolog is extended by adding a new kind of
Functions can be declared as %updating
annotation, or the equivalent backwards-compatible bare keyword updating
.
The built-in function fn:put
is also specified as an
%updating
annotation, or if it is
declared with the %simple
annotation it is a
If a external
, its
If a external
, evaluation of the external function must not return a non-empty
An
XQuery Update Facility 3.0 allows an
If the result of an item()*
.
The means by which an external function returns an
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
The
XQuery Update Facility 3.0 adds eight new kinds of expressions. The syntax and semantics of these expressions are described in the following sections.
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
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.
An insert expression is an
The
$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.
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,
If $clist
is not empty,
If as last into
is specified, the
If $alist
is not empty,
If $clist
is not empty,
If into
is specified with neither as first
nor as last
, the
If $alist
is not empty,
If $clist
is not empty,
If before
is specified, let $parent
be the parent node of $target
. The
If $alist
is not empty,
If $clist
is not empty,
If after
is specified, let $parent
be the parent node of $target
. The
If $alist
is not empty,
If $clist
is not empty,
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.
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
The
$tlist
be the list of nodes returned by
the target expression.
If any node in $tlist
has no parent,
it is removed from $tlist
(and is thus ignored in the following step).
A new $tnode
in $tlist
, the following
upd:delete($tnode)
. The resulting pending update list
is merged with the
Delete the last author of the first book in a given bibliography.
Delete all email messages that are more than 365 days old.
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 has two forms, depending on whether 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.
A replace expression without value of
specified is an
The with
can be
expressions of any category.
The expression following the keyword with
is evaluated as though it were an enclosed
expression in an element constructor (see Rule 1e in $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.
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 with
with the following
Replace the publisher of the first book with the publisher of the second book.
If value of
is specified,
a replace expression is used to modify the value of a node while preserving
its
A replace expression with value of
specified is an
The with
can be
expressions of any category.
The expression following the keyword with
is evaluated as though it were the content
expression of a text node constructor (see Section 3.7.3.4 of
$text
be the result of this step.
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 with
with the following
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
with
with the following
.
Increase the price of the first book by ten percent.
A rename expression replaces the name
property of a
A rename expression is an
The
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
.
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 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 dynamic updating function call dynamically invokes an
A dynamic updating function call is an
The PrimaryExpr and any
A dynamic updating function call is evaluated like a dynamic function invocation,
as specified in
The result of the dynamic updating function call is the
Dynamically call the fn:put()
function.
A copy modify expression can be used to create modified copies of existing nodes in an
A copy modify expression consists of three clauses, denoted by the keywords copy
, modify
, and return
.
If all of the copy modify expression's copy
and return
clauses have operand
expressions that are
If any of the copy modify expression's copy
or return
clauses have operand
expressions that are
The operand expressions of any of the clauses of a copy modify expression can be expressions of any category.
The copy
clause contains one or more variable bindings, each of which consists of a variable name and an expression called the
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.
The parent property of the copy of $node
is set
to empty.
Other properties of the copied nodes are determined as follows:
For a copied document node, the document-uri
property is set to empty.
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 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.
The expression in the modify
clause is evaluated, resulting in a
$pul
)
and an
If the $pul
is a node that
was not newly created in Step 1, a dynamic error is raised $pul
contains a upd:put
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
. 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
The return
clause is evaluated, resulting in a
copy
or return
clause operand
expressions using return
clause, changes applied to copied nodes by the preceding
step are visible.
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.
The $v
is a variable name that is otherwise unused in
is equivalent to the following longer form
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 3.0 provides extensions to XQuery built-in function library, as specified in this section.
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 output:serialization-parameters
element with no child elements.
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.
An implementation that serializes $node
during storage $params
argument (because it does not perform serialization) but must not raise an error because serialization
parameters are specified.
The result of a call to fn:put
is an empty
.
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
XQuery Update Facility 3.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.
The category of the FLWOR expression is the same as the category of the expression in its
If any
The
The semantics of all clauses other than the
The result of the FLWOR expression is the concatenation of the
operation.
In the event of incompatible updates, the
operation may raise an error,
as described in
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.
The return expressions in the default
clause are called
typeswitch
is called
the
If all
If any
If
The
Selection of the effective case and binding of variables are performed as specified in
return
clause of the effective case (or default) is then evaluated, resulting in
an
The syntax of the switch expression is not changed.
The return expressions in the default
clause are called
switch
is called
the
If all
If any
If
The
Selection of the effective case is
performed as specified in return
clause of the effective case (or default) is then evaluated, resulting in
an
The syntax of conditional expression is not changed.
The operands of the then
and else
clauses are called
if
is called
the
If all
If any
If
The
Selection of the effective branch performed as specified in
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 the
If the
If the
The
Since the
The comma expressions is composed of one or more expressions concatenated by the comma operator, as described in
If the operand expressions of the comma expression are
If any of the operand expressions of the comma expression is an
The operand expressions of a comma expression can be expressions of any category.
The operand expressions of the comma expression are evaluated, and the
operation.
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 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 the same as the result of the expression enclosed in parentheses.
The category of an extension (pragma) expression is the same as the category of the enclosed expression, which may have any category.
The result of an extension (pragma) expression is the same as the result of the enclosed expression.
The %simple
and %updating
annotations can be specified at the start of the inline
function expression, to force the creation of a
If neither %simple
nor %updating
is specified:
The
If the
If the
If %simple
is specified:
The
The inline function expression is a
If %updating
is specified:
The
The inline function expression is a
It is a static error to use more than one %updating
or %simple
annotation in a given annotation set
Function calls can either be a
If the function call is a
If the function call is a
A function call of a
A function call of an
The
The function call is evaluated as specified in
Dynamic function invocation can either be a
A dynamic function invocation is a
The PrimaryExpr and the
The dynamic function invocation is evaluated as specified in
If the function returned by the PrimaryExpr is an
All
If all operand expressions of the node constructor are
If any operand expression of the node constructor is an
The operand expressions of a node constructor may be expressions of any category.
The upd:mergeUpdates
, and returned as the
All other XQuery expressions not listed in the sections preceeding this are extended as follows:
The expression is a
If an operand expression of the expresion is an
This section describes the update operations defined by XQuery Update Facility 3.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
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,
is invoked.
All the namespace bindings of parent($target)
are
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 add 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 add 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 add 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
is invoked.
The following properties of $target
are changed:
attributes
: Modified to add the nodes in $content
.
namespaces:
Modified to add namespace bindings for any attribute namespace prefixes in $content
that did not already have bindings.
These bindings are
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
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
is invoked on each 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 add namespace bindings for any attribute namespace prefixes in $replacement
that did not already have bindings. These bindings are
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,
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
.
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,
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.
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
.
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 add a namespace binding derived from $newName
, if this binding did not already exist.
This binding is
If $target
is an attribute node:
node-name
of $target
is set to $newName
.
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 add a namespace binding derived from $newName
, if this binding did not already exist.
This binding is
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.
An implementation that uses serialization when storing the node $params
.
Performs compatibility checking against a
None.
A dynamic error if any of the following conditions are detected:
Two or more upd:rename
primitives in $pul
have the same target node
Two or more upd:replaceNode
primitives in $pul
have the same target node
Two or more upd:replaceValue
primitives in $pul
have the same target node
Two or more upd:replaceElementContent
primitives in $pul
have the same target node
Two or more upd:put
primitives in $pul
have the same $uri
operand
Two or more primitives in $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
.
Merges two
None.
The two
Optionally,
This routine ends a
$revalidation-mode
must be "strict"
, "lax"
, or "skip"
Checks the update primitives on $pul
for compatibility using
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, after applying the updates, any
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.
If $inherit-namespaces
is true
, then
is invoked
for each namespace binding that was $element
is the element node on which the namespace binding appears, $prefix
is the namespace prefix, and $uri
is the namespace URI. Each of these nodes is then unmarked.
For each document or element node $top
that was upd:revalidate($top, $revalidation-mode)
is invoked. Each of these nodes is then unmarked.
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:anyType
N
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-idrefs
is set to false
.
is-id
is set to false
if the attribute name is not xml:id
.
None
Propagates a namespace binding to all descendants of an element.
For each element $child
among the children of $element
that does not have a namespace binding for $prefix
,
add a namespace binding ($prefix, $uri)
to $child
call upd:propagateNamespace($child, $prefix, $uri)
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
A subset of the XQuery Update 3.0 specification called
Minimal Conformance to
Support for the facilities described in the following sections of this document:
%updating
and %simple
annotations.
%updating
and %simple
annotations.
Use of other types of XQuery Update 3.0 expression
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 3.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.
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
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 copy modify expression, it is a type error if a source expression in the copy
clause does not return a single node.
In a copy modify 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 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.
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 static error if an %updating
or %simple
annotation is used on a
It is a static error to use more than one %updating
or %simple
annotation in a
given annotation set.
It is a static error to use more than one
It is a dynamic error if the
upd:put
It is a dynamic error if the function returned by the PrimaryExpr of a dynamic
function invocation is an
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.
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 3.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 3.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 XQuery Update 3.0 Working Draft of 13 December 2011. Minor editorial changes are not included in this log.
Removed require-feature()
/prohibit-feature()
due to implementation experience.
Implemented Dynamic Updating Function Invocation, according to the 2013-09-23 proposal by Ghislain Fourny, accepted in meeting #551 on 2013-10-01.
Implemented serialization parameters for fn:put(), according to the 2013-01-30 proposal by Josh Spiegel, accepted in meeting #551 on 2013-10-01.
Update XQueryX schema and stylesheet to reflect new syntax in XQuery Update 3.0.
Added the %simple annotation, bug 14667, accepted in meeting #494
Changed transform expressions to say that they don't copy the document-uri, bug 13027, accepted in meeting #527
Clarified from which module the revalidation mode is used, bug 13300, accepted in meeting #527
Raise an error for an fn:put update primitive returned to the modify clause of a copy modify expression, bug 13970, accepted in meeting #527
Implemented the "XQuery with Multiple Results" conformance level, bug 9064, accepted in meeting #555
Implemented the ability for results to contain both non-empty XDM instances and non-empty PUL, accepted in meeting #579, clarified in the minutes of meeting #580
Added the %updating("allowed"), %updating("prohibited"), and %updating("required") function assertions, bug 14662, accepted in meeting #579
Implemented the simple transform expression, bug 23643, accepted in meeting #563
Renamed the transform expression to copy modify, and the simple transform expression to transform with, bug 23643, accepted in meeting #585
Changed all [err:TBD] to real error codes.
Raising upd:mergeUpdate related errors is required at the end of a try clause, accepted in meeting #591
The %updating annotation is not required to create an updating function as an inline function, accepted in meeting #591