This section discusses each of the basic kinds of expression.
Each kind of expression has a name such as PathExpr,
which is introduced on the left side of the grammar production that
defines the expression. Since XQuery 1.1 is a composable language,
each kind of expression is defined in terms of other expressions
whose operators have a higher precedence. In this way, the
precedence of operators is represented explicitly in the
grammar.
The order in which expressions are discussed in this document
does not reflect the order of operator precedence. In general, this
document introduces the simplest kinds of expressions first,
followed by more complex expressions. For the complete grammar, see
Appendix [A XQuery 1.1 Grammar].
3.1 Primary Expressions
[Definition: Primary
expressions are the basic primitives of the language. They
include literals, variable references, context item expressions,
constructors, and function calls. A
primary expression may also be created by enclosing any expression
in parentheses, which is sometimes helpful in controlling the
precedence of operators.] Constructors are
described in 3.7
Constructors.
3.1.1 Literals
[Definition: A literal is a direct syntactic
representation of an atomic value.] XQuery 1.1 supports two kinds
of literals: numeric literals and string literals.
The value of a numeric literal containing no
"." and no e or E character
is an atomic value of type xs:integer. The value of a
numeric literal containing "." but no e
or E character is an atomic value of type
xs:decimal. The value of a numeric literal containing
an e or E character is an atomic value of
type xs:double. The value of the numeric literal is
determined by casting it to the appropriate type according to the
rules for casting from xs:untypedAtomic to a numeric
type as specified in Section
17.1.1 Casting from xs:string and
xs:untypedAtomicFO.
The value of a string literal is an atomic value whose
type is xs:string and whose value is the string
denoted by the characters between the delimiting apostrophes or
quotation marks. If the literal is delimited by apostrophes, two
adjacent apostrophes within the literal are interpreted as a single
apostrophe. Similarly, if the literal is delimited by quotation
marks, two adjacent quotation marks within the literal are
interpreted as one quotation mark.
A string literal may contain a predefined
entity reference. [Definition: A predefined
entity reference is a short sequence of characters, beginning
with an ampersand, that represents a single character that might
otherwise have syntactic significance.] Each predefined entity
reference is replaced by the character it represents when the
string literal is processed. The predefined entity references
recognized by XQuery are as follows:
| Entity Reference |
Character Represented |
< |
< |
> |
> |
& |
& |
" |
" |
' |
' |
A string literal may also contain a character
reference. [Definition: A character reference
is an XML-style reference to a [Unicode]
character, identified by its decimal or hexadecimal code point.]
For example, the Euro symbol (€) can be represented by the
character reference €. Character references
are normatively defined in Section 4.1 of the XML specification (it
is implementation-defined whether the
rules in [XML 1.0] or [XML
1.1] apply.) A static error [err:XQST0090] is raised if a character reference
does not identify a valid character in the version of XML that is
in use.
Here are some examples of literal expressions:
-
"12.5" denotes the string containing the characters
'1', '2', '.', and '5'.
-
12 denotes the xs:integer value
twelve.
-
12.5 denotes the xs:decimal value
twelve and one half.
-
125E2 denotes the xs:double value
twelve thousand, five hundred.
-
"He said, ""I don't like it.""" denotes a string
containing two quotation marks and one apostrophe.
-
"Ben & Jerry's" denotes the
xs:string value "Ben & Jerry's".
-
"€99.50" denotes the
xs:string value "€99.50".
The xs:boolean values true and
false can be represented by calls to the built-in
functions fn:true() and fn:false(),
respectively.
Values of other atomic types can be constructed by calling the
constructor function for the given
type. The constructor functions for XML Schema built-in types are
defined in [XQuery 1.0 and XPath
2.0 Functions and Operators]. In general, the name of a
constructor function for a given type is the same as the name of
the type (including its namespace). For example:
-
xs:integer("12") returns the integer value
twelve.
-
xs:date("2001-08-25") returns an item whose type is
xs:date and whose value represents the date 25th
August 2001.
-
xs:dayTimeDuration("PT5H") returns an item whose
type is xs:dayTimeDuration and whose value represents
a duration of five hours.
Constructor functions can also be used to create special values
that have no literal representation, as in the following
examples:
-
xs:float("NaN") returns the special floating-point
value, "Not a Number."
-
xs:double("INF") returns the special
double-precision value, "positive infinity."
It is also possible to construct values of various types by
using a cast expression. For example:
3.1.2 Variable
References
[Definition: A variable
reference is a QName preceded by a $-sign.] Two variable
references are equivalent if their local names are the same and
their namespace prefixes are bound to the same namespace URI in the
statically known namespaces. An
unprefixed variable reference is in no namespace.
Every variable reference must match a name in the in-scope
variables, which include variables from the following
sources:
-
A variable may be declared in a Prolog, in the current module or an imported module. See 4 Modules and Prologs for a
discussion of modules and Prologs.
-
The in-scope variables may be augmented by
implementation-defined
variables.
-
A variable may be bound by an XQuery 1.1 expression.
The kinds of expressions that can bind
variables are FLWOR expressions (3.8 FLWOR Expressions),
quantified expressions (3.11 Quantified
Expressions), and typeswitch expressions
(3.13.2 Typeswitch). Function
calls also bind values to the formal parameters of functions before
executing the function body.
Every variable binding has a static scope. The scope defines
where references to the variable can validly occur. It is a
static error
[err:XPST0008] to
reference a variable that is not in scope. If a variable is bound
in the static
context for an expression, that variable is in scope for the
entire expression.
A reference to a variable that was declared
external, but was not bound to a value by the external
environment, raises a dynamic error [err:XPDY0002].
If a variable reference matches two or more variable bindings
that are in scope, then the reference is taken as referring to the
inner binding, that is, the one whose scope is smaller. At
evaluation time, the value of a variable reference is the value of
the expression to which the relevant variable is bound. The scope
of a variable binding is defined separately for each kind of
expression that can bind variables.
3.1.3 Parenthesized Expressions
| [112] |
ParenthesizedExpr |
::= |
"(" Expr? ")" |
Parentheses may be used to enforce a particular evaluation order
in expressions that contain multiple operators. For example, the
expression (2 + 4) * 5 evaluates to thirty, since the
parenthesized expression (2 + 4) is evaluated first
and its result is multiplied by five. Without parentheses, the
expression 2 + 4 * 5 evaluates to twenty-two, because
the multiplication operator has higher precedence than the addition
operator.
Empty parentheses are used to denote an empty sequence, as
described in 3.3.1 Constructing
Sequences.
3.1.4 Context Item Expression
| [113] |
ContextItemExpr |
::= |
"." |
A context item expression evaluates to the context item, which may
be either a node (as in the expression
fn:doc("bib.xml")/books/book[fn:count(./author)>1])
or an atomic value (as in the expression (1 to 100)[. mod 5
eq 0]).
If the context
item is undefined, a context item expression raises a dynamic
error [err:XPDY0002].
3.1.5
Function Calls
[Definition: The built-in functions
supported by XQuery 1.1 are defined in [XQuery 1.0 and XPath 2.0 Functions and
Operators].] Additional functions may be
declared in a Prolog,
imported from a library module, or provided by the
external environment as part of the static context.
A function call consists of a QName followed by a
parenthesized list of zero or more expressions, called
arguments. If the QName in the function call has no
namespace prefix, it is considered to be in the default function
namespace.
If the expanded QName and number of arguments in
a function call do not match the name and arity of a function
signature in the static context, a static error is raised [err:XPST0017].
A function call is evaluated as follows:
-
Argument expressions are evaluated, producing argument values.
The order of argument evaluation is implementation-dependent and a
function need not evaluate an argument if the function can evaluate
its body without evaluating that argument.
-
Each argument value is converted by applying the function
conversion rules listed below.
-
If the function is a built-in function, it is evaluated using
the converted argument values. The result is either an instance of
the function's declared return type or a dynamic error. Errors
raised by built-in functions are defined in [XQuery 1.0 and XPath 2.0 Functions and
Operators].
-
If the function is a user-declared function that has a body, the
converted argument values are bound to the formal parameters of the
function, and the function body is evaluated. The value returned by
the function body is then converted to the declared return type of
the function by applying the function conversion rules.
When a converted argument value is bound to a function
parameter, the argument value retains its most specific dynamic type, even
though this type may be derived from the type of the formal
parameter. For example, a function with a parameter $p
of type xs:decimal can be invoked with an argument of
type xs:integer, which is derived from
xs:decimal. During the processing of this function
invocation, the dynamic type of $p inside the
body of the function is considered to be xs:integer.
Similarly, the value returned by a function retains its most
specific type, which may be derived from the declared return type
of the function. For example, a function that has a declared return
type of xs:decimal may in fact return a value of
dynamic type xs:integer.
During evaluation of a function body, the static context and
dynamic
context for expression evaluation are defined by the module in which the function is
declared, which is not necessarily the same as the module in which the function is
called. For example, the variables in scope while evaluating a
function body are defined by in-scope variables of the module that
declares the function rather than the module in which the function
is called. During evaluation of a function body, the focus (context item, context position,
and context size) is undefined, except where it is defined by some
expression inside the function body.
-
If the function is a user-declared external function, its
function implementation is
invoked with the converted argument values. The result is either a
value of the declared type or an implementation-defined error
(see 2.2.5 Consistency
Constraints).
The function conversion rules are used to convert an
argument value or a return value to its
expected type; that is, to the declared type of the function
parameter or return. The expected type
is expressed as a sequence type. The function conversion
rules are applied to a given value as follows:
-
If the expected type is a sequence of an atomic type (possibly
with an occurrence indicator *, +, or
?), the following conversions are applied:
-
Atomization is
applied to the given value, resulting in a sequence of atomic
values.
-
Each item in the atomic sequence that is of type
xs:untypedAtomic is cast to the expected atomic type.
For built-in functions where the expected
type is specified as numeric, arguments of type
xs:untypedAtomic are cast to
xs:double.
-
For each numeric item
in the atomic sequence that can be promoted to the expected atomic type using
numeric promotion as described in B.1 Type
Promotion, the promotion is done.
-
For each item of type xs:anyURI in the atomic
sequence that can be promoted to the expected atomic type using
URI promotion as described in B.1 Type
Promotion, the promotion is done.
-
If, after the above conversions, the resulting value does not
match the expected type according to the rules for SequenceType Matching, a type error is raised
[err:XPTY0004].
If the function call takes place in a
module other than the
module in which the
function is defined, this rule must be satisfied in both the module
where the function is called and the module where the function is
defined (the test is repeated because the two modules may have
different in-scope schema definitions.) Note that the
rules for SequenceType Matching permit a
value of a derived type to be substituted for a value of its base
type.
Since the arguments of a function call are separated by commas,
any argument expression that contains a top-level comma operator must
be enclosed in parentheses. Here are some illustrative examples of
function calls:
-
my:three-argument-function(1, 2, 3) denotes a
function call with three arguments.
-
my:two-argument-function((1, 2), 3) denotes a
function call with two arguments, the first of which is a sequence
of two values.
-
my:two-argument-function(1, ()) denotes a function
call with two arguments, the second of which is an empty
sequence.
-
my:one-argument-function((1, 2, 3)) denotes a
function call with one argument that is a sequence of three
values.
-
my:one-argument-function(( )) denotes a function
call with one argument that is an empty sequence.
-
my:zero-argument-function( ) denotes a function
call with zero arguments.
3.2
Path Expressions
[Definition: A path expression can be
used to locate nodes within trees. A path expression consists of a
series of one or more steps,
separated by "/" or "//", and optionally
beginning with "/" or "//".] An initial
"/" or "//" is an abbreviation for one or
more initial steps that are implicitly added to the beginning of
the path expression, as described below.
A path expression consisting of a single step is evaluated as
described in 3.2.1 Steps.
A "/" at the beginning of a path expression is an
abbreviation for the initial step (fn:root(self::node())
treat as document-node())/ (however, if the "/"
is the entire path expression, the trailing "/" is
omitted from the expansion.) The effect of this initial step is to
begin the path at the root node of the tree that contains the
context node. If the context item is not a node, a type error is raised
[err:XPTY0020]. At
evaluation time, if the root node above the context node is not a
document node, a dynamic error is raised [err:XPDY0050].
A "//" at the beginning of a path expression is an
abbreviation for the initial steps (fn:root(self::node())
treat as document-node())/descendant-or-self::node()/
(however, "//" by itself is not a valid path
expression [err:XPST0003].) The effect of these initial
steps is to establish an initial node sequence that contains the
root of the tree in which the context node is found, plus all nodes
descended from this root. This node sequence is used as the input
to subsequent steps in the path expression. If the context item is
not a node, a type
error is raised [err:XPTY0020]. At evaluation time, if the root
node above the context node is not a document node, a dynamic error is
raised [err:XPDY0050].
Note:
The descendants of a node do not include attribute nodes .
Each non-initial occurrence of "//" in a path
expression is expanded as described in 3.2.4
Abbreviated Syntax, leaving a sequence of steps separated
by "/". This sequence of steps is then evaluated from
left to right. Each operation E1/E2 is evaluated as
follows: Expression E1 is evaluated, and if the result
is not a (possibly empty) sequence of nodes, a type error is raised
[err:XPTY0019].
Each node resulting from the evaluation of E1 then
serves in turn to provide an inner focus for an evaluation
of E2, as described in 2.1.2 Dynamic Context. The sequences
resulting from all the evaluations of E2 are combined
as follows:
-
If every evaluation of E2 returns a (possibly
empty) sequence of nodes, these sequences are combined, and
duplicate nodes are eliminated based on node identity. If ordering mode is ordered, the
resulting node sequence is returned in document order; otherwise it is
returned in implementation-dependent
order.
-
If every evaluation of E2 returns a (possibly
empty) sequence of atomic values, these sequences are concatenated
and returned. If ordering mode is ordered,
the returned sequence preserves the orderings within and among the
subsequences generated by the evaluations of E2;
otherwise the order of the returned sequence is implementation-dependent.
-
If the multiple evaluations of E2 return at least
one node and at least one atomic value, a type error is raised [err:XPTY0018].
Note:
Since each step in a path provides context nodes for the
following step, in effect, only the last step in a path is allowed
to return a sequence of atomic values.
As an example of a path expression,
child::div1/child::para selects the para
element children of the div1 element children of the
context node, or, in other words, the para element
grandchildren of the context node that have div1
parents.
Note:
The "/" character can be used
either as a complete path expression or as the beginning of a
longer path expression such as "/*". Also,
"*" is both the multiply operator and a wildcard in
path expressions. This can cause parsing difficulties when
"/" appears on the left hand side of "*".
This is resolved using the leading-lone-slash constraint.
For example, "/*" and "/ *" are valid
path expressions containing wildcards, but "/*5" and
"/ * 5" raise syntax errors. Parentheses must be used
when "/" is used on the left hand side of an operator,
as in "(/) * 5". Similarly, "4 + / * 5"
raises a syntax error, but "4 + (/) * 5" is a valid
expression. The expression "4 + /" is also valid,
because / does not occur on the left hand side of the
operator.
3.2.1 Steps
[Definition: A
step is a part of a path expression that generates a sequence
of items and then filters the sequence by zero or more predicates. The value of the
step consists of those items that satisfy the predicates, working
from left to right. A step may be either an axis step or a filter
expression.] Filter expressions are described in 3.3.2 Filter Expressions.
[Definition: An axis step returns a sequence
of nodes that are reachable from the context node via a specified
axis. Such a step has two parts: an axis, which defines the
"direction of movement" for the step, and a node test, which selects nodes based on
their kind, name, and/or type annotation.] If the context item is
a node, an axis step returns a sequence of zero or more nodes;
otherwise, a type
error is raised [err:XPTY0020]. If ordering mode is
ordered, the resulting node sequence is returned in
document
order; otherwise it is returned in implementation-dependent
order. An axis step may be either a forward step or a
reverse step, followed by zero or more predicates.
In the abbreviated syntax for a step, the axis can be
omitted and other shorthand notations can be used as described in
3.2.4 Abbreviated Syntax.
The unabbreviated syntax for an axis step consists of the axis
name and node test separated by a double colon. The result of the
step consists of the nodes reachable from the context node via the
specified axis that have the node kind, name, and/or type annotation
specified by the node test. For example, the step
child::para selects the para element
children of the context node: child is the name of the
axis, and para is the name of the element nodes to be
selected on this axis. The available axes are described in 3.2.1.1 Axes. The available node tests are
described in 3.2.1.2 Node Tests.
Examples of steps are provided in 3.2.3
Unabbreviated Syntax and 3.2.4
Abbreviated Syntax.
3.2.1.1 Axes
| [96] |
ForwardAxis |
::= |
("child" "::")
| ("descendant" "::")
| ("attribute" "::")
| ("self" "::")
| ("descendant-or-self" "::")
| ("following-sibling" "::")
| ("following" "::") |
| [99] |
ReverseAxis |
::= |
("parent" "::")
| ("ancestor" "::")
| ("preceding-sibling" "::")
| ("preceding" "::")
| ("ancestor-or-self" "::") |
XQuery supports the following axes (subject to
limitations as described in 5.2.4 Full Axis Feature):
-
The child axis contains the children of the context
node, which are the nodes returned by the dm:children
accessor in [XQuery/XPath Data Model
(XDM)].
Note:
Only document nodes and element nodes have children. If the
context node is any other kind of node, or if the context node is
an empty document or element node, then the child axis is an empty
sequence. The children of a document node or element node may be
element, processing instruction, comment, or text nodes. Attribute
and document nodes can never appear as children.
-
the descendant axis is defined as the transitive
closure of the child axis; it contains the descendants of the
context node (the children, the children of the children, and so
on)
-
the parent axis contains the sequence returned by
the dm:parent accessor in [XQuery/XPath Data Model (XDM)], which returns the
parent of the context node, or an empty sequence if the context
node has no parent
Note:
An attribute node may have an element node as its parent, even
though the attribute node is not a child of the element node.
-
the ancestor axis is defined as the transitive
closure of the parent axis; it contains the ancestors of the
context node (the parent, the parent of the parent, and so on)
Note:
The ancestor axis includes the root node of the tree in which
the context node is found, unless the context node is the root
node.
-
the following-sibling axis contains the context
node's following siblings, those children of the context node's
parent that occur after the context node in document order; if
the context node is an attribute node, the
following-sibling axis is empty
-
the preceding-sibling axis contains the context
node's preceding siblings, those children of the context node's
parent that occur before the context node in document order; if
the context node is an attribute node, the
preceding-sibling axis is empty
-
the following axis contains all nodes that are
descendants of the root of the tree in which the context node is
found, are not descendants of the context node, and occur after the
context node in document order
-
the preceding axis contains all nodes that are
descendants of the root of the tree in which the context node is
found, are not ancestors of the context node, and occur before the
context node in document order
-
the attribute axis contains the attributes of the
context node, which are the nodes returned by the
dm:attributes accessor in [XQuery/XPath Data Model (XDM)]; the axis will be
empty unless the context node is an element
-
the self axis contains just the context node
itself
-
the descendant-or-self axis contains the context
node and the descendants of the context node
-
the ancestor-or-self axis contains the context node
and the ancestors of the context node; thus, the ancestor-or-self
axis will always include the root node
Axes can be categorized as forward axes and reverse
axes. An axis that only ever contains the context node or nodes
that are after the context node in document order is a forward axis. An axis
that only ever contains the context node or nodes that are before
the context node in document order is a reverse axis.
The parent, ancestor,
ancestor-or-self, preceding, and
preceding-sibling axes are reverse axes; all other
axes are forward axes. The ancestor,
descendant, following,
preceding and self axes partition a
document (ignoring attribute nodes): they do not overlap and
together they contain all the nodes in the document.
[Definition: Every axis has a
principal node kind. If an axis can contain elements, then
the principal node kind is element; otherwise, it is the kind of
nodes that the axis can contain.] Thus:
-
For the attribute axis, the principal node kind is
attribute.
-
For all other axes, the principal node kind is element.
3.2.1.2 Node
Tests
[Definition: A node test is a condition that
must be true for each node selected by a step.] The condition may be based on the kind of the
node (element, attribute, text, document, comment, or processing
instruction), the name of the node, or (in the case of element,
attribute, and document nodes), the type annotation of the node.
[Definition: A node test that consists only of a
QName or a Wildcard is called a name test.] A name test is
true if and only if the kind of the node is the principal node
kind for the step axis and the expanded QName of the node is equal (as
defined by the eq operator) to the expanded QName
specified by the name test. For example, child::para
selects the para element children of the context node;
if the context node has no para children, it selects
an empty set of nodes. attribute::abc:href selects the
attribute of the context node with the QName abc:href;
if the context node has no such attribute, it selects an empty set
of nodes.
A QName in a name test is resolved into an expanded QName using
the statically known namespaces in the
expression context. It is a static error [err:XPST0081] if the QName has a prefix that
does not correspond to any statically known namespace. An
unprefixed QName, when used as a name test on an axis whose
principal node kind is element, has
the namespace URI of the default element/type namespace in
the expression context; otherwise, it has no namespace URI.
A name test is not satisfied by an element node whose name does
not match the expanded QName of the name test, even if
it is in a substitution group whose head is the
named element.
A node test * is true for any node of the principal node
kind of the step axis. For example, child::* will
select all element children of the context node, and
attribute::* will select all attributes of the context
node.
A node test can have the form NCName:*. In this
case, the prefix is expanded in the same way as with a QName, using
the statically known namespaces in the
static
context. If the prefix is not found in the statically known
namespaces, a static error is raised [err:XPST0081]. The node
test is true for any node of the principal node kind of the step
axis whose expanded QName has the namespace URI to
which the prefix is bound, regardless of the local part of the
name.
A node test can also have the form *:NCName. In
this case, the node test is true for any node of the principal node
kind of the step axis whose local name matches the given
NCName, regardless of its namespace or lack of a namespace.
[Definition: An alternative form of a node test
called a kind test can select nodes based on their kind,
name, and type annotation.] The syntax and
semantics of a kind test are described in 2.5.3 SequenceType Syntax and
2.5.4 SequenceType
Matching. When a kind test is used in a node test, only those nodes on
the designated axis that match the kind test are selected. Shown
below are several examples of kind tests that might be used in path
expressions:
-
node() matches any node.
-
text() matches any text node.
-
comment() matches any comment node.
-
namespace-node() matches any namespace node.
-
element() matches any element node.
-
schema-element(person) matches any element node
whose name is person (or is in the substitution
group headed by person), and whose type annotation
is the same as (or is derived from) the declared type of the
person element in the in-scope
element declarations.
-
element(person) matches any element node whose name
is person, regardless of its type annotation.
-
element(person, surgeon) matches any non-nilled
element node whose name is person, and whose type
annotation is surgeon or is derived from
surgeon.
-
element(*, surgeon) matches any non-nilled element
node whose type annotation is surgeon (or is derived
from surgeon), regardless of its name.
-
attribute() matches any attribute node.
-
attribute(price) matches any attribute whose name
is price, regardless of its type annotation.
-
attribute(*, xs:decimal) matches any attribute
whose type annotation is xs:decimal (or is derived
from xs:decimal), regardless of its name.
-
document-node() matches any document node.
-
document-node(element(book)) matches any document
node whose content consists of a single element node that satisfies
the kind test
element(book), interleaved with zero or more comments
and processing instructions.
3.2.2
Predicates
| [106] |
Predicate |
::= |
"[" Expr "]" |
[Definition: A predicate consists of an
expression, called a predicate expression, enclosed in
square brackets. A predicate serves to filter a sequence, retaining
some items and discarding others.] In the case of multiple adjacent
predicates, the predicates are applied from left to right, and the
result of applying each predicate serves as the input sequence for
the following predicate.
For each item in the input sequence, the predicate expression is
evaluated using an inner focus, defined as follows: The
context item is the item currently being tested against the
predicate. The context size is the number of items in the input
sequence. The context position is the position of the context item
within the input sequence. For the purpose of evaluating the
context position within a predicate, the input sequence is
considered to be sorted as follows: into document order if the
predicate is in a forward-axis step, into reverse document order if
the predicate is in a reverse-axis step, or in its original order
if the predicate is not in a step.
For each item in the input sequence, the result of the predicate
expression is coerced to an xs:boolean value, called
the predicate truth value, as described below. Those items
for which the predicate truth value is true are
retained, and those for which the predicate truth value is
false are discarded.
The predicate truth value is derived by applying the following
rules, in order:
-
If the value of the predicate expression is a singleton atomic value of a
numeric type or derived
from a numeric type, the
predicate truth value is true if the value of the
predicate expression is equal (by the eq operator) to
the context position, and is false otherwise.
[Definition: A predicate whose predicate
expression returns a numeric type is called a numeric
predicate.]
-
Otherwise, the predicate truth value is the effective boolean
value of the predicate expression.
Here are some examples of axis steps that contain predicates:
-
This example selects the second chapter element
that is a child of the context node:
-
This example selects all the descendants of the context node
that are elements named "toy" and whose
color attribute has the value "red":
descendant::toy[attribute::color = "red"]
-
This example selects all the employee children of
the context node that have both a secretary child
element and an assistant child element:
child::employee[secretary][assistant]
Note:
When using predicates with a sequence of nodes selected
using a reverse axis, it is important to remember that the
the context positions for such a sequence are assigned in reverse
document order. For example, preceding::foo[1]
returns the first qualifying foo element in reverse
document order, because the predicate is part of an axis step using a reverse
axis. By contrast, (preceding::foo)[1] returns the
first qualifying foo element in document order,
because the parentheses cause (preceding::foo) to be
parsed as a primary expression in which context
positions are assigned in document order. Similarly,
ancestor::*[1] returns the nearest ancestor element,
because the ancestor axis is a reverse axis, whereas
(ancestor::*)[1] returns the root element (first
ancestor in document order).
The fact that a reverse-axis step assigns context positions in
reverse document order for the purpose of evaluating predicates
does not alter the fact that the final result of the step
(when in ordered mode) is always in
document order.
3.2.3 Unabbreviated
Syntax
This section provides a number of examples of path expressions
in which the axis is explicitly specified in each step. The syntax used in these examples is
called the unabbreviated syntax. In many common cases, it is
possible to write path expressions more concisely using an
abbreviated syntax, as explained in 3.2.4 Abbreviated Syntax.
-
child::para selects the para element
children of the context node
-
child::* selects all element children of the
context node
-
child::text() selects all text node children of the
context node
-
child::node() selects all the children of the
context node. Note that no attribute nodes are returned, because
attributes are not children.
-
attribute::name selects the name
attribute of the context node
-
attribute::* selects all the attributes of the
context node
-
parent::node() selects the parent of the context
node. If the context node is an attribute node, this expression
returns the element node (if any) to which the attribute node is
attached.
-
descendant::para selects the para
element descendants of the context node
-
ancestor::div selects all div
ancestors of the context node
-
ancestor-or-self::div selects the div
ancestors of the context node and, if the context node is a
div element, the context node as well
-
descendant-or-self::para selects the
para element descendants of the context node and, if
the context node is a para element, the context node
as well
-
self::para selects the context node if it is a
para element, and otherwise returns an empty
sequence
-
child::chapter/descendant::para selects the
para element descendants of the chapter
element children of the context node
-
child::*/child::para selects all para
grandchildren of the context node
-
/ selects the root of the tree that contains the
context node, but raises a dynamic error if this root is not a
document node
-
/descendant::para selects all the para
elements in the same document as the context node
-
/descendant::list/child::member selects all the
member elements that have a list parent
and that are in the same document as the context node
-
child::para[fn:position() = 1] selects the first
para child of the context node
-
child::para[fn:position() = fn:last()] selects the
last para child of the context node
-
child::para[fn:position() = fn:last()-1] selects
the last but one para child of the context node
-
child::para[fn:position() > 1] selects all the
para children of the context node other than the first
para child of the context node
-
following-sibling::chapter[fn:position() =
1]selects the next chapter sibling of the
context node
-
preceding-sibling::chapter[fn:position() =
1]selects the previous chapter sibling of the
context node
-
/descendant::figure[fn:position() = 42] selects the
forty-second figure element in the document containing
the context node
-
/child::book/child::chapter[fn:position() =
5]/child::section[fn:position() = 2] selects the second
section of the fifth chapter of the
book whose parent is the document node that contains
the context node
-
child::para[attribute::type eq "warning"]selects
all para children of the context node that have a
type attribute with value warning
-
child::para[attribute::type eq 'warning'][fn:position() =
5]selects the fifth para child of the context
node that has a type attribute with value
warning
-
child::para[fn:position() = 5][attribute::type eq
"warning"]selects the fifth para child of the
context node if that child has a type attribute with
value warning
-
child::chapter[child::title =
'Introduction']selects the chapter children of
the context node that have one or more title children
whose typed value
is equal to the string Introduction
-
child::chapter[child::title] selects the
chapter children of the context node that have one or
more title children
-
child::*[self::chapter or self::appendix] selects
the chapter and appendix children of the
context node
-
child::*[self::chapter or self::appendix][fn:position() =
fn:last()] selects the last chapter or
appendix child of the context node
3.2.4 Abbreviated Syntax
| [97] |
AbbrevForwardStep |
::= |
"@"? NodeTest |
| [100] |
AbbrevReverseStep |
::= |
".." |
The abbreviated syntax permits the following abbreviations:
-
The attribute axis attribute:: can be abbreviated
by @. For example, a path expression
para[@type="warning"] is short for
child::para[attribute::type="warning"] and so selects
para children with a type attribute with
value equal to warning.
-
If the axis name is omitted from an axis step, the default axis is
child unless the axis step contains an AttributeTest or SchemaAttributeTest; in that
case, the default axis is attribute. For example, the
path expression section/para is an abbreviation for
child::section/child::para, and the path expression
section/@id is an abbreviation for
child::section/attribute::id. Similarly,
section/attribute(id) is an abbreviation for
child::section/attribute::attribute(id). Note that the
latter expression contains both an axis specification and a
node test.
-
Each non-initial occurrence of // is effectively
replaced by /descendant-or-self::node()/ during
processing of a path expression. For example,
div1//para is short for
child::div1/descendant-or-self::node()/child::para and
so will select all para descendants of
div1 children.
Note:
The path expression //para[1] does not
mean the same as the path expression
/descendant::para[1]. The latter selects the first
descendant para element; the former selects all
descendant para elements that are the first
para children of their respective parents.
-
A step consisting of .. is short for
parent::node(). For example, ../title is
short for parent::node()/child::title and so will
select the title children of the parent of the context
node.
Here are some examples of path expressions that use the
abbreviated syntax:
-
para selects the para element children
of the context node
-
* selects all element children of the context
node
-
text() selects all text node children of the
context node
-
@name selects the name attribute of
the context node
-
@* selects all the attributes of the context
node
-
para[1] selects the first para child
of the context node
-
para[fn:last()] selects the last para
child of the context node
-
*/para selects all para grandchildren
of the context node
-
/book/chapter[5]/section[2] selects the second
section of the fifth chapter of the
book whose parent is the document node that contains
the context node
-
chapter//para selects the para element
descendants of the chapter element children of the
context node
-
//para selects all the para
descendants of the root document node and thus selects all
para elements in the same document as the context
node
-
//@version selects all the version
attribute nodes that are in the same document as the context
node
-
//list/member selects all the member
elements in the same document as the context node that have a
list parent
-
.//para selects the para element
descendants of the context node
-
.. selects the parent of the context node
-
../@lang selects the lang attribute of
the parent of the context node
-
para[@type="warning"] selects all para
children of the context node that have a type
attribute with value warning
-
para[@type="warning"][5] selects the fifth
para child of the context node that has a
type attribute with value warning
-
para[5][@type="warning"] selects the fifth
para child of the context node if that child has a
type attribute with value warning
-
chapter[title="Introduction"] selects the
chapter children of the context node that have one or
more title children whose typed value is equal to the string
Introduction
-
chapter[title] selects the chapter
children of the context node that have one or more
title children
-
employee[@secretary and @assistant] selects all the
employee children of the context node that have both a
secretary attribute and an assistant
attribute
-
book/(chapter|appendix)/section selects every
section element that has a parent that is either a
chapter or an appendix element, that in
turn is a child of a book element that is a child of
the context node.
-
If E is any expression that returns a sequence of
nodes, then the expression E/. returns the same nodes
in document
order, with duplicates eliminated based on node identity.
3.3 Sequence Expressions
XQuery 1.1 supports operators to construct, filter, and combine
sequences of items. Sequences are never nested—for
example, combining the values 1, (2, 3),
and ( ) into a single sequence results in the sequence
(1, 2, 3).
3.3.1
Constructing Sequences
[Definition: One way to construct a sequence is
by using the comma operator, which evaluates each of its
operands and concatenates the resulting sequences, in order, into a
single result sequence.] Empty parentheses can be used to denote an
empty sequence.
A sequence may contain duplicate atomic values or nodes, but a
sequence is never an item in another sequence. When a new sequence
is created by concatenating two or more input sequences, the new
sequence contains all the items of the input sequences and its
length is the sum of the lengths of the input sequences.
Note:
In places where the grammar calls for ExprSingle, such as the arguments of a
function call, any expression that contains a top-level comma
operator must be enclosed in parentheses.
Here are some examples of expressions that construct
sequences:
-
The result of this expression is a sequence of five
integers:
-
This expression combines four sequences of length one, two,
zero, and two, respectively, into a single sequence of length five.
The result of this expression is the sequence 10, 1, 2, 3,
4.
-
The result of this expression is a sequence containing all
salary children of the context node followed by all
bonus children.
-
Assuming that $price is bound to the value
10.50, the result of this expression is the sequence
10.50, 10.50.
A range expression can be used to construct a sequence of
consecutive integers. Each of the operands of the to
operator is converted as though it was an argument of a function
with the expected parameter type xs:integer?. If
either operand is an empty sequence, or if the integer derived from
the first operand is greater than the integer derived from the
second operand, the result of the range expression is an empty
sequence. If the two operands convert to the same integer, the
result of the range expression is that integer. Otherwise, the
result is a sequence containing the two integer operands and every
integer between the two operands, in increasing order.
-
This example uses a range expression as one operand in
constructing a sequence. It evaluates to the sequence 10, 1,
2, 3, 4.
-
This example constructs a sequence of length one containing the
single integer 10.
-
The result of this example is a sequence of length zero.
-
This example uses the fn:reverse function to
construct a sequence of six integers in decreasing order. It
evaluates to the sequence 15, 14, 13, 12, 11, 10.
3.3.2 Filter
Expressions
[Definition: A filter expression
consists simply of a primary expression followed by zero or
more predicates. The
result of the filter expression consists of the items returned by
the primary expression, filtered by applying each predicate in
turn, working from left to right.] If no predicates are specified,
the result is simply the result of the primary expression. The
ordering of the items returned by a filter expression is the same
as their order in the result of the primary expression. Context
positions are assigned to items based on their ordinal position in
the result sequence. The first context position is 1.
Here are some examples of filter expressions:
-
Given a sequence of products in a variable, return only those
products whose price is greater than 100.
-
List all the integers from 1 to 100 that are divisible by 5.
(See 3.3.1 Constructing
Sequences for an explanation of the to
operator.)
-
The result of the following expression is the integer 25:
-
The following example returns the fifth through ninth items in
the sequence bound to variable $orders.
$orders[fn:position() = (5 to 9)]
-
The following example illustrates the use of a filter expression
as a step in a path expression.
It returns the last chapter or appendix within the book bound to
variable $book:
$book/(chapter | appendix)[fn:last()]
-
The following example also illustrates the use of a filter
expression as a step in a
path
expression. It returns the element node within the specified
document whose ID value is tiger:
fn:doc("zoo.xml")/fn:id('tiger')
3.3.3 Combining
Node Sequences
XQuery 1.1 provides the following operators for combining
sequences of nodes:
-
The union and | operators are
equivalent. They take two node sequences as operands and return a
sequence containing all the nodes that occur in either of the
operands.
-
The intersect operator takes two node sequences as
operands and returns a sequence containing all the nodes that occur
in both operands.
-
The except operator takes two node sequences as
operands and returns a sequence containing all the nodes that occur
in the first operand but not in the second operand.
All these operators eliminate duplicate nodes from their result
sequences based on node identity. If ordering mode is
ordered, the resulting sequence is returned in
document
order; otherwise it is returned in implementation-dependent
order.
If an operand of union, intersect, or
except contains an item that is not a node, a
type error is
raised [err:XPTY0004].
Here are some examples of expressions that combine sequences.
Assume the existence of three element nodes that we will refer to
by symbolic names A, B, and C. Assume that the variables
$seq1, $seq2 and $seq3 are
bound to the following sequences of these nodes:
-
$seq1 is bound to (A, B)
-
$seq2 is bound to (A, B)
-
$seq3 is bound to (B, C)
Then:
-
$seq1 union $seq2 evaluates to the sequence (A,
B).
-
$seq2 union $seq3 evaluates to the sequence (A, B,
C).
-
$seq1 intersect $seq2 evaluates to the sequence (A,
B).
-
$seq2 intersect $seq3 evaluates to the sequence
containing B only.
-
$seq1 except $seq2 evaluates to the empty
sequence.
-
$seq2 except $seq3 evaluates to the sequence
containing A only.
In addition to the sequence operators described here, [XQuery 1.0 and XPath 2.0 Functions and
Operators] includes functions for indexed access to items or
sub-sequences of a sequence, for indexed insertion or removal of
items in a sequence, and for removing duplicate items from a
sequence.
3.4 Arithmetic
Expressions
XQuery 1.1 provides arithmetic operators for addition,
subtraction, multiplication, division, and modulus, in their usual
binary and unary forms.
A subtraction operator must be preceded by whitespace if it
could otherwise be interpreted as part of the previous token. For
example, a-b will be interpreted as a name, but
a - b and a -b will be interpreted as
arithmetic expressions. (See A.2.4
Whitespace Rules for further details on whitespace
handling.)
The first step in evaluating an arithmetic expression is to
evaluate its operands. The order in which the operands are
evaluated is implementation-dependent.
Each operand is evaluated by
applying the following steps, in order:
-
Atomization is
applied to the operand. The result of this operation is called the
atomized operand.
-
If the atomized operand is an empty sequence, the result of the
arithmetic expression is an empty sequence, and the implementation
need not evaluate the other operand or apply the operator. However,
an implementation may choose to evaluate the other operand in order
to determine whether it raises an error.
-
If the atomized operand is a sequence of length greater than
one, a type error
is raised [err:XPTY0004].
-
If the atomized operand is of type
xs:untypedAtomic, it is cast to
xs:double. If the cast fails, a dynamic error is
raised. [err:FORG0001]
After evaluation of the operands, if the types of the operands
are a valid combination for the given arithmetic operator, the
operator is applied to the operands, resulting in an atomic value
or a dynamic
error (for example, an error might result from dividing by
zero.) The combinations of atomic types that are accepted by the
various arithmetic operators, and their respective result types,
are listed in B.2 Operator Mapping
together with the operator functions that define the
semantics of the operator for each type combination, including the
dynamic errors that can be raised by the operator. The definitions
of the operator functions are found in [XQuery 1.0 and XPath 2.0 Functions and
Operators].
If the types of the operands, after evaluation, are not a valid
combination for the given operator, according to the rules in
B.2 Operator Mapping, a type error is raised
[err:XPTY0004].
XQuery 1.1 supports two division operators named
div and idiv. Each of these operators
accepts two operands of any numeric type. As described in [XQuery 1.0 and XPath 2.0 Functions and
Operators], $arg1 idiv $arg2 is equivalent to
($arg1 div $arg2) cast as xs:integer? except for error
cases.
Here are some examples of arithmetic expressions:
-
The first expression below returns the xs:decimal
value -1.5, and the second expression returns the
xs:integer value -1:
-
Subtraction of two date values results in a value of type
xs:dayTimeDuration:
$emp/hiredate - $emp/birthdate
-
This example illustrates the difference between a subtraction
operator and a hyphen:
$unit-price - $unit-discount
-
Unary operators have higher precedence than binary operators,
subject of course to the use of parentheses. Therefore, the
following two examples have different meanings:
-$bellcost + $whistlecost
-($bellcost + $whistlecost)
Note:
Multiple consecutive unary
arithmetic operators are permitted by XQuery 1.1 for compatibility
with [XPath 1.0].
3.5 Comparison
Expressions
Comparison expressions allow two values to be compared. XQuery
1.1 provides three kinds of comparison expressions, called value
comparisons, general comparisons, and node comparisons.
| [71] |
ComparisonExpr |
::= |
RangeExpr ( (ValueComp
| GeneralComp
| NodeComp) RangeExpr )? |
| [84] |
ValueComp |
::= |
"eq" | "ne" | "lt" | "le" | "gt" | "ge" |
| [83] |
GeneralComp |
::= |
"=" | "!=" | "<" | "<=" | ">" |
">=" |
| [85] |
NodeComp |
::= |
"is" | "<<" | ">>" |
3.5.1 Value Comparisons
The value comparison operators are eq,
ne, lt, le, gt,
and ge. Value comparisons are used for comparing
single values.
The first step in evaluating a value comparison is to evaluate
its operands. The order in which the operands are evaluated is
implementation-dependent. Each
operand is evaluated by applying the following steps, in order:
-
Atomization is
applied to the operand. The result of this operation is called the
atomized operand.
-
If the atomized operand is an empty sequence, the result of the
value comparison is an empty sequence, and the implementation need
not evaluate the other operand or apply the operator. However, an
implementation may choose to evaluate the other operand in order to
determine whether it raises an error.
-
If the atomized operand is a sequence of length greater than
one, a type error
is raised [err:XPTY0004].
-
If the atomized operand is of type
xs:untypedAtomic, it is cast to
xs:string.
Note:
The purpose of this rule is to make value comparisons
transitive. Users should be aware that the general comparison
operators have a different rule for casting of
xs:untypedAtomic operands. Users should also be aware
that transitivity of value comparisons may be compromised by loss
of precision during type conversion (for example, two
xs:integer values that differ slightly may both be
considered equal to the same xs:float value because
xs:float has less precision than
xs:integer).
Next, if possible, the two operands are converted to their least
common type by a combination of type promotion and subtype
substitution. For example, if the operands are of type
hatsize (derived from xs:integer) and
shoesize (derived from xs:float), their
least common type is xs:float.
Finally, if the types of the operands are a valid combination
for the given operator, the operator is applied to the operands.
The combinations of atomic types that are accepted by the various
value comparison operators, and their respective result types, are
listed in B.2 Operator Mapping
together with the operator functions that define the
semantics of the operator for each type combination. The
definitions of the operator functions are found in [XQuery 1.0 and XPath 2.0 Functions and
Operators].
Informally, if both atomized operands consist of exactly one
atomic value, then the result of the comparison is
true if the value of the first operand is (equal, not
equal, less than, less than or equal, greater than, greater than or
equal) to the value of the second operand; otherwise the result of
the comparison is false.
If the types of the operands, after evaluation, are not a valid
combination for the given operator, according to the rules in
B.2 Operator Mapping, a type error is raised
[err:XPTY0004].
Here are some examples of value comparisons:
-
The following comparison atomizes the node(s) that are returned
by the expression $book/author. The comparison is true
only if the result of atomization is the value "Kennedy" as an
instance of xs:string or
xs:untypedAtomic. If the result of atomization is an
empty sequence, the result of the comparison is an empty sequence.
If the result of atomization is a sequence containing more than one
value, a type error
is raised [err:XPTY0004].
$book1/author eq "Kennedy"
-
The following path expression contains a predicate that
selects products whose weight is greater than 100. For any product
that does not have a weight subelement, the value of
the predicate is the empty sequence, and the product is not
selected. This example assumes that weight is a
validated element with a numeric type.
-
The following comparisons are true because, in each case, the
two constructed nodes have the same value after atomization, even
though they have different identities and/or names:
-
The following comparison is true if my:hatsize and
my:shoesize are both user-defined types that are
derived by restriction from a primitive numeric type:
my:hatsize(5) eq my:shoesize(5)
-
The following comparison is true. The eq operator
compares two QNames by performing codepoint-comparisons of their
namespace URIs and their local names, ignoring their namespace
prefixes.
fn:QName("http://example.com/ns1", "this:color")
eq fn:QName("http://example.com/ns1", "that:color")
3.5.2 General Comparisons
The general comparison operators are =,
!=, <, <=,
>, and >=. General comparisons are
existentially quantified comparisons that may be applied to operand
sequences of any length. The result of a general comparison that
does not raise an error is always true or
false.
A general comparison is evaluated by
applying the following rules, in order:
-
Atomization is
applied to each operand. After atomization, each operand is a
sequence of atomic values.
-
The result of the comparison is true if and only if
there is a pair of atomic values, one in the first operand sequence
and the other in the second operand sequence, that have the
required magnitude relationship. Otherwise the result of the
comparison is false. The magnitude relationship
between two atomic values is determined by applying the following
rules. If a cast operation called for by these rules
is not successful, a dynamic error is raised. [err:FORG0001]
Note:
The purpose of these rules is to preserve compatibility with
XPath 1.0, in which (for example) x < 17 is a
numeric comparison if x is an untyped value. Users
should be aware that the value comparison operators have different
rules for casting of xs:untypedAtomic operands.
-
If one of the atomic values is an instance of
xs:untypedAtomic and the other is an instance of a
numeric type, then the
xs:untypedAtomic value is cast to the type
xs:double.
-
If one of the atomic values is an instance of
xs:untypedAtomic and the other is an instance of
xs:untypedAtomic or xs:string, then the
xs:untypedAtomic value (or values) is (are) cast to
the type xs:string.
-
If one of the atomic values is an instance of
xs:untypedAtomic and the other is not an instance of
xs:string, xs:untypedAtomic, or any
numeric type, then the
xs:untypedAtomic value is cast to the dynamic type of the
other value.
-
After performing the conversions described above, the atomic
values are compared using one of the value comparison operators
eq, ne, lt, le,
gt, or ge, depending on whether the
general comparison operator was =, !=,
<, <=, >, or
>=. The values have the required magnitude
relationship if and only if the result of this value comparison
is true.
When evaluating a general comparison in which either operand is
a sequence of items, an implementation may return true
as soon as it finds an item in the first operand and an item in the
second operand that have the required magnitude
relationship. Similarly, a general comparison may raise a
dynamic error
as soon as it encounters an error in evaluating either operand, or
in comparing a pair of items from the two operands. As a result of
these rules, the result of a general comparison is not
deterministic in the presence of errors.
Here are some examples of general comparisons:
-
The following comparison is true if the typed value of any author
subelement of $book1 is "Kennedy" as an instance of
xs:string or xs:untypedAtomic:
$book1/author = "Kennedy"
-
The following example contains three general comparisons. The
value of the first two comparisons is true, and the
value of the third comparison is false. This example
illustrates the fact that general comparisons are not
transitive.
(1, 2) = (2, 3)
(2, 3) = (3, 4)
(1, 2) = (3, 4)
-
The following example contains two general comparisons, both of
which are true. This example illustrates the fact that
the = and != operators are not inverses
of each other.
(1, 2) = (2, 3)
(1, 2) != (2, 3)
-
Suppose that $a, $b, and
$c are bound to element nodes with type annotation
xs:untypedAtomic, with string values "1",
"2", and "2.0" respectively. Then
($a, $b) = ($c, 3.0) returns false,
because $b and $c are compared as
strings. However, ($a, $b) = ($c, 2.0) returns
true, because $b and 2.0 are
compared as numbers.
3.5.3 Node Comparisons
Node comparisons are used to compare two nodes, by their
identity or by their document order. The result of a node
comparison is defined by the following rules:
-
The operands of a node comparison are evaluated in implementation-dependent
order.
-
If either operand is an empty sequence, the result of the
comparison is an empty sequence, and the implementation need not
evaluate the other operand or apply the operator. However, an
implementation may choose to evaluate the other operand in order to
determine whether it raises an error.
-
Each operand must be either a single node or an empty sequence;
otherwise a type
error is raised [err:XPTY0004].
-
A comparison with the is operator is
true if the two operand nodes have the same identity,
and are thus the same node; otherwise it is false. See
[XQuery/XPath Data Model (XDM)] for a
definition of node identity.
-
A comparison with the << operator returns
true if the left operand node precedes the right
operand node in document order; otherwise it returns
false.
-
A comparison with the >> operator returns
true if the left operand node follows the right
operand node in document order; otherwise it returns
false.
Here are some examples of node comparisons:
-
The following comparison is true only if the left and right
sides each evaluate to exactly the same single node:
/books/book[isbn="1558604820"] is /books/book[call="QA76.9 C3845"]
-
The following comparison is false because each constructed node
has its own identity:
-
The following comparison is true only if the node identified by
the left side occurs before the node identified by the right side
in document order:
/transactions/purchase[parcel="28-451"]
<< /transactions/sale[parcel="33-870"]
3.7
Constructors
XQuery provides constructors that can create XML structures
within a query. Constructors are provided for element, attribute,
document, text, comment, and processing instruction nodes. Two
kinds of constructors are provided: direct constructors,
which use an XML-like notation, and computed constructors,
which use a notation based on enclosed expressions.
This section contains a conceptual description of the semantics
of various kinds of constructor expressions. An XQuery
implementation is free to use any implementation technique that
produces the same result as the processing steps described in this
section.
3.7.1 Direct Element Constructors
An element constructor creates an element node. [Definition: A direct element
constructor is a form of element constructor in which the name
of the constructed element is a constant.] Direct element
constructors are based on standard XML notation. For example, the
following expression is a direct element constructor that creates a
book element containing an attribute and some nested
elements:
<book isbn="isbn-0060229357">
<title>Harold and the Purple Crayon</title>
<author>
<first>Crockett</first>
<last>Johnson</last>
</author>
</book>
If the element name in a direct element constructor has a
namespace prefix, the namespace prefix is resolved to a namespace
URI using the statically known namespaces. If the
element name has no namespace prefix, it is implicitly qualified by
the default element/type namespace. Note that
both the statically known namespaces and the default element/type
namespace may be affected by namespace declaration attributes
found inside the element constructor. The namespace prefix of the
element name is retained after expansion of the QName, as described
in [XQuery/XPath Data Model (XDM)]. The
resulting expanded QName becomes the
node-name property of the constructed element
node.
In a direct element constructor, the name used in the end tag
must exactly match the name used in the corresponding start tag,
including its prefix or absence of a prefix.
In a direct element constructor, curly braces { } delimit
enclosed expressions, distinguishing them from literal text.
Enclosed expressions are evaluated and replaced by their value, as
illustrated by the following example:
<example>
<p> Here is a query. </p>
<eg> $b/title </eg>
<p> Here is the result of the query. </p>
<eg>{ $b/title }</eg>
</example>
The above query might generate the following result (whitespace
has been added for readability to this result and other result
examples in this document):
<example>
<p> Here is a query. </p>
<eg> $b/title </eg>
<p> Here is the result of the query. </p>
<eg><title>Harold and the Purple Crayon</title></eg>
</example>
Since XQuery uses curly braces to denote enclosed expressions,
some convention is needed to denote a curly brace used as an
ordinary character. For this purpose, a pair of identical curly
brace characters within the content of an element or attribute are
interpreted by XQuery as a single curly brace character (that is,
the pair "{{" represents the character
"{" and the pair "}}" represents the
character "}".) Alternatively, the character
references { and }
can be used to denote curly brace characters. A single left curly
brace ("{") is interpreted as the beginning delimiter
for an enclosed expression. A single right curly brace
("}") without a matching left curly brace is treated
as a static
error [err:XPST0003].
The result of an element constructor is a new element node, with
its own node identity. All the attribute and descendant nodes of
the new element node are also new nodes with their own identities,
even if they are copies of existing nodes.
3.7.1.1
Attributes
The start tag of a direct element constructor may contain one or
more attributes. As in XML, each attribute is specified by a name
and a value. In a direct element constructor, the name of each
attribute is specified by a constant QName, and the value of the
attribute is specified by a string of characters enclosed in single
or double quotes. As in the main content of the element
constructor, an attribute value may contain expressions enclosed in
curly braces, which are evaluated and replaced by their value
during processing of the element constructor.
Each attribute in a direct element constructor creates a new
attribute node, with its own node identity, whose parent is the
constructed element node. However, note that namespace declaration attributes (see
3.7.1.2 Namespace Declaration
Attributes) do not create attribute nodes.
If an attribute name has a namespace prefix, the prefix is
resolved to a namespace URI using the statically known namespaces. If the
attribute name has no namespace prefix, the attribute is in no
namespace. Note that the statically known namespaces used in
resolving an attribute name may be affected by namespace declaration attributes that
are found inside the same element constructor. The namespace prefix
of the attribute name is retained after expansion of the QName, as
described in [XQuery/XPath Data Model
(XDM)]. The resulting expanded QName becomes the
node-name property of the constructed attribute
node.
If the attributes in a direct element constructor do not have
distinct expanded QNames as their respective
node-name properties, a static error is raised [err:XQST0040].
Conceptually, an attribute (other than a namespace declaration
attribute) in a direct element constructor is processed by the
following steps:
-
Each consecutive sequence of literal characters in the attribute
content is treated as a string containing those characters.
Attribute value normalization is then applied to normalize
whitespace and expand character references and predefined entity references.
An XQuery processor that supports XML 1.0 uses the rules for
attribute value normalization in Section 3.3.3 of [XML 1.0]; an XQuery processor that supports XML 1.1
uses the rules for attribute value normalization in Section 3.3.3
of [XML 1.1]. In either case, the
normalization rules are applied as though the type of the attribute
were CDATA (leading and trailing whitespace characters are not
stripped.) The choice between XML 1.0 and XML 1.1 rules is
implementation-defined.
-
Each enclosed expression is converted to a string as
follows:
-
Atomization is
applied to the value of the enclosed expression, converting it to a
sequence of atomic values.
-
If the result of atomization is an empty sequence, the result is
the zero-length string. Otherwise, each atomic value in the
atomized sequence is cast into a string.
-
The individual strings resulting from the previous step are
merged into a single string by concatenating them with a single
space character between each pair.
-
Adjacent strings resulting from the above steps are concatenated
with no intervening blanks. The resulting string becomes the
string-value property of the attribute node. The
attribute node is given a type annotation (type-name
property) of xs:untypedAtomic (this type annotation
may change if the parent element is validated). The
typed-value property of the attribute node is the same
as its string-value, as an instance of
xs:untypedAtomic.
-
The parent property of the attribute node is set to
the element node constructed by the direct element constructor that
contains this attribute.
-
If the attribute name is xml:id, then
xml:id processing is performed as defined in [XML ID]. This ensures that the attribute has the type
xs:ID and that its value is properly normalized. If an
error is encountered during xml:id processing, an
implementation MAY raise a dynamic error
[err:XQDY0091].
-
If the attribute name is xml:id, the
is-id property of the resulting attribute node is set
to true; otherwise the is-id property is
set to false. The is-idrefs property of
the attribute node is unconditionally set to
false.
-
Example:
The string value of the size attribute is
"7".
-
Example:
The string value of the size attribute is
"7".
-
Example:
The string value of the size attribute is the
zero-length string.
-
Example:
<chapter ref="[{1, 5 to 7, 9}]"/>
The string value of the ref attribute is "[1
5 6 7 9]".
-
Example:
<shoe size="As big as {$hat/@size}"/>
The string value of the size attribute is the
string "As big as ", concatenated with the string
value of the node denoted by the expression
$hat/@size.
3.7.1.2
Namespace Declaration Attributes
The names of a constructed element and its attributes may be
QNames that include
namespace prefixes. Namespace prefixes can be bound to
namespaces in the Prolog or
by namespace declaration attributes. It is a static error to use a
namespace prefix that has not been bound to a namespace [err:XPST0081].
[Definition: A
namespace declaration attribute is used inside a direct
element constructor. Its purpose is to bind a namespace prefix or
to set the default element/type namespace for the
constructed element node, including its attributes.] Syntactically,
a namespace declaration attribute has the form of an attribute with
namespace prefix xmlns, or with name
xmlns and no namespace prefix. The value of a
namespace declaration attribute must be a URILiteral; otherwise a static error is raised
[err:XQST0022]. All
the namespace declaration attributes of a given element must have
distinct names [err:XQST0071]. Each namespace declaration
attribute is processed as follows:
-
The local part of the attribute name is interpreted as a
namespace prefix and the value of the attribute is interpreted as a
namespace URI. This prefix and URI are added to the statically known namespaces of the
constructor expression (overriding any existing binding of the
given prefix), and are also added as a namespace binding to the
in-scope namespaces of the
constructed element. If the namespace URI is a zero-length string
and the implementation supports [XML Names
1.1], any existing namespace binding for the given prefix is
removed from the in-scope namespaces of the
constructed element and from the statically known namespaces of the
constructor expression. If the namespace URI is a zero-length
string and the implementation does not support [XML Names 1.1], a static error is raised
[err:XQST0085]. It
is implementation-defined whether an
implementation supports [XML Names] or
[XML Names 1.1].
-
If the name of the namespace declaration attribute is
xmlns with no prefix, the value of the attribute is
interpreted as a namespace URI. This URI specifies the default
element/type namespace of the constructor expression
(overriding any existing default), and is added (with no prefix) to
the in-scope namespaces of the
constructed element (overriding any existing namespace binding with
no prefix). If the namespace URI is a zero-length string, the
default element/type namespace of the
constructor expression is set to "none," and any no-prefix
namespace binding is removed from the in-scope
namespaces of the constructed element.
-
It is a static
error [err:XQST0070] if a namespace declaration
attribute binds a namespace URI to the predefined prefix
xmlns. It is also a static error [err:XQST0070] if a namespace declaration
attribute binds a namespace URI other than
http://www.w3.org/XML/1998/namespace to the prefix
xml, or binds a prefix other than xml to
the namespace URI
http://www.w3.org/XML/1998/namespace.
A namespace declaration attribute does not cause an attribute
node to be created.
The following examples illustrate namespace declaration
attributes:
-
In this element constructor, a namespace declaration attribute
is used to set the default element/type namespace to
http://example.org/animals:
<cat xmlns = "http://example.org/animals">
<breed>Persian</breed>
</cat>
-
In this element constructor, namespace declaration attributes
are used to bind the namespace prefixes metric and
english:
<box xmlns:metric = "http://example.org/metric/units"
xmlns:english = "http://example.org/english/units">
<height> <metric:meters>3</metric:meters> </height>
<width> <english:feet>6</english:feet> </width>
<depth> <english:inches>18</english:inches> </depth>
</box>
3.7.1.3 Content
The part of a direct element constructor between the start tag
and the end tag is called the content of the element
constructor. This content may consist of text characters (parsed as
ElementContentChar),
nested direct constructors, CdataSections, character and
predefined entity references,
and expressions enclosed in curly braces. In general, the value of
an enclosed expression may be any sequence of nodes and/or atomic
values. Enclosed expressions can be used in the content of an
element constructor to compute both the content and the attributes
of the constructed node.
Conceptually, the content of an element constructor is processed
as follows:
-
The content is evaluated to produce a sequence of nodes called
the content sequence, as follows:
-
If the boundary-space policy in the
static
context is strip, boundary whitespace is
identified and deleted (see 3.7.1.4
Boundary Whitespace for a definition of boundary
whitespace.)
-
Predefined entity references
and character references are expanded
into their referenced strings, as described in 3.1.1 Literals. Characters inside a
CDataSection, including
special characters such as < and
&, are treated as literal characters rather than
as markup characters (except for the sequence ]]>,
which terminates the CDataSection).
-
Each consecutive sequence of literal characters evaluates to a
single text node containing the characters.
-
Each nested direct constructor is evaluated according to the
rules in 3.7.1 Direct Element
Constructors or 3.7.2
Other Direct Constructors, resulting in a new element,
comment, or processing instruction node. Then:
-
The parent property of the resulting node is then
set to the newly constructed element node.
-
The base-uri property of the resulting node, and of
each of its descendants, is set to be the same as that of its new
parent, unless it (the child node) has an xml:base
attribute, in which case its base-uri property is set
to the value of that attribute, resolved (if it is relative)
against the base-uri property of its new parent
node.
-
Enclosed expressions are evaluated as follows:
-
For each adjacent sequence of one or more atomic values returned
by an enclosed expression, a new text node is constructed,
containing the result of casting each atomic value to a string,
with a single space character inserted between adjacent values.
Note:
The insertion of blank characters between adjacent values
applies even if one or both of the values is a zero-length
string.
-
For each node returned by an enclosed expression, a new copy is
made of the given node and all nodes that have the given node as an
ancestor, collectively referred to as copied nodes. The
properties of the copied nodes are as follows:
-
Each copied node receives a new node identity.
-
The parent, children, and
attributes properties of the copied nodes are set so
as to preserve their inter-node relationships. For the topmost node
(the node directly returned by the enclosed expression), the
parent property is set to the node constructed by this
constructor.
-
If construction mode in the static context is
strip:
-
If the copied node is an element node, its
type-name property is set to xs:untyped.
Its nilled, is-id, and
is-idrefs properties are set to
false.
-
If the copied node is an attribute node, its
type-name property is set to
xs:untypedAtomic. Its is-idrefs property
is set to false. Its 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.
Note:
Implementations that store only the typed value of a node are required at this
point to convert the typed value to a string form.
On the other hand, if construction mode in the static context is
preserve, the type-name,
nilled, string-value,
typed-value, is-id, and
is-idrefs properties of the copied nodes are
preserved.
-
The in-scope-namespaces property of a copied
element node is determined by the following rules. In applying
these rules, the default namespace or absence of a default
namespace is treated like any other namespace binding:
-
If copy-namespaces mode 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.
-
If copy-namespaces mode specifies
inherit, the copied node inherits all the in-scope
namespaces of the constructed node, augmented and overridden by the
in-scope namespaces of the original element that were preserved by
the preceding rule. If copy-namespaces mode specifies
no-inherit, the copied node does not inherit any
in-scope namespaces from the constructed node.
-
An enclosed expression in the content of an element constructor
may cause one or more existing nodes to be copied. Type error
[err:XQTY0086] is
raised in the following cases:
-
An element node is copied, and the typed value of the element node or one of its
attributes is namespace-sensitive, and construction
mode is preserve, and copy-namespaces mode is
no-preserve.
-
An attribute node is copied but its parent element node is not
copied, and the typed
value of the copied attribute node is namespace-sensitive, and construction
mode is preserve.
[Definition: A value is
namespace-sensitive if it includes an item whose dynamic type is
xs:QName or xs:NOTATION or is derived by
restriction from xs:QName or
xs:NOTATION.]
Note:
The rationale for error [err:XQTY0086] is as follows: It is not possible
to preserve the type of a QName without also preserving the
namespace binding that defines the prefix of the QName.
-
When an element or processing instruction node is copied, its
base-uri property is set to be the same as that of its
new parent, with the following exception: if a copied element node
has an xml:base attribute, its base-uri
property is set to the value of that attribute, resolved (if it is
relative) against the base-uri property of the new
parent node.
-
All other properties of the copied nodes are preserved.
-
If the content sequence contains a document node, the document
node is replaced in the content sequence by its children.
-
Adjacent text nodes in the content sequence are merged into a
single text node by concatenating their contents, with no
intervening blanks. After concatenation, any text node whose
content is a zero-length string is deleted from the content
sequence.
-
If the content sequence contains an attribute node or a
namespace node following a node that is not an attribute node or a
namespace node, a type
error is raised [err:XQTY0024].
-
The properties of the newly constructed element node are
determined as follows:
-
node-name is the expanded QName resulting from resolving
the element name in the start tag, including its original namespace
prefix (if any), as described in 3.7.1 Direct Element
Constructors.
-
parent is set to empty.
-
attributes consist of all the attributes specified
in the start tag as described in 3.7.1.1 Attributes, together with all
the attribute nodes in the content sequence, in implementation-dependent order.
Note that the parent property of each of these
attribute nodes has been set to the newly constructed element node.
If two or more attributes have the same node-name, a
dynamic error
is raised [err:XQDY0025]. If an attribute named
xml:space has a value other than preserve
or default, a dynamic error MAY be raised [err:XQDY0092].
-
children consist of all the element, text, comment,
and processing instruction nodes in the content sequence. Note that
the parent property of each of these nodes has been
set to the newly constructed element node.
-
base-uri is set to the following value:
-
If the constructed node has an attribute named
xml:base, then the value of this attribute, resolved
if it is relative against the base URI in the static context. The value of the
xml:base attribute is normalized as described in
[XML Base].
-
Otherwise, the value of the base URI in the static context.
-
in-scope-namespaces consist of all the namespace
bindings resulting from namespace declaration attributes as
described in 3.7.1.2 Namespace
Declaration Attributes, and possibly additional namespace
bindings as described in 3.7.4 In-scope Namespaces of a
Constructed Element.
-
The nilled property is false.
-
The string-value property is equal to the
concatenated contents of the text-node descendants in document
order. If there are no text-node descendants, the
string-value property is a zero-length string.
-
The typed-value property is equal to the
string-value property, as an instance of
xs:untypedAtomic.
-
If construction mode in the static context is
strip, the type-name property is
xs:untyped. On the other hand, if construction mode is
preserve, the type-name property is
xs:anyType.
-
The is-id and is-idrefs properties are
set to false.
-
Example:
The constructed element node has one child, a text node
containing the value "1".
-
Example:
The constructed element node has one child, a text node
containing the value "1 2 3".
-
Example:
The constructed element node has one child, a text node
containing the value "123".
-
Example:
The constructed element node has one child, a text node
containing the value "1 2 3".
-
Example:
<fact>I saw 8 cats.</fact>
The constructed element node has one child, a text node
containing the value "I saw 8 cats.".
-
Example:
<fact>I saw {5 + 3} cats.</fact>
The constructed element node has one child, a text node
containing the value "I saw 8 cats.".
-
Example:
<fact>I saw <howmany>{5 + 3}</howmany> cats.</fact>
The constructed element node has three children: a text node
containing "I saw ", a child element node named
howmany, and a text node containing "
cats.". The child element node in turn has a single
text node child containing the value "8".
3.7.1.4 Boundary
Whitespace
In a direct element constructor, whitespace characters may
appear in the content of the constructed element. In some cases,
enclosed expressions and/or nested elements may be separated only
by whitespace characters. For example, in the expression below, the
end-tag </title> and the start-tag
<author> are separated by a newline character
and four space characters:
<book isbn="isbn-0060229357">
<title>Harold and the Purple Crayon</title>
<author>
<first>Crockett</first>
<last>Johnson</last>
</author>
</book>
[Definition: Boundary
whitespace is a sequence of consecutive whitespace characters
within the content of a direct element constructor, that is
delimited at each end either by the start or end of the content, or
by a DirectConstructor,
or by an EnclosedExpr. For
this purpose, characters generated by character
references such as   or by CdataSections are not considered to
be whitespace characters.]
The boundary-space policy in the
static
context controls whether boundary whitespace is preserved by
element constructors. If boundary-space policy is
strip, boundary whitespace is not considered
significant and is discarded. On the other hand, if boundary-space
policy is preserve, boundary whitespace is considered
significant and is preserved.
-
Example:
<cat>
<breed>{$b}</breed>
<color>{$c}</color>
</cat>
The constructed cat element node has two child
element nodes named breed and color.
Whitespace surrounding the child elements will be stripped away by
the element constructor if boundary-space policy is
strip.
-
Example:
If boundary-space policy is strip, this example is
equivalent to <a>abc</a>. However, if
boundary-space policy is preserve, this example is
equivalent to
<a> abc </a>.
-
Example:
Since the whitespace surrounding the z is not
boundary whitespace, it is always preserved. This example is
equivalent to <a> z abc</a>.
-
Example:
This example is equivalent to
<a> abc</a>, regardless of the
boundary-space policy, because the space generated by the character
reference is not treated as a whitespace character.
-
Example:
This example constructs an element containing two space
characters, regardless of the boundary-space policy, because
whitespace inside an enclosed expression is never considered to be
boundary whitespace.
Note:
Element constructors treat attributes named
xml:space as ordinary attributes. An
xml:space attribute does not affect the handling of
whitespace by an element constructor.
3.7.2 Other Direct Constructors
XQuery allows an expression to generate a processing instruction
node or a comment node. This can be accomplished by using a
direct processing instruction constructor or a direct
comment constructor. In each case, the syntax of the
constructor expression is based on the syntax of a similar
construct in XML.
A direct processing instruction constructor creates a processing
instruction node whose target property is PITarget and whose content
property is DirPIContents.
The base-uri property of the node is empty. The
parent property of the node is empty.
The PITarget of a processing
instruction must not consist of the characters "XML" in any
combination of upper and lower case. The DirPIContents of a processing
instruction must not contain the string "?>".
The following example illustrates a direct processing
instruction constructor:
<?format role="output" ?>
A direct comment constructor creates a comment node whose
content property is DirCommentContents. Its
parent property is empty.
The DirCommentContents of a
comment must not contain two consecutive hyphens or end with a
hyphen. These rules are syntactically enforced by the grammar shown
above.
The following example illustrates a direct comment
constructor:
<!-- Tags are ignored in the following section -->
Note:
A direct comment constructor is different from a comment, since a direct comment
constructor actually constructs a comment node, whereas a comment is simply used in documenting a
query and is not evaluated.
3.7.3 Computed Constructors
An alternative way to create nodes is by using a computed
constructor. A computed constructor begins with a keyword that
identifies the type of node to be created: element,
attribute, document, text,
processing-instruction, comment, or
namespace.
For those kinds of nodes that have names (element, attribute,
and processing instruction nodes), the keyword that specifies the
node kind is followed by the name of the node to be created. This
name may be specified either as a QName or as an expression
enclosed in braces. [Definition: When
an expression is used to specify the name of a constructed node,
that expression is called the name expression of the
constructor.]
[Definition: The final part of a
computed constructor is an expression enclosed in braces, called
the content expression of the constructor, that generates
the content of the node.]
The following example illustrates the use of computed element
and attribute constructors in a simple case where the names of the
constructed nodes are constants. This example generates exactly the
same result as the first example in 3.7.1 Direct Element
Constructors:
element book {
attribute isbn {"isbn-0060229357" },
element title { "Harold and the Purple Crayon"},
element author {
element first { "Crockett" },
element last {"Johnson" }
}
}
3.7.3.1 Computed Element
Constructors
[Definition: A computed
element constructor creates an element node, allowing both the
name and the content of the node to be computed.]
If the keyword element is followed by a QName, it
is expanded using the statically known namespaces, and the
resulting expanded QName is used as the
node-name property of the constructed element node. If
expansion of the QName is not successful, a static error is raised [err:XPST0081].
If the keyword element is followed by a name expression,
the name expression is processed as follows:
-
Atomization is
applied to the value of the name expression. If the result of
atomization is not a single atomic value of type
xs:QName, xs:string, or
xs:untypedAtomic, a type error is raised [err:XPTY0004].
-
If the atomized value of the name expression is of type
xs:QName, that expanded QName is used as the
node-name property of the constructed element,
retaining the prefix part of the QName.
-
If the atomized value of the name expression is of type
xs:string or xs:untypedAtomic, that value
is converted to an expanded QName. If the string value
contains a namespace prefix, that prefix is resolved to a namespace
URI using the statically known namespaces. If the
string value contains no namespace prefix, it is treated as a local
name in the default element/type namespace. The
resulting expanded QName is used as the
node-name property of the constructed element,
retaining the prefix part of the QName. If conversion of the
atomized name
expression to an expanded QName is not successful, a dynamic error is
raised [err:XQDY0074].
The content expression of a computed
element constructor (if present) is processed in exactly the same
way as an enclosed expression in the content of a direct
element constructor, as described in Step 1e of 3.7.1.3 Content. The result of processing
the content expression is a sequence of nodes called the content
sequence. If the content expression is absent, the
content sequence is an empty sequence.
Processing of the computed element constructor proceeds as
follows:
-
If the content sequence contains a document node, the document
node is replaced in the content sequence by its children.
-
Adjacent text nodes in the content sequence are merged into a
single text node by concatenating their contents, with no
intervening blanks. After concatenation, any text node whose
content is a zero-length string is deleted from the content
sequence.
-
If the content sequence contains an attribute node or a
namespace node following a node that is not an attribute node or a
namespace node, a type
error is raised [err:XQTY0024].
-
The properties of the newly constructed element node are
determined as follows:
-
node-name is the expanded QName resulting from processing
the specified QName or name expression, as described above.
-
parent is empty.
-
attributes consist of all the attribute nodes in
the content sequence, in implementation-dependent order.
Note that the parent property of each of these
attribute nodes has been set to the newly constructed element node.
If two or more attributes have the same node-name, a
dynamic error
is raised [err:XQDY0025]. If an attribute named
xml:space has a value other than preserve
or default, a dynamic error MAY be raised [err:XQDY0092].
-
children consist of all the element, text, comment,
and processing instruction nodes in the content sequence. Note that
the parent property of each of these nodes has been
set to the newly constructed element node.
-
base-uri is set to the following value:
-
If the constructed node has an attribute named
xml:base, then the value of this attribute, resolved
if it is relative against the base URI in the static context. The value of the
xml:base attribute is normalized as described in
[XML Base].
-
Otherwise, the value of the base URI in the static context.
-
in-scope-namespaces are computed as described in
3.7.4 In-scope Namespaces of
a Constructed Element.
-
The nilled property is false.
-
The string-value property is equal to the
concatenated contents of the text-node descendants in document
order.
-
The typed-value property is equal to the
string-value property, as an instance of
xs:untypedAtomic.
-
If construction mode in the static context is
strip, the type-name property is
xs:untyped. On the other hand, if construction mode is
preserve, the type-name property is
xs:anyType.
-
The is-id and is-idrefs properties are
set to false.
A computed element constructor might be used to make a modified
copy of an existing element. For example, if the variable
$e is bound to an element with numeric content, the following constructor
might be used to create a new element with the same name and
attributes as $e and with numeric content equal to
twice the value of $e:
element {fn:node-name($e)}
{$e/@*, 2 * fn:data($e)}
In this example, if $e is bound by the expression
let $e := <length
units="inches">{5}</length>, then the result of the
example expression is the element <length
units="inches">10</length>.
Note:
The static
type of the expression fn:node-name($e) is
xs:QName?, denoting zero or one QName. Therefore, if
the Static Typing Feature is in effect,
the above example raises a static type error, since the name
expression in a computed element constructor is required to return
exactly one string or QName. In order to avoid the static type
error, the name expression fn:node-name($e) could be
rewritten as fn:exactly-one(fn:node-name($e)). If the
Static Typing Feature is not in
effect, the example can be successfully evaluated as written,
provided that $e is bound to exactly one element node
with numeric content.
One important purpose of computed constructors is to allow the
name of a node to be computed. We will illustrate this feature by
an expression that translates the name of an element from one
language to another. Suppose that the variable $dict
is bound to a dictionary element containing a sequence
of entry elements, each of which encodes translations
for a specific word. Here is an example entry that encodes the
German and Italian variants of the word "address":
<entry word="address">
<variant xml:lang="de">Adresse</variant>
<variant xml:lang="it">indirizzo</variant>
</entry>
Suppose further that the variable $e is bound to
the following element:
<address>123 Roosevelt Ave. Flushing, NY 11368</address>
Then the following expression generates a new element in which
the name of $e has been translated into Italian and
the content of $e (including its attributes, if any)
has been preserved. The first enclosed expression after the
element keyword generates the name of the element, and
the second enclosed expression generates the content and
attributes:
element
{$dict/entry[@word=name($e)]/variant[@xml:lang="it"]}
{$e/@*, $e/node()}
The result of this expression is as follows:
<indirizzo>123 Roosevelt Ave. Flushing, NY 11368</indirizzo>
Note:
As in the previous example, if the Static
Typing Feature is in effect, the enclosed expression that
computes the element name in the above computed element constructor
must be wrapped in a call to the fn:exactly-one
function in order to avoid a static type error.
Additional examples of computed element constructors can be
found in I.3 Recursive
Transformations.
3.7.3.2 Computed Attribute
Constructors
| [136] |
CompAttrConstructor |
::= |
"attribute" (QName |
("{" Expr "}")) "{" Expr? "}" |
A computed attribute constructor creates a new attribute node,
with its own node identity.
If the keyword attribute is followed by a QName,
that QName is expanded using the statically known namespaces, and the
resulting expanded QName (including its prefix) is
used as the node-name property of the constructed
attribute node. If expansion of the QName is not successful, a
static error is
raised [err:XPST0081].
If the keyword attribute is followed by a name expression,
the name expression is processed as follows:
-
Atomization is
applied to the result of the name expression. If the result of
atomization is
not a single atomic value of type xs:QName,
xs:string, or xs:untypedAtomic, a
type error is
raised [err:XPTY0004].
-
If the atomized value of the name expression is of type
xs:QName:
-
If the expanded QName returned by the atomized
name expression has a namespace URI but has no prefix, it is given
an implementation-dependent
prefix.
Note:
This step is necessary because attributes have no default
namespace. Therefore any attribute name that has a namespace URI
must also have a prefix.
-
The resulting expanded QName (including its prefix) is
used as the node-name property of the constructed
attribute node.
-
If the atomized value of the name expression is of type
xs:string or xs:untypedAtomic, that value
is converted to an expanded QName. If the string value
contains a namespace prefix, that prefix is resolved to a namespace
URI using the statically known namespaces. If the
string value contains no namespace prefix, it is treated as a local
name in no namespace. The resulting expanded QName (including its prefix) is
used as the node-name property of the constructed
attribute. If conversion of the atomized name expression to an expanded QName is
not successful, a dynamic error is raised [err:XQDY0074].
The node-name property of the constructed attribute
(an expanded
QName) is checked as follows: If its URI part is
http://www.w3.org/2000/xmlns/ (corresponding to
namespace prefix xmlns) or if it is in no namespace
and its local name is xmlns, a dynamic error
[err:XQDY0044] is
raised.
The content expression of a computed
attribute constructor is processed as follows:
-
Atomization is
applied to the result of the content expression, converting it to a
sequence of atomic values. (If the content expression is absent, the
result of this step is an empty sequence.)
-
If the result of atomization is an empty sequence, the value of
the attribute is the zero-length string. Otherwise, each atomic
value in the atomized sequence is cast into a string.
-
The individual strings resulting from the previous step are
merged into a single string by concatenating them with a single
space character between each pair. The resulting string becomes the
string-value property of the new attribute node. The
type
annotation (type-name property) of the new
attribute node is xs:untypedAtomic. The
typed-value property of the attribute node is the same
as its string-value, as an instance of
xs:untypedAtomic.
-
The parent property of the attribute node is set to
empty.
-
If the attribute name is xml:id, then
xml:id processing is performed as defined in [XML ID]. This ensures that the attribute node has the
type xs:ID and that its value is properly normalized.
If an error is encountered during xml:id processing,
an implementation MAY raise a
dynamic error
[err:XQDY0091].
-
If the attribute name is xml:id, the
is-id property of the resulting attribute node is set
to true; otherwise the is-id property is
set to false. The is-idrefs property of
the attribute node is unconditionally set to
false.
-
If the attribute name is xml:space and the
attribute value is other than preserve or
default, a dynamic error MAY be raised [err:XQDY0092].
3.7.3.3 Document Node
Constructors
| [133] |
CompDocConstructor |
::= |
"document" "{" Expr
"}" |
All document node constructors are computed constructors. The
result of a document node constructor is a new document node, with
its own node identity.
A document node constructor is useful when the result of a query
is to be a document in its own right. The following example
illustrates a query that returns an XML document containing a root
element named author-list:
document
{
<author-list>
{fn:doc("bib.xml")/bib/book/author}
</author-list>
}
The content expression of a document node
constructor is processed in exactly the same way as an enclosed
expression in the content of a direct
element constructor, as described in Step 1e of 3.7.1.3 Content. The result of processing
the content expression is a sequence of nodes called the content
sequence. Processing of the document node constructor then
proceeds as follows:
-
If the content sequence contains a document node, the document
node is replaced in the content sequence by its children.
-
Adjacent text nodes in the content sequence are merged into a
single text node by concatenating their contents, with no
intervening blanks. After concatenation, any text node whose
content is a zero-length string is deleted from the content
sequence.
-
If the content sequence contains an attribute node, a type error is raised
[err:XPTY0004].
-
If the content sequence contains a namespace node, a type error is raised
[err:XPTY0004].
-
The properties of the newly constructed document node are
determined as follows:
-
base-uri is taken from base URI in the static context. If no base URI is defined in the
static context, the base-uri property is empty.
-
children consist of all the element, text, comment,
and processing instruction nodes in the content sequence. Note that
the parent property of each of these nodes has been
set to the newly constructed document node.
-
The unparsed-entities and document-uri
properties are empty.
-
The string-value property is equal to the
concatenated contents of the text-node descendants in document
order.
-
The typed-value property is equal to the
string-value property, as an instance of
xs:untypedAtomic.
No validation is performed on the constructed document node. The
[XML 1.0] rules that govern the structure of an
XML document (for example, the document node must have exactly one
child that is an element node) are not enforced by the XQuery
document node constructor.
3.7.3.4 Text Node Constructors
| [140] |
CompTextConstructor |
::= |
"text" "{" Expr
"}" |
All text node constructors are computed constructors. The result
of a text node constructor is a new text node, with its own node
identity.
The content expression of a text node
constructor is processed as follows:
-
Atomization is
applied to the value of the content expression, converting it to a
sequence of atomic values.
-
If the result of atomization is an empty sequence, no text node
is constructed. Otherwise, each atomic value in the atomized
sequence is cast into a string.
-
The individual strings resulting from the previous step are
merged into a single string by concatenating them with a single
space character between each pair. The resulting string becomes the
content property of the constructed text node.
The parent property of the constructed text node is
set to empty.
Note:
It is possible for a text node constructor to construct a text
node containing a zero-length string. However, if used in the
content of a constructed element or document node, such a text node
will be deleted or merged with another text node.
The following example illustrates a text node constructor:
3.7.3.5
Computed Processing Instruction Constructors
| [142] |
CompPIConstructor |
::= |
"processing-instruction" (NCName | ("{" Expr "}")) "{" Expr? "}" |
A computed processing instruction constructor (CompPIConstructor) constructs a
new processing instruction node with its own node identity.
If the keyword processing-instruction is followed
by an NCName, that NCName is used as the target
property of the constructed node. If the keyword
processing-instruction is followed by a name expression,
the name expression is processed as follows:
-
Atomization is
applied to the value of the name expression. If the result of
atomization is
not a single atomic value of type xs:NCName,
xs:string, or xs:untypedAtomic, a
type error is
raised [err:XPTY0004].
-
If the atomized value of the name expression is of type
xs:string or xs:untypedAtomic, that value
is cast to the type xs:NCName. If the value cannot be
cast to xs:NCName, a dynamic error is raised [err:XQDY0041].
-
The resulting NCName is then used as the target
property of the newly constructed processing instruction node.
However, a dynamic error is raised if the NCName is
equal to "XML" (in any combination of upper and lower
case) [err:XQDY0064].
The content expression of a computed
processing instruction constructor is processed as follows:
-
Atomization is
applied to the value of the content expression, converting it to a
sequence of atomic values. (If the content expression is absent, the
result of this step is an empty sequence.)
-
If the result of atomization is an empty sequence, it is
replaced by a zero-length string. Otherwise, each atomic value in
the atomized sequence is cast into a string. If any of the
resulting strings contains the string "?>", a
dynamic error
[err:XQDY0026] is
raised.
-
The individual strings resulting from the previous step are
merged into a single string by concatenating them with a single
space character between each pair. Leading whitespace is removed
from the resulting string. The resulting string then becomes the
content property of the constructed processing
instruction node.
The remaining properties of the new processing instruction node
are determined as follows:
-
The parent property is empty.
-
The base-uri property is empty.
The following example illustrates a computed processing
instruction constructor:
let $target := "audio-output",
$content := "beep"
return processing-instruction {$target} {$content}
The processing instruction node constructed by this example
might be serialized as follows:
3.7.3.6 Computed Comment
Constructors
| [141] |
CompCommentConstructor |
::= |
"comment" "{" Expr
"}" |
A computed comment constructor (CompCommentConstructor)
constructs a new comment node with its own node identity. The
content
expression of a computed comment constructor is processed as
follows:
-
Atomization is
applied to the value of the content expression, converting it to a
sequence of atomic values.
-
If the result of atomization is an empty sequence, it is
replaced by a zero-length string. Otherwise, each atomic value in
the atomized sequence is cast into a string.
-
The individual strings resulting from the previous step are
merged into a single string by concatenating them with a single
space character between each pair. The resulting string becomes the
content property of the constructed comment node.
-
It is a dynamic error [err:XQDY0072] if the result of the
content
expression of a computed comment constructor contains two
adjacent hyphens or ends with a hyphen.
The parent property of the constructed comment node
is set to empty.
The following example illustrates a computed comment
constructor:
let $homebase := "Houston"
return comment {fn:concat($homebase, ", we have a problem.")}
The comment node constructed by this example might be serialized
as follows:
<!--Houston, we have a problem.-->
3.7.3.7 Computed Namespace
Constructors
A computed namespace constructor creates a new namespacee node,
with its own node identity. The parent of the newly created
namespace node is empty.
If the constructor specifies a Prefix, it is used
as the prefix for the namespace node.
If the constructor specifies a PrefixExpr, the
prefix expression is evaluated as follows: Atomization is applied to the result of
the name
expression. If the result of atomization a single atomic value of type
xs:NCName, xs:string, or
xs:untypedAtomic, it is used as the
prefix property of the newly constructed namespace
node. If the result is the empty sequence or an empty string, the
prefix property of the newly constructed namespace
node is empty. For any other result, a type error is raised [err:XPTY0004].
The URIExpr is evaluated, and the result is cast to
xs:anyURI to create the URI property for
the newly created node.
An error [err:XQDY0101] is raised if the namespace URI in
a computed namespace constructor is bound to the predefined prefix
xmlns, or if a namespace URI other than
http://www.w3.org/XML/1998/namespace is bound to the
prefix xml, or if the prefix xml is bound
to a namespace URI other than
http://www.w3.org/XML/1998/namespace.
By itself, a computed namespace constructor has no effect on
in-scope namespaces, but if an element constructor's content
sequence contains a namespace node, the namespace binding it
represents is added to the elements in-scope namespaces.
A computed namespace constructor has no effect on the statically
known namespaces.
Note:
The newly created namespace node has all properties defined for
a namespace node in the data model. Like all nodes, it has
identity. Like all nodes who do not share a common parent, the
relative order of these nodes is implementation dependent. As
defined in the data model, the name of the node is the prefix, and
the string value of the node is the URI.
Examples:
-
A computed namespace constructor with a prefix:
namespace a {"http://a.example.com" }
-
A computed namespace constructor with a prefix expression:
namespace {"a"} {"http://a.example.com" }
-
A computed namespace constructor with an empty prefix:
namespace { "" } {"http://a.example.com" }
Computed namespace constructors are generally used to add to the
in-scope namespaces of elements created with element
constructors:
<form>
{
namespace a {"http://a.example.com" },
attribute { xs:QName("a:id") } { "a-12-XE-45" },
element { xs:QName("a:field")} { "Sample data" }
}
</form>
Computed namespace constructors have no effect on the statically
known namespaces. If the prefix a is not already defined in the
statically known namespaces, the following expression results in a
static error [err:XPST0081].
<a:form>
{
namespace a { "http://a.example.com" }
}
</a:form>
3.7.4 In-scope Namespaces of a
Constructed Element
An element node constructed by a direct or computed element
constructor has an in-scope namespaces property that
consists of a set of namespace bindings. The in-scope
namespaces of an element node may affect the way the node is
serialized (see 2.2.4
Serialization), and may also affect the behavior of certain
functions that operate on nodes, such as fn:name. Note
the difference between in-scope namespaces, which is a
dynamic property of an element node, and statically known namespaces, which is a
static property of an expression. Also note that one of the
namespace bindings in the in-scope namespaces may have no prefix
(denoting the default namespace for the given element). The
in-scope namespaces of a constructed element node consist of the
following namespace bindings:
-
A namespace binding is created for each namespace declared in
the current element constructor by a namespace declaration attribute.
-
A namespace binding is created for each namespace node in the
context sequence of the current element constructor.
-
A namespace binding is created for each namespace that is
declared in a namespace declaration attribute of an
enclosing direct element constructor and not
overridden by the current element constructor or an intermediate
constructor.
-
A namespace binding is always created to bind the prefix
xml to the namespace URI
http://www.w3.org/XML/1998/namespace.
-
For each namespace used in the name of the constructed element
or in the names of its attributes, a namespace binding must exist.
If a namespace binding does not already exist for one of these
namespaces, a new namespace binding is created for it. If the name
of the node includes a prefix, that prefix is used in the namespace
binding; if the name has no prefix, then a binding is created for
the empty prefix. If this would result in a conflict, because it
would require two different bindings of the same prefix, then the
prefix used in the node name is changed to an arbitrary implementation-dependent prefix
that does not cause such a conflict, and a namespace binding is
created for this new prefix.
Note:
Copy-namespaces mode does not affect
the namespace bindings of a newly constructed element node. It
applies only to existing nodes that are copied by a constructor
expression.
In an element constructor, if two or more namespace bindings in
the in-scope bindings would have the same prefix, then an error is
raised if they have different URIs [err:XQTY0102]; if they would have the same
prefix and URI, duplicate bindings are ignored.
The following query serves as an example:
declare namespace p="http://example.com/ns/p";
declare namespace q="http://example.com/ns/q";
declare namespace f="http://example.com/ns/f";
<p:a q:b="{f:func(2)}" xmlns:r="http://example.com/ns/r"/>
The in-scope namespaces of the resulting
p:a element consists of the following namespace
bindings:
-
p = "http://example.com/ns/p"
-
q = "http://example.com/ns/q"
-
r = "http://example.com/ns/r"
-
xml = "http://www.w3.org/XML/1998/namespace"
The namespace bindings for p and q are
added to the result element because their respective namespaces are
used in the names of the element and its attributes. The namespace
binding r="http://example.com/ns/r" is added to the
in-scope namespaces of the constructed element because it is
defined by a namespace declaration attribute, even
though it is not used in a name.
No namespace binding corresponding to
f="http://example.com/ns/f" is created, because the
namespace prefix f appears only in the query prolog
and is not used in an element or attribute name of the constructed
node. This namespace binding does not appear in the query result,
even though it is present in the statically known namespaces and is
available for use during processing of the query.
Note that the following constructed element, if nested within a
validate expression, cannot be validated:
<p xsi:type="xs:integer">3</p>
The constructed element will have namespace bindings for the
prefixes xsi (because it is used in a name) and
xml (because it is defined for every constructed
element node). During validation of the constructed element, the
validator will be unable to interpret the namespace prefix
xs because it is has no namespace binding. Validation
of this constructed element could be made possible by providing a
namespace declaration attribute, as
in the following example:
<p xmlns:xs="http://www.w3.org/2001/XMLSchema"
xsi:type="xs:integer">3</p>
3.8 FLWOR Expressions
XQuery provides a versatile expression called a FLWOR expression
that may contain multiple clauses. The FLWOR expression can be used
for many purposes, including iterating over sequences, joining
multiple documents, and performing grouping and aggregation. The
name FLWOR, pronounced "flower", is suggested by the keywords
for, let, where, order
by, and return, which introduce some of the
clauses used in FLWOR expressions (but this is not a complete list
of such clauses.)
The complete syntax of a FLWOR expression is shown here, and
relevant parts of the syntax are repeated in subsequent sections of
this document.
The semantics of FLWOR expressions are based on a concept called
a tuple stream. [Definition: A
tuple stream is an ordered sequence of zero or more
tuples.] [Definition: A tuple is a set of zero or
more named variables, each of which is bound to a value that is an
XDM
instance.] Each tuple stream is homogeneous in the sense that
all its tuples contain variables with the same names and the same
static types. The
following example illustrates a tuple stream consisting of four
tuples, each containing three variables named $x,
$y, and $z:
($x = 1003, $y = "Fred", $z = <age>21</age>)
($x = 1017, $y = "Mary", $z = <age>35</age>)
($x = 1020, $y = "Bill", $z = <age>18</age>)
($x = 1024, $y = "John", $z = <age>29</age>)
Note:
In this section, tuple streams are represented as shown in the
above example. Each tuple is on a separate line and is enclosed in
parentheses, and the variable bindings inside each tuple are
separated by commas. This notation does not represent XQuery
syntax, but is simply a representation of a tuple stream for the
purpose of defining the semantics of FLWOR expressions.
Tuples and tuple streams are not part of the data model. They exist only
as conceptual intermediate results during the processing of a FLWOR
expression.
A FLWOR expression consists of an initial clause, zero or more
intermediate clauses, and a final clause. Conceptually, the initial
clause generates a tuple stream. Each intermediate clause takes the
tuple stream generated by the previous clause as input and
generates a (possibly different) tuple stream as output. The final
clause takes a tuple stream as input and, for each tuple in this
tuple stream, generates an XDM instance; the final result of the
FLWOR expression is the ordered concatenation of these XDM
instances.
The initial clause in a FLWOR expression may be a
for, let, window, or
count clause. Intermediate clauses may be
for, let, window,
count, where, group by, or
order by clauses. These intermediate clauses may be
repeated as many times as desired, in any order. The final clause
of the FLWOR expression must be a return clause. The
semantics of the various clauses are described in the following
sections.
3.8.1
Variable Bindings
The following clauses in FLWOR expressions bind values to
variables: for, let, window,
and count (in addition, a group by clause
changes the values of variables that were previously bound.) In
each case, binding of variables is governed by the following
rules:
-
The scope of a bound variable includes all subexpressions of the
containing FLWOR that appear after the variable binding. The scope
does not include the expression to which the variable is bound. The
following code fragment, containing two let clauses,
illustrates how variable bindings may reference variables that were
bound in earlier clauses, or in earlier bindings in the same
clause:
let $x := 47, $y := f($x)
let $z := g($x, $y)
-
A given variable may be bound more than once in a FLWOR
expression, or even within one clause of a FLWOR expression. In
such a case, each new binding occludes the previous one, which
becomes inaccessible in the remainder of the FLWOR expression.
-
[Definition: A variable binding may be
accompanied by a type declaration, which consists of the
keyword as followed by the static type of the
variable, declared using the syntax in 2.5.3 SequenceType Syntax.] At
run time, if the value bound to the variable does not match the
declared type according to the rules for SequenceType matching, a type error is raised
[err:XPTY0004]. For
example, the following let clause raises a type error because the
variable $salary has a type declaration that is not
satisfied by the value that is bound to it:
let $salary as xs:decimal := "cat"
-
[Definition: In a for clause or
window clause, when an expression is preceded by the
keyword in, the value of that expression is called a
binding sequence.] The for and
window clauses iterate over their binding sequences,
producing multiple bindings for one or more variables. Details on
how binding sequences are used in for and
window clauses are described in the following
sections.
3.8.2 For Clause
A for clause is used for iteration. Each variable
in a for clause iterates over a sequence and is bound
in turn to each item in the sequence.
If a for clause contains multiple variables, it is
semantically equivalent to multiple for clauses, each
containing one of the variables in the original for
clause. In each of the semantically equivalent single-variable
for clauses, the presence or absence of the
outer keyword is the same as in the original
for clause.
Examples:
In the remainder of this section, we define the semantics of a
for clause containing a single variable and an
associated expression (following the keyword in) whose
value is called the binding sequence for that variable.
If a single-variable for clause is the initial
clause in a FLWOR expression, it iterates over its binding
sequence, binding the variable to each item in turn. The
resulting sequence of variable bindings becomes the initial tuple
stream that serves as input to the next clause of the FLWOR
expression. If ordering mode is ordered, the
order of tuples in the tuple stream preserves the order of the
binding
sequence; otherwise the order of the tuple stream is implementation-dependent.
If the binding sequence contains no items, the
output tuple stream depends on the presence or absence of the
outer keyword. If outer is specified, the
output tuple stream consists of one tuple in which the variable is
bound to an empty sequence. If outer is not specified,
the output tuple stream consists of zero tuples.
The following examples illustrates tuple streams that are
generated by initial for clauses:
[Definition: A positional
variable is a variable that is preceded by the keyword
at.] A positional variable may be associated with a
variable that is bound in a for clause. In this case,
as the main variable iterates over the items in its binding
sequence, the positional variable iterates over the integers
that represent the ordinal numbers of these items in the binding
sequence, starting with one. Each tuple in the output tuple
stream contains bindings for both the main variable and the
positional variable. If the binding sequence is empty and
outer is specified, the positional variable in the
output tuple is bound to the integer zero. Positional variables
always have the implied type xs:integer. The expanded QName of a
positional variable must be distinct from the expanded QName of
the main variable with which it is associated [err:XQST0089].
The following examples illustrate how a positional variable
would have affected the results of the previous examples that
generated tuples:
-
Initial clause:
for $x at $i in (100, 200, 300)
Output tuple stream:
($x = 100, $i = 1)
($x = 200, $i = 2)
($x = 300, $i = 3)
-
Initial clause:
Output tuple stream:
If a single-variable for clause is an intermediate
clause in a FLWOR expression, its binding sequence is evaluated for each
input tuple, given the bindings in that input tuple. Each input
tuple generates zero or more tuples in the output tuple stream.
Each of these output tuples consists of the original variable
bindings of the input tuple plus a binding of the new variable to
one of the items in its binding sequence.
Note:
Although the binding sequence is conceptually
evaluated independently for each input tuple, an optimized
implementation may sometimes be able to avoid re-evaluating the
binding
sequence if it can show that the variables that the binding sequence
depends on have the same values as in a previous evaluation.
For a given input tuple, if the binding sequence for the new
variable in the for clause contains no items, the
result depends on the presence or absence of the outer
keyword. If outer is specified, the input tuple
generates one output tuple, with the original variable bindings
plus a binding of the new variable to an empty sequence. If
outer is not specified, the input tuple generates zero
output tuples (it is not represented in the output tuple
stream.)
If the new variable introduced by a for clause has
an associated positional variable, the output
tuples generated by the for clause also contain
bindings for the positional variable. In this case, as
the new variable is bound to each item in its binding
sequence, the positional variable is bound to the
ordinal position of that item within the binding
sequence, starting with one. Note that, since the positional
variable represents a position within a binding
sequence, the output tuples corresponding to each input tuple
are independently numbered, starting with one. For a given input
tuple, if the binding sequence is empty and
outer is specified, the positional variable in the
output tuple is bound to the integer zero.
If ordering
mode is ordered, the tuples in the output tuple
stream are ordered primarily by the order of the input tuples from
which they are derived, and secondarily by the order of the
binding
sequence for the new variable; otherwise the order of the
output tuple stream is implementation-dependent.
The following examples illustrates the effects of intermediate
for clauses:
-
Input tuple stream:
($x = 1)
($x = 2)
($x = 3)
($x = 4)
Intermediate for clause:
Output tuple stream (assuming ordering mode is ordered):
($x = 1, $y = 1)
($x = 1, $y = 2)
($x = 1, $y = 3)
($x = 2, $y = 2)
($x = 2, $y = 3)
($x = 3, $y = 3)
Note:
In this example, there is no output tuple that corresponds to
the input tuple ($x = 4) because, when the
for clause is evaluated with the bindings in this
input tuple, the resulting binding sequence for $y is
empty.
-
This example shows how the previous example would have been
affected by a positional variable (assuming the
same input tuple stream):
for $y at $j in ($x to 3)
Output tuple stream (assuming ordering mode is ordered):
($x = 1, $y = 1, $j = 1)
($x = 1, $y = 2, $j = 2)
($x = 1, $y = 3, $j = 3)
($x = 2, $y = 2, $j = 1)
($x = 2, $y = 3, $j = 2)
($x = 3, $y = 3, $j = 1)
-
This example shows how the previous example would have been
affected by the outer keyword. Note that the
outer keyword causes the input tuple ($x =
4) to be represented in the output tuple stream, even though
the binding
sequence for $y contains no items for this input
tuple. This example illustrates that the outer keyword
in a for clause serves a purpose similar to that of an
"outer join" in a relational database query. (Assume the same input
tuple stream as in the previous example.)
outer for $y at $j in ($x to 3)
Output tuple stream (assuming ordering mode is ordered):
($x = 1, $y = 1, $j = 1)
($x = 1, $y = 2, $j = 2)
($x = 1, $y = 3, $j = 3)
($x = 2, $y = 2, $j = 1)
($x = 2, $y = 3, $j = 2)
($x = 3, $y = 3, $j = 1)
($x = 4, $y = (), $j = 0)
-
This example shows how a for clause that binds two
variables is semantically equivalent to two for
clauses that bind one variable each. We assume that this
for clause occurs at the beginning of a FLWOR
expression. It is equivalent to an initial single-variable
for clause that provides an input tuple stream to an
intermediate single-variable for clause.
for $x in (1, 2, 3, 4), $y in ($x to 3)
Output tuple stream (assuming ordering mode is ordered):
($x = 1, $y = 1)
($x = 1, $y = 2)
($x = 1, $y = 3)
($x = 2, $y = 2)
($x = 2, $y = 3)
($x = 3, $y = 3)
In the above examples, if ordering mode had been
unordered, the output tuple streams would have
consisted of the same tuples, with the same values for the
positional variables, but the
ordering of the tuples would have been implementation-dependent.
A for clause may contain one or more type
declarations, identified by the keyword as. The
semantics of type declarations are defined in
3.8.1 Variable Bindings.
3.8.3 Let Clause
The purpose of a let clause is to bind values to
one or more variables. Each variable is bound to the result of
evaluating an expression.
If a let clause contains multiple variables, it is
semantically equivalent to multiple let clauses, each
containing a single variable. For example, the clause
let $x := $expr1, $y := $expr2
is semantically equivalent to the following sequence of
clauses:
let $x := $expr1
let $y := $expr2
In the remainder of this section, we define the semantics of a
let clause containing a single variable V and
an associated expression E.
If a single-variable let clause is the initial
clause in a FLWOR expression, it simply binds the variable
V to the result of the expression E. The result
of the let clause is a tuple stream consisting of one
tuple with a single binding that binds V to the result of
E. This tuple stream serves as input to the next clause in
the FLWOR expression.
If a single-variable let clause is an intermediate
clause in a FLWOR expression, it adds a new binding for variable
V to each tuple in the input tuple stream. For each input
tuple, the value bound to V is the result of evaluating
expression E, given the bindings that are already present
in that input tuple. The resulting tuples become the output tuple
stream of the let clause.
The number of tuples in the output tuple stream of an
intermediate let clause is the same as the number of
tuples in the input tuple stream. The number of bindings in the
output tuples is one more than the number of bindings in the input
tuples, unless the input tuples already contain bindings for
V; in this case, the new binding for V occludes
(replaces) the earlier binding for V, and the number of
bindings is unchanged.
A let clause may contain one or more type
declarations, identified by the keyword as. The
semantics of type declarations are defined in 3.8.1 Variable Bindings.
The following code fragment illustrates how a for
clause and a let clause can be used together. The
for clause produces an initial tuple stream containing
a binding for variable $d to each department number
found in a given input document. The let clause adds
an additional binding to each tuple, binding variable
$e to a sequence of employees whose department number
matches the value of $d in that tuple.
for $d in fn:doc("depts.xml")/depts/deptno
let $e := fn:doc("emps.xml")/emps/emp[deptno eq $d]
3.8.4 Window
Clause
Like a for clause, a window clause
iterates over its binding sequence and generates a
sequence of tuples. In the case of a window clause,
each tuple represents a window. [Definition: A window is a sequence of
consecutive items drawn from the binding sequence.] Each window is
represented by at least one and at most nine bound variables. The
variables have user-specified names, but their roles are as
follows:
-
Window-variable: Bound to the sequence of items from
the binding
sequence that comprise the window.
-
Start-item: (Optional) Bound to the first item in the
window.
-
Start-item-position: (Optional) Bound to the ordinal
position of the first window item in the binding
sequence. Start-item-position is a positional
variable. Its type is xs:integer, and its expanded
QName must be distinct from the expanded QName of
start-item [err:XQST0089].
-
Start-previous-item: (Optional) Bound to the item in
the binding
sequence that precedes the first item in the window (empty
sequence if none).
-
Start-next-item: (Optional) Bound to the item in the
binding
sequence that follows the first item in the window (empty
sequence if none).
-
End-item: (Optional) Bound to the last item in the
window.
-
End-item-position: (Optional) Bound to the ordinal
position of the last window item in the binding sequence.
End-item-position is a positional variable. Its type is
xs:integer, and its expanded QName must be distinct
from the expanded QName of end-item [err:XQST0089].
-
End-previous-item: (Optional) Bound to the item in the
binding
sequence that precedes the last item in the window (empty
sequence if none).
-
End-next-item: (Optional) Bound to the item in the
binding
sequence that follows the last item in the window (empty
sequence if none).
All variables in a window clause must have distinct
names; otherwise a static error is raised [err:XQST0103].
The following is an example of a window clause that
binds nine variables to the roles listed above. In this example,
the variables are named $w, $s,
$spos, $sprev, $snext,
$e, $epos, $eprev, and
$enext respectively. A window clause
always binds the window variable, but typically binds only a subset
of the other variables.
for tumbling window $w in (2, 4, 6, 8, 10)
start $s at $spos previous $sprev next $snext when true() end $e at
$epos previous $eprev next $enext when true()
Windows are created by iterating over the items in the binding
sequence, in order, identifying the start item and the end item
of each window by evaluating the WindowStartCondition and the
WindowEndCondition.
Each of these conditions is satisfied if the effective boolean
value of the expression following the when keyword
is true. The start item of the window is an item that
satisfies the WindowStartCondition (see
3.8.4.1 Tumbling Windows
and 3.8.4.2 Sliding
Windows for a more complete explanation.) The end item of
the window is the first item in the binding sequence, beginning with
the start item, that satisfies the WindowEndCondition (again, see
3.8.4.1 Tumbling Windows
and 3.8.4.2 Sliding
Windows for more details.) Each window contains its start
item, its end item, and all items that occur between them in the
binding
sequence. If the end item is the start item, then the window
contains only one item. If a start item is identified, but no
following item in the binding sequence satisfies the WindowEndCondition, then the
only keyword determines whether a window is generated:
if only end is specified, then no window is generated;
otherwise, the end item is set to the last item in the binding sequence
and a window is generated.
In the above example, the WindowStartCondition and
WindowEndCondition are
both true(), which causes each tuple in the binding sequence
to be in a separate window. Typically, the WindowStartCondition and
WindowEndCondition are
expressed in terms of bound variables. For example, the following
WindowStartCondition
might be used to start a new window for every item in the binding sequence
that is larger than both the previous item and the following
item:
start $s previous $sprev next $snext
when $s > $sprev and $s > $snext
The scoping rules for the variables bound by a
window clause are as follows:
-
In the when-expression of the WindowStartCondition, the
following variables (identified here by their roles) are in scope
(if bound): start-item, start-item-position,
start-previous-item, start-next-item.
-
In the when-expression of the WindowEndCondition, the
following variables (identified here by their roles) are in scope
(if bound): start-item, start-item-position,
start-previous-item, start-next-item, end-item, end-item-position,
end-previous-item, end-next-item.
-
In the clauses of the FLWOR expression that follow the
window clause, all nine of the variables bound by the
window clause (including window-variable) are
in scope (if bound).
In a window clause, the keyword
tumbling or sliding determines the way in
which the starting item of each window is identified, as explained
in the following sections.
3.8.4.1 Tumbling Windows
If the window type is tumbling, then windows never
overlap. The search for the start of the first window begins at the
beginning of the binding sequence. After each window is
generated, the search for the start of the next window begins with
the item in the binding sequence that occurs after the
ending item of the last generated window. Thus, no item that occurs
in one window can occur in another window drawn from the same
binding
sequence. In a tumbling window clause, the end
clause is optional; if it is omitted, the start clause
is applied to identify all potential starting items in the
binding
sequence, and a window is constructed for each starting item,
including all items from that starting item up to the item before
the next window's starting item, or the end of the binding
sequence, whichever comes first.
The following examples illustrate the use of tumbling
windows.
-
Show non-overlapping windows of three items.
for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
start at $s when fn:true()
only end at $e when $e - $s eq 2
return <window>{ $w }</window>
Result of the above query:
<window>2 4 6</window>
<window>8 10 12</window>
-
Show averages of non-overlapping three-item windows.
for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
start at $s when fn:true()
only end at $e when $e - $s eq 2
return avg($w)
Result of the above query:
-
Show first and last items in each window of three items.
for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
start $first at $s when fn:true()
only end $last at $e when $e - $s eq 2
return <window>{ $first, $last }</window>
Result of the above query:
<window>2 6</window>
<window>8 12</window>
-
Show non-overlapping windows of up to three items (illustrates
end clause without the only keyword).
for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
start at $s when fn:true()
end at $e when $e - $s eq 2
return <window>{ $w }</window>
Result of the above query:
<window>2 4 6</window>
<window>8 10 12</window>
<window>14</window>
-
Show non-overlapping windows of up to three items (illustrates
use of start without explicit end).
for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
start at $s when $s mod 3 = 1
return <window>{ $w }</window>
Result of the above query:
<window>2 4 6</window>
<window>8 10 12</window>
<window>14</window>
-
Show non-overlapping sequences starting with a number divisible
by 3.
for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
start $first when $first mod 3 = 0
return <window>{ $w }</window>
Result of the above query:
<window>6 8 10</window>
<window>12 14</window>
3.8.4.2 Sliding Windows
If the window type is sliding window, then windows
may overlap. Every item in the binding sequence that satisfies the
WindowStartCondition
is the starting item of a new window. Thus, a given item may be
found in multiple windows drawn from the same binding
sequence.
The following examples illustrate the use of sliding
windows.
-
Show windows of three items.
for sliding window $w in (2, 4, 6, 8, 10, 12, 14)
start at $s when fn:true()
only end at $e when $e - $s eq 2
return <window>{ $w }</window>
Result of the above query:
<window>2 4 6</window>
<window>4 6 8</window>
<window>6 8 10</window>
<window>8 10 12</window>
<window>10 12 14</window>
-
Show moving averages of three items.
for sliding window $w in (2, 4, 6, 8, 10, 12, 14)
start at $s when fn:true()
only end at $e when $e - $s eq 2
return avg($w)
Result of the above query:
-
Show overlapping windows of up to three items (illustrates
end clause without the only keyword).
for sliding window $w in (2, 4, 6, 8, 10, 12, 14)
start at $s when fn:true()
end at $e when $e - $s eq 2
return <window>{ $w }</window>
Result of the above query:
<window>2 4 6</window>
<window>4 6 8</window>
<window>6 8 10</window>
<window>8 10 12</window>
<window>10 12 14</window>
<window>12 14</window>
<window>14</window>
3.8.4.3 Effects of Window
Clauses on the Tuple Stream
The effects of a window clause on the tuple stream
are similar to the effects of a for clause. As
described in 3.8.4 Window Clause,
a window clause generates zero or more windows, each
of which is represented by at least one and at most nine bound
variables.
If the window clause is the initial clause in a
FLWOR expression, the bound variables that describe each window
become an output tuple. These tuples form the initial tuple stream
that serves as input to the next clause of the FLWOR expression. If
ordering mode
is ordered, the order of tuples in the tuple stream is
the order in which their start items appear in the binding
sequence; otherwise the order of the tuple stream is implementation-dependent. The
cardinality of the tuple stream is equal to the number of
windows.
If a window clause is an intermediate clause in a
FLWOR expression, each input tuple generates zero or more output
tuples, each consisting of the original bound variables of the
input tuple plus the new bound variables that represent one of the
generated windows. For each tuple T in the input tuple
stream, the output tuple stream will contain NT
tuples, where NT is the number of windows
generated by the window clause, given the bindings in
the input tuple T. Input tuples for which no windows are
generated are not represented in the output tuple stream. If
ordering mode
is ordered, the order of tuples in the output stream
is determined primarily by the order of the input tuples from which
they were derived, and secondarily by the order in which their
start items appear in the binding sequence. If ordering mode is
unordered, the order of tuples in the output stream is
implementation-dependent.
The following example illustrates a window clause
that is the initial clause in a FLWOR expression. The example is
based on input data that consists of a sequence of closing stock
prices for a specific company. For this example we assume the
following input data (assume that the price elements
have a validated type of xs:decimal):
<stock>
<closing> <date>2008-01-01</date> <price>105</price> </closing
<closing> <date>2008-01-02</date> <price>101</price> </closing
<closing> <date>2008-01-03</date> <price>102</price> </closing
<closing> <date>2008-01-04</date> <price>103</price> </closing
<closing> <date>2008-01-05</date> <price>102</price> </closing
<closing> <date>2008-01-06</date> <price>104</price> </closing
</stock>
A user wishes to find "run-ups," which are defined as sequences
of dates that begin with a "low" and end with a "high" price (that
is, the stock price begins to rise on the first day of the run-up,
and continues to rise or remain even through the last day of the
run-up.) The following query uses a tumbling window to find run-ups
in the input data:
for tumbling window $w in //closing
start $first next $second when $first/price < $second/price
end $last next $beyond when $last/price > $beyond/price
return
<run-up>
<start-date>{fn:data($first/date)}</start-date>
<start-price>{fn:data($first/price)}</start-price>
<end-date>{fn:data($last/date)}</end-date>
<end-price>{fn:data($last/price)}</end-price>
</run-up>
For our sample input data, this tumbling window
clause generates a tuple stream consisting of two tuples, each
representing a window and containing five bound variables named
$w, $first, $second,
$last, and $beyond. The
return clause is evaluated for each of these tuples,
generating the following query result:
<run-up>
<start-date>2008-01-02</start-date>
<start-price>101</start-price>
<end-date>2008-01-04</start-date>
<end-price>103</end-price>
</run-up>
<run-up>
<start-date>2008-01-05</start-date>
<start-price>102</start-price>
<end-date>2008-01-06</start-date>
<end-price>104</end-price>
</run-up>
The following example illustrates a window clause
that is an intermediate clause in a FLWOR expression. In this
example, the input data contains closing stock prices for several
different companies, each identified by a three-letter symbol. We
assume the following input data (again assuming that the type of
the price element is xs:decimal):
<stocks>
<closing> <symbol>ABC</symbol> <date>2008-01-01</date> <price>105</price> </closing>
<closing> <symbol>DEF</symbol> <date>2008-01-01</date> <price>057</price> </closing>
<closing> <symbol>ABC</symbol> <date>2008-01-02</date> <price>101</price> </closing>
<closing> <symbol>DEF</symbol> <date>2008-01-02</date> <price>054</price> </closing>
<closing> <symbol>ABC</symbol> <date>2008-01-03</date> <price>102</price> </closing>
<closing> <symbol>DEF</symbol> <date>2008-01-03</date> <price>056</price> </closing>
<closing> <symbol>ABC</symbol> <date>2008-01-04</date> <price>103</price> </closing>
<closing> <symbol>DEF</symbol> <date>2008-01-04</date> <price>052</price> </closing>
<closing> <symbol>ABC</symbol> <date>2008-01-05</date> <price>101</price> </closing>
<closing> <symbol>DEF</symbol> <date>2008-01-05</date> <price>055</price> </closing>
<closing> <symbol>ABC</symbol> <date>2008-01-06</date> <price>104</price> </closing>
<closing> <symbol>DEF</symbol> <date>2008-01-06</date> <price>059</price> </closing>
</stocks>
As in the previous example, we want to find "run-ups," which are
defined as sequences of dates that begin with a "low" and end with
a "high" price for a specific company. In this example, however,
the input data consists of stock prices for multiple companies.
Therefore it is necessary to isolate the stock prices of each
company before forming windows. This can be accomplished by an
initial for and let clause, followed by a
window clause, as follows:
for $symbol in fn:distinct-values(//symbol)
let $closings := //closing[symbol = $symbol]
for tumbling window $w in $closings
start $first next $second when $first/price < $second/price
end $last next $beyond when $last/price > $beyond/price
return
<run-up symbol="{$symbol}">
<start-date>{fn:data($first/date)}</start-date>
<start-price>{fn:data($first/price)}</start-price>
<end-date>{fn:data($last/date)}</end-date>
<end-price>{fn:data($last/price)}</end-price>
</run-up>
Note:
In the above example, the for and let
clauses could be rewritten as follows:
for $closings in //closing
let $symbol := $closings/symbol
group by $symbol
The group by clause is described in 3.8.7 Group By Clause.
The for and let clauses in this query
generate an initial tuple stream consisting of two tuples. In the
first tuple, $symbol is bound to "ABC" and
$closings is bound to the sequence of
closing elements for company ABC. In the second tuple,
$symbol is bound to "DEF" and $closings
is bound to the sequence of closing elements for
company DEF.
The window clause operates on this initial tuple
stream, generating two windows for the first tuple and two windows
for the second tuple. The result is a tuple stream consisting of
four tuples, each with the following bound variables:
$symbol, $closings, $w,
$first, $second, $last, and
$beyond. The return clause is then
evaluated for each of these tuples, generating the following query
result:
<run-up symbol="ABC">
<start-date>2008-01-02</start-date>
<start-price>101</start-price>
<end-date>2008-01-04</start-date>
<end-price>103</end-price>
</run-up>
<run-up symbol="ABC">
<start-date>2008-01-05</start-date>
<start-price>101</start-price>
<end-date>2008-01-06</start-date>
<end-price>104</end-price>
</run-up>
<run-up symbol="DEF">
<start-date>2008-01-02</start-date>
<start-price>54</start-price>
<end-date>2008-01-03</start-date>
<end-price>56</end-price>
</run-up>
<run-up symbol="DEF">
<start-date>2008-01-04</start-date>
<start-price>52</start-price>
<end-date>2008-01-06</start-date>
<end-price>59</end-price>
</run-up>
3.8.5 Where Clause
A where clause serves as a filter for the tuples in
its input tuple stream. The expression in the where
clause, called the where-expression, is evaluated once for
each of these tuples. If the effective boolean value of the where-expression
is true, the tuple is retained in the output tuple
stream; otherwise the tuple is discarded.
Examples:
-
This example illustrates the effect of a where
clause on a tuple stream:
Input tuple stream:
($a = 5, $b = 11)
($a = 91, $b = 42)
($a = 17, $b = 30)
($a = 85, $b = 63)
where clause:
Output tuple stream:
($a = 91, $b = 42)
($a = 85, $b = 63)
-
The following query illustrates how a where clause
might be used with a positional variable to perform
sampling on an input sequence. The query returns one value out of
each one hundred input values.
for $x at $i in $inputvalues
where $i mod 100 = 0
return $x
3.8.6 Count Clause
| [55] |
CountClause |
::= |
"count" "$" VarName |
The purpose of a count clause is to enhance the
tuple stream with a new variable that is bound, in each tuple, to
the ordinal position of that tuple in the tuple stream. The name of
the new variable is specified in the count clause.
The output tuple stream of a count clause is the
same as its input tuple stream, with each tuple enhanced by one
additional variable that is bound to the ordinal position of that
tuple in the tuple stream. However, if the name of the new variable
is the same as the name of an existing variable in the input tuple
stream, the new variable occludes (replaces) the existing variable
of the same name, and the number of bound variables in each tuple
is unchanged.
The following examples illustrate uses of the count
clause:
-
This example illustrates the effect of a count
clause on an input tuple stream:
Input tuple stream:
($name = "Bob", $age = 21)
($name = "Carol", $age = 19)
($name = "Ted", $age = 20)
($name = "Alice", $age = 22)
count clause:
Output tuple stream:
($name = "Bob", $age = 21, $counter = 1)
($name = "Carol", $age = 19, $counter = 2)
($name = "Ted", $age = 20, $counter = 3)
($name = "Alice", $age = 22, $counter = 4)
-
This example illustrates how a counter might be used to filter
the result of a query. The query ranks products in order by
decreasing sales, and returns the three products with the highest
sales. Assume that the variable $products is bound to
a sequence of product elements, each of which has
name and sales child-elements.
for $p in $products
order by $p/sales descending
count $rank
where $rank <= 3
return
<product rank="{$rank}">
{$p/name, $p/sales}
</product>
The result of this query has the following structure:
<product rank="1">
<name>Toaster</name>
<sales>968</sales>
</product>
<product rank="2">
<name>Blender</name>
<sales>520</sales>
</product>
<product rank="3">
<name>Can Opener</name>
<sales>475</sales>
</product>
3.8.7 Group By
Clause
A group by clause generates an output tuple stream
in which each tuple represents a group of tuples from the input
tuple stream. We will refer to the tuples in the input tuple stream
as pre-grouping tuples, and the tuples in the output tuple
stream as post-grouping tuples.
The post-grouping tuples have exactly the same variable-names as
the pre-grouping tuples. The number of post-grouping tuples is less
than or equal to the number of pre-grouping tuples. The group
by clause assigns each pre-grouping tuple to a group, and
generates one post-grouping tuple for each group. Subsequent
clauses in the FLWOR expression see only the variable bindings in
the post-grouping tuples; they no longer have access to the
variable bindings in the pre-grouping tuples.
[Definition: A group by clause
consists of the keywords group by followed by one or
more variables called grouping variables.] The name of each
grouping variable must be equal (by the eq operator on
expanded QNames) to the name of a bound variable in the input tuple
stream; otherwise a static error is raised [err:XQST0094]. The process
of group formation proceeds as follows:
-
[Definition: The atomized value of a grouping
variable is called a grouping key.] For each
pre-grouping tuple, the grouping keys are created by atomizing the values of
the grouping variables. If the resulting
value for any grouping variable consists of more than
one item, a dynamic error is raised [err:XQDY0095].
-
The input tuple stream is partitioned into groups of tuples
whose grouping
keys are equivalent. Two tuples T1 and
T2 are in the same group if and only if, for each
grouping
variable GV, the atomized value of GV in
T1 is equivalent to the atomized value of
GV in T2. For this purpose, equivalence
of two atomic values V1 and V2 is defined by the
following rules:
-
If V1 and V2 are both empty sequences, they
are equivalent.
-
If V1 and V2 are both NaN, they
are equivalent.
-
If the pertinent GroupingSpec specifies a collation
C, and V1 and V2 are both convertible to
the type xs:string by subtype substitution and/or
type
promotion, then:
If fn:compare(V1, V2, C) returns zero, V1
and V2 are equivalent; otherwise they are not
equivalent.
If the collation C is specified by a relative URI, that
relative URI is resolved to an absolute URI using the base URI in the static context. If
the specified collation is not found in statically known collations, a
static error is
raised [err:XQST0076].
-
If none of the above rules apply, then:
If V1 eq V2 is true, V1
and V2 are equivalent; otherwise they are not
equivalent.
Note:
If V1 and V2 are not comparable by the
eq operator, no error is raised. In this case,
V1 and V2 are not equivalent, and the
tuples having these grouping keys are in separate groups.
Each group of tuples produced by the above process results in
one post-grouping tuple. The pre-grouping tuples from which the
group is derived have equivalent grouping keys, but these keys are not
necessarily identical (for example, the strings "Frog" and "frog"
might be equivalent according to the collation in use.) In
the post-grouping tuple, each grouping variable is bound to the value
of one of the original grouping variables. The choice of which
grouping
variable is chosen is implementation-dependent.
| Editorial
note |
|
| Some members of the
XQuery Working Group would prefer that the grouping variables in
the post-grouping tuple contain the grouping key for a grouping
variable in a pre-grouping tuple, which is atomized, rather than
the value of the grouping variable in a pre-grouping tuple. We
welcome feedback on this question. |
In the post-grouping tuple generated for a given group, each
non-grouping variable is bound to a sequence containing the
concatenated values of that variable in all the pre-grouping tuples
that were assigned to that group. If ordering mode is ordered, the
values derived from individual tuples are concatenated in a way
that preserves the order of the pre-grouping tuple stream;
otherwise the ordering of these values is implementation-dependent.
Note:
In general, the static type of a variable in a post-grouping
tuple is different from the static type of the variable with the same
name in the pre-grouping tuples.
The order in which tuples appear in the post-grouping tuple
stream is implementation-dependent.
Note:
An order by clause can be used to impose a
value-based ordering on the post-grouping tuple stream. Similarly,
if it is desired to impose a value-based ordering within a group
(i.e., on the sequence of items bound to a non-grouping variable),
this can be accomplished by a nested FLWOR expression that iterates
over these items and applies an order by clause. In
some cases, a value-based ordering within groups can be
accomplished by applying an order by clause on a
non-grouping variable before applying the group by
clause.
A group by clause rebinds all the variables in the
input tuple stream. The scopes of these variables are not affected
by the group by clause, but in post-grouping tuples
the values of the variables represent group properties rather than
properties of individual pre-grouping tuples.
Examples:
-
This example and the ones that follow are based on two separate
sequences of elements, named $sales and
$products. We assume that the variable
$sales is bound to a sequence of elements with the
following structure:
<sales>
<storeno>S101</storeno>
<itemno>P78395</itemno>
<qty>125</qty>
</sales>
We also assume that the variable $products is bound
to a sequence of elements with the following structure:
<product>
<itemno>P78395</itemno>
<price>25.00</price>
<category>Men's Wear</category>
</product>
The simplest kind of grouping query has a single grouping
variable. The query in this example finds the total quantity of
items sold by each store:
for $s in $sales
let $storeno := $s/storeno
group by $storeno
return <store number="{$storeno}" total-qty="{sum($s/qty)}"/>
The result of this query is a sequence of elements with the
following structure:
<store number="S101" total-qty="1550" />
<store number="S102" total-qty="2125" />
-
In a more realistic example, a user might be interested in the
total revenue generated by each store for each product category.
Revenue depends on both the quantity sold of various items and the
price of each item. The following query joins the two input
sequences and groups the resulting tuples by two grouping
variables:
for $s in $sales,
$p in $products[itemno = $s/itemno]
let $storeno := $s/storeno,
$category := $p/category,
$revenue := $s/qty * $p/price
group by $storeno, $category
return
<summary storeno="{$storeno}"
category="{$category}"
revenue="{sum($revenue)}"/>
The result of this query is a sequence of elements with the
following structure:
<summary storeno="S101" category="Men's Wear" revenue="10185"/>
<summary storeno="S101" category="Stationery" revenue="4520"/>
<summary storeno="S102" category="Men's Wear" revenue="9750"/>
<summary storeno="S102" category="Appliances" revenue="22650"/>
<summary storeno="S102" category="Jewelry" revenue="30750"/>
-
The result of the previous example was a "flat" list of
elements. A user might prefer the query result to be presented in
the form of a hierarchical report, grouped primarily by store (in
order by store number) and secondarily by product category. Within
each store, the user might want to see only those product
categories whose total revenue exceeds $10,000, presented in
descending order by their total revenue. This report is generated
by the following query:
for $s1 in $sales
let $storeno := $s1/storeno
group by $storeno
order by $storeno
return
<store storeno="{$storeno}">
{for $s2 in $s1,
$p in $products[itemno = $s2/itemno]
let $category := $p/category,
$revenue := $s2/qty * $p/price
group by $category
let $group-revenue := sum($revenue)
where $group-revenue > 10000
order by $group-revenue descending
return <category name="{$category}" revenue="{$group-revenue}"/>
}
</store>
The result of this example query has the following
structure:
<store storeno="S101">
<category name="Men's Wear" revenue="10185"/>
</store>
<store storeno="S102">
<category name="Jewelry" revenue="30750"/>
<category name="Appliances" revenue="22650"/>
</store>
-
When writing a query that includes a group by
clause, it is important to remember that, in each post-grouping
tuple, each grouping variable is bound to a single
atomic value (a grouping key), and all other variables are
bound to sequences of items derived from all the pre-grouping
tuples from which the group was formed. The following example
illustrates how to avoid a possible pitfall in writing grouping
queries.
let $high-price := 1000
for $p in $products[price > $high-price]
let $category := $p/category
group by $category
return
<category name="{$category}">
{fn:count($p)} products have price greater than {$high-price}.
</category>
If three products in the "Men's Wear" category have prices
greater than 1000, the result of this query might look (in part)
like this:
<category name="Men's Wear">
3 products have price greater than 1000 1000 1000.
</category>
The repetition of "1000" in this query result is due to the fact
that $high-price is not a grouping variable. One way to
avoid this repetition is to move the binding of
$high-price to an outer-level FLWOR expression, as
follows:
let $high-price := 1000
return
for $p in $products[price > $high-price]
let $category := $p/category
group by $category
return
<category name="{$category}">
{fn:count($p)} products have price greater than {$high-price}.
</category>
The result of the revised query might contain the following
element:
<category name="Men's Wear">
3 products have price greater than 1000.
</category>
3.8.8
Order By Clause
The purpose of an order by clause is to impose a
value-based ordering on the tuples in the tuple stream. The output
tuple stream of the order by clause contains the same
tuples as its input tuple stream, but the tuples may be in a
different order.
An order by clause contains one or more ordering
specifications, called orderspecs, as shown in the grammar.
For each tuple in the input tuple stream, the orderspecs are
evaluated, using the variable bindings in that tuple. The relative
order of two tuples is determined by comparing the values of their
orderspecs, working from left to right until a pair of unequal
values is encountered. If an orderspec specifies a collation, that collation is
used in comparing values of type xs:string,
xs:anyURI, or types derived from them (otherwise, the
default
collation is used in comparing values of these types). If an
orderspec specifies a collation by a relative URI, that relative
URI is resolved to an absolute URI using the base URI in the static context. If an orderspec
specifies a collation that is not found in statically known collations, an error
is raised [err:XQST0076].
The process of evaluating and comparing the orderspecs is based
on the following rules:
-
Atomization is
applied to the result of the expression in each orderspec. If the
result of atomization is neither a single atomic value nor an empty
sequence, a type
error is raised [err:XPTY0004].
-
If the value of an orderspec has the dynamic type
xs:untypedAtomic (such as character data in a
schemaless document), it is cast to the type
xs:string.
Note:
Consistently treating untyped values as strings enables the
sorting process to begin without complete knowledge of the types of
all the values to be sorted.
-
All the non-empty orderspec values must be convertible to a
common type by subtype substitution and/or
type
promotion. The ordering is performed in the least common type
that has a gt operator. If two or more non-empty
orderspec values are not convertible to a common type that has a
gt operator, a type error is raised [err:XPTY0004].
-
Example: The orderspec values include a value of type
hatsize, which is derived from
xs:integer, and a value of type shoesize,
which is derived from xs:decimal. The least common
type reachable by subtype substitution and type promotion is
xs:decimal.
-
Example: The orderspec values include a value of type
xs:string and a value of type xs:anyURI.
The least common type reachable by subtype substitution and type
promotion is xs:string.
For the purpose of determining their relative position in the
ordering sequence, the greater-than relationship between
two orderspec values W and V is defined as
follows:
-
When the orderspec specifies empty least, the
following rules are applied in order:
-
If V is an empty sequence and W is not an
empty sequence, then W greater-than V is
true.
-
If V is NaN and W is neither
NaN nor an empty sequence, then W
greater-than V is true.
-
If a specific collation C is specified, and V
and W are both of type xs:string or are
convertible to xs:string by subtype
substitution and/or type promotion, then:
If fn:compare(V, W, C) is less than zero, then
W greater-than V is true; otherwise
W greater-than V is false.
-
If none of the above rules apply, then:
If W gt V is true, then W
greater-than V is true; otherwise W
greater-than V is false.
-
When the orderspec specifies empty greatest, the
following rules are applied in order:
-
If W is an empty sequence and V is not an
empty sequence, then W greater-than V is
true.
-
If W is NaN and V is neither
NaN nor an empty sequence, then W
greater-than V is true.
-
If a specific collation C is specified, and V
and W are both of type xs:string or are
convertible to xs:string by subtype
substitution and/or type promotion, then:
If fn:compare(V, W, C) is less than zero, then
W greater-than V is true; otherwise
W greater-than V is false.
-
If none of the above rules apply, then:
If W gt V is true, then W
greater-than V is true; otherwise W
greater-than V is false.
-
When the orderspec specifies neither empty least
nor empty greatest, the default order for empty sequences in
the static
context determines whether the rules for empty
least or empty greatest are used.
If T1 and T2 are two tuples in the input tuple
stream, and V1 and V2 are the first pair of
values encountered when evaluating their orderspecs from left to
right for which one value is greater-than the other (as
defined above), then:
-
If V1 is greater-than V2: If the
orderspec specifies descending, then T1
precedes T2 in the output tuple stream; otherwise,
T2 precedes T1 in the output tuple stream.
-
If V2 is greater-than V1: If the
orderspec specifies descending, then T2
precedes T1 in the output tuple stream; otherwise,
T1 precedes T2 in the output tuple stream.
If neither V1 nor V2 is greater-than
the other for any pair of orderspecs for tuples T1 and
T2, the following rules apply.
-
If stable is specified, the original order of
T1 and T2 is preserved in the output tuple
stream.
-
If stable is not specified, the order of
T1 and T2 in the output tuple stream is implementation-dependent.
Note:
If two orderspecs return the special floating-point values
positive and negative zero, neither of these values is
greater-than the other, since +0.0 gt -0.0
and -0.0 gt +0.0 are both false.
Examples:
-
This example illustrates the effect of an order by
clause on a tuple stream. The keyword stable indicates
that, when two tuples have equal sort keys, their order in the
input tuple stream is preserved.
Input tuple stream:
($license = "PFQ519", $make = "Ford", $value = 16500)
($license = "HAJ865", $make = "Honda", $value = 22750)
($license = "NKV473", $make = "Ford", $value = 21650)
($license = "RCM922", $make = "Dodge", $value = 11400)
($license = "ZBX240", $make = "Ford", $value = 16500)
($license = "KLM030", $make = "Dodge", $value = () )
order by clause:
stable order by $make,
$value descending empty least
Output tuple stream:
($license = "RCM922", $make = "Dodge", $value = 11400)
($license = "KLM030", $make = "Dodge", $value = () )
($license = "NKV473", $make = "Ford", $value = 21650)
($license = "PFQ519", $make = "Ford", $value = 16500)
($license = "ZBX240", $make = "Ford", $value = 16500)
($license = "HAJ865", $make = "Honda", $value = 22750)
-
The following example shows how an order by clause
can be used to sort the result of a query, even if the sort key is
not included in the query result. This query returns employee names
in descending order by salary, without returning the actual
salaries:
for $e in $employees
order by $e/salary descending
return $e/name
Note:
Since the order by clause in a FLWOR expression is
the only facility provided by XQuery for specifying a value
ordering, a FLWOR expression must be used in some queries where
iteration would not otherwise be necessary. For example, a list of
books with price less than 100 might be obtained by a simple
path
expression such as $books/book[price < 100].
But if these books are to be returned in alphabetic order by title,
the query must be expressed as follows:
for $b in $books/book[price < 100]
order by $b/title
return $b
3.8.9
Return Clause
The return clause is the final clause of a FLWOR
expression. The return clause is evaluated once for
each tuple in its input tuple stream, using the variable bindings
in the respective tuples, in the order in which these tuples appear
in the input tuple stream. The results of these evaluations are
concatenated, as if by the comma operator, to form the result of the
FLWOR expression.
The following example illustrates a FLWOR expression containing
several clauses. The for clause iterates over all the
departments in an input document named depts.xml,
binding the variable $d to each department in turn.
For each binding of $d, the let clause
binds variable $e to all the employees in the given
department, selected from another input document named
emps.xml (the relationship between employees and
departments is represented by matching their deptno
values). Each tuple in the resulting tuple stream contains a pair
of bindings for $d and $e
($d is bound to a department and $e is
bound to a set of employees in that department). The
where clause filters the tuple stream, retaining only
those tuples that represent departments having at least ten
employees. The order by clause orders the surviving
tuples in descending order by the average salary of the employees
in the department. The return clause constructs a new
big-dept element for each surviving tuple, containing
the department number, headcount, and average salary.
for $d in fn:doc("depts.xml")//dept
let $e := fn:doc("emps.xml")//emp[deptno eq $d/deptno]
where fn:count($e) >= 10
order by fn:avg($e/salary) descending
return
<big-dept>
{
$d/deptno,
<headcount>{fn:count($e)}</headcount>,
<avgsal>{fn:avg($e/salary)}</avgsal>
}
</big-dept>
Notes:
-
The order in which items appear in the result of a FLWOR
expression depends on the ordering of the input tuple stream to the
return clause, which in turn is influenced by
order by clauses and by ordering mode. For example, consider the
following query, which is based on the same two input documents as
the previous example:
for $d in fn:doc("depts.xml")//dept
order by $d/deptno
for $e in fn:doc("emps.xml")//emp[deptno eq $d/deptno]
return
<assignment>
{$d/deptno, $e/name}
</assignment
The result of this query is a sequence of
assignment elements, each containing a
deptno element and a name element. The
sequence will be ordered primarily by the deptno
values because of the order by clause. If ordering mode is
ordered, subsequences of assignment
elements with equal deptno values will be ordered by
the document order of their name elements within the
emps.xml document; otherwise the ordering of these
subsequences will be implementation-dependent.
-
Parentheses are helpful in return clauses that
contain comma operators, since FLWOR expressions have a higher
precedence than the comma operator. For example, the following
query raises an error because after the comma, $j is
no longer within the FLWOR expression, and is an undefined
variable:
let $i := 5,
$j := 20 * $i
return $i, $j
Parentheses can be used to bring $j into the
return clause of the FLWOR expression, as the
programmer probably intended:
let $i := 5,
$j := 20 * $i
return ($i, $j)
3.9 Ordered and Unordered
Expressions
| [114] |
OrderedExpr |
::= |
"ordered" "{" Expr
"}" |
| [115] |
UnorderedExpr |
::= |
"unordered" "{" Expr
"}" |
The purpose of ordered and unordered
expressions is to set the ordering mode in the static context to
ordered or unordered for a certain region
in a query. The specified ordering mode applies to the expression
nested inside the curly braces. For expressions where the ordering
of the result is not significant, a performance advantage may be
realized by setting the ordering mode to unordered,
thereby granting the system flexibility to return the result in the
order that it finds most efficient.
Ordering
mode affects the behavior of path expressions that include a
"/" or "//" operator or an axis step; union,
intersect, and except expressions; the
fn:id and fn:idref functions; and certain
clauses within a FLWOR expression. If ordering mode is
ordered, node sequences returned by path expressions,
union, intersect, and except
expressions, and the fn:id and fn:idref
functions are in document order; otherwise the order of
these return sequences is implementation-dependent. The
effect of ordering mode on FLWOR expressions is described in
3.8.2 For Clause,
3.8.4.3 Effects of
Window Clauses on the Tuple Stream, and 3.8.7 Group By Clause. Ordering mode has
no effect on duplicate elimination.
Note:
In a region of a query where ordering mode is
unordered, the result of an expression may be
nondeterministic if the expression invokes certain functions that
are affected by the ordering of node sequences. These functions
include fn:position, fn:last,
fn:index-of, fn:insert-before,
fn:remove, fn:reverse, and
fn:subsequence. Also, within a path expression in
an unordered region, numeric predicates are
nondeterministic. For example, in an ordered region, the path
expression (//a/b)[5] will return the fifth qualifying
b-element in document order. In an unordered region,
the same expression will return an implementation-dependent
qualifying b-element.
Note:
The fn:id and fn:idref functions are
described in [XQuery 1.0 and XPath
2.0 Functions and Operators] as returning their results in
document
order. Since ordering mode is a feature of XQuery, relaxation
of the ordering requirement for function results when ordering mode
is unordered is a feature of XQuery rather than of the
functions themselves.
The use of an unordered expression is illustrated
by the following example, which joins together two documents named
parts.xml and suppliers.xml. The example
returns the part numbers of red parts, paired with the supplier
numbers of suppliers who supply these parts. If an
unordered expression were not used, the resulting list
of (part number, supplier number) pairs would be required to have
an ordering that is controlled primarily by the document order of
parts.xml and secondarily by the document order of
suppliers.xml. However, this might not be the most
efficient way to process the query if the ordering of the result is
not important. An XQuery implementation might be able to process
the query more efficiently by using an index to find the red parts,
or by using suppliers.xml rather than
parts.xml to control the primary ordering of the
result. The unordered expression gives the query
evaluator freedom to make these kinds of optimizations.
unordered {
for $p in fn:doc("parts.xml")/parts/part[color = "Red"],
$s in fn:doc("suppliers.xml")/suppliers/supplier
where $p/suppno = $s/suppno
return
<ps>
{ $p/partno, $s/suppno }
</ps>
}
In addition to ordered and unordered
expressions, XQuery provides a function named
fn:unordered that operates on any sequence of items
and returns the same sequence in a nondeterministic order. A call
to the fn:unordered function may be thought of as
giving permission for the argument expression to be materialized in
whatever order the system finds most efficient. The
fn:unordered function relaxes ordering only for the
sequence that is its immediate operand, whereas an
unordered expression sets the ordering mode for its operand
expression and all nested expressions.
