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 codepoint.] 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 and XPath
Functions and Operators 1.1]. 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.12 Quantified
Expressions), and typeswitch expressions
(3.14.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
| [129] |
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
| [130] |
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 and XPath Functions and Operators
1.1].] 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 and XPath Functions and Operators
1.1].
-
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).
[Definition: 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 the expected type is a TypedFunctionTest (possibly
with an occurrence indicator *, +, or
?), function item coercion is applied
to each function item in the given value.
-
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.1.5.1 Function Item Coercion
Function item coercion is a transformation applied to function
itemsDM11 during application of the
function conversion rules. [Definition: Function item
coercion wraps a function
itemDM11 in a new inline function with
signature the same as the expected type. This effectively delays
the checking of the argument and return types until the function
item is invoked.]
Function item coercion is only defined to operate on function
itemsDM11. Given a function item,
$function, function item coercion returns a new
function item with the following properties (as defined in Section
2.7 Function ItemsDM11):
-
An empty set of variable values.
-
The name of $function.
-
A function
signatureDM11 equal to the expected
type for the function argument or return type.
-
A new function, whose result is calculated by invoking
$function with the arguments that were specified at
the new function's invocation.
If the result of invoking the new function item would
necessarily result in a type error, that error may be raised during
function coercion. It is implementation dependent whether this
happens or not.
These rules have the following consequences:
-
SequenceType matching of the function item's arguments and
result are delayed until that function item is invoked.
-
The function conversion rules applied to the function item's
arguments and result are defined by the SequenceType it has most
recently been coerced to. Additional function conversion rules
could apply when the wrapped function item is invoked.
-
If an implementation has static type information about a
function item, that can be used to type check the function item's
argument and return types during static analysis.
For instance, consider the following query:
declare function local:filter($s as item()*, $p as function(xs:string) as xs:boolean) as item()*
{
$s[$p(.)]
};
let $f := function($a) { starts-with($a, "E") }
return
local:filter(("Ethel", "Enid", "Gertrude"), $f)
The function item $f has a static type of
function(item()*) as item()*. When the
local:filter() function is called, the following
occurs to the function item:
-
The function conversion rules result in applying function
coercion to $function, wrapping $f in a new inline
function ($p) with the signature function(xs:string) as
xs:boolean.
-
$p is matched against the SequenceType of
function(xs:string) as xs:boolean, and succeeds.
-
When $p is invoked inside the predicate, function conversion and
SequenceType matching rules are applied to the context item
argument, resulting in a xs:string value or a type
error.
-
$f is invoked with the xs:string, which returns a
xs:boolean.
-
$p applies function conversion rules to the result sequence from
$f, which already matches its declared return type of
xs:boolean.
-
The xs:boolean is returned as the result of $p.
Note:
Although the semantics of function item coercion are specified
in terms of wrapping the function items, static typing will often
be able to reduce the number of places where this is actually
necessary.
3.1.6 Literal Function Items
[Definition: A literal function
item creates a function
itemDM11 that represents a named function.]
[Definition: A named function is a
function defined in the static context for the query. To uniquely
identify a particular named function, both its name as a QName and
its arity are required.]
If the QName in the literal function item has no namespace
prefix, it is considered to be in the default function
namespace.
If the expanded QName and arity in a literal function item do
not match the name and arity of a function signature in the static
context, a static error is raised [err:XPST0017].
The result of a literal function item is a single function item
with the following properties (as defined in Section
2.7 Function ItemsDM11):
-
An empty set of variable values.
-
The name specified in the literal function item.
-
The function
signatureDM11 of the function from
the static context that matches the name and arity given.
-
The function from the static context that matches the name and
arity given.
Certain functions in the [XQuery
and XPath Functions and Operators 1.1] specification are
defined to be polymorphic. These are denoted as accepting
parameters of "numeric" type, or returning "numeric" type. Here
"numeric" is a pseudonym for the four primitive numeric types
xs:decimal, xs:integer, xs:float, and xs:double. The functions in
question are:
-
fn:abs()
-
fn:ceiling()
-
fn:floor()
-
fn:round()
-
fn:round-half-to-even()
For the purposes of literal function items, these functions are
regarded as taking arguments and producing results of type
xs:anyAtomicType, with a type error raised at runtime if the
argument value provided is not of the correct numeric type.
Note:
The above way of modeling polymorphic functions is semantically
backwards compatible with XQuery 1.0. An implementation that
supports static typing can choose to model the types of these
functions more accurately if desired.
The following are examples of some literal function item
expressions:
-
fn:abs#1 references the fn:abs function which takes
a single argument.
-
fn:concat#5 references the fn:concat function which
takes 5 arguments.
-
local:myfunc#2 references a function named
local:myfunc which takes 2 arguments.
3.1.7 Inline
Functions
[Definition: An inline function
expression creates a function
itemDM11 that represents an anonymous
function defined directly in the inline function expression
itself.] An inline function specifies the names and SequenceTypes
of the parameters to the function, the SequenceType of the result,
and the body of the function.
If a function parameter is declared using a name but no type,
its default type is item()*. If the result type is omitted from a
function declaration, its default result type is item()*.
The parameters of a function declaration are considered to be
variables whose scope is the function body. It is a static error
[err:XQST0039] for
a function declaration to have more than one parameter with the
same name.
The static context for the function body is inherited from the
location of the inline function expression, with the exception of
the static type of the context item which is initially
undefined.
The variables in scope for the function body include all
variables representing the function parameters, as well as all
variables that are in scope for the inline function expression.
Note:
Function parameter names can mask variables that would otherwise
be in scope for the function body.
The result of an inline function is a single function item with
the following properties (as defined in Section
2.7 Function ItemsDM11):
-
The set of variable values for any variables referenced by the
inline function's body.
-
An absent name.
-
The function
signatureDM11 of the inline
function.
-
The inline function itself.
The following are examples of some inline functions:
-
This example creates an inline function that takes no arguments
and returns a sequence of the first 6 primes:
function() as xs:integer+ { 2, 3, 5, 7, 11, 13 }
-
This example creates an inline function that takes two xs:double
arguments and returns their product:
function($a as xs:double, $b as xs:double) as xs:double { $a * $b }
-
This example creates an inline function that returns its item()*
argument:
-
This example creates an inline function that returns the
xs:integer value 7, i.e.: the value of the variable $a from the
scope of the inline function expression:
let $a := 7
return
let $f := function() { $a }
return
let $a := 8
return $f()
3.1.8
Dynamic Function Invocation
[Definition: A dynamic function
invocation invokesDM11
a function
itemDM11, calling the function it
represents.] A dynamic function invocation consists of an
expression that returns the function item and a parenthesized list
of zero or more arguments.
If the function item expression does not return a sequence
consisting of a single function item with the same arity as the
number of specified arguments, a type error is raised [err:XPTY0004].
A dynamic function invocation is evaluated as follows:
-
Argument values are calculated for the function item using rules
1 and 2 for evaluation of a function call as defined in 3.1.5 Function Calls.
-
The set of variable values from the function item's closure are
added to the dynamic context with a scope of the invocation of the
function.
-
The function from the function item is evaluated using the
argument values according to rules 3 -
5 for evaluation of a function call as defined in 3.1.5 Function Calls.
Note:
These rules are derived from the rules for function calls
defined in 3.1.5 Function
Calls except for the addition of a rule to deal with the
use of the variable values from the closure.
The following are examples of some dynamic function
invocations:
-
This example invokes the function item contained in $f, passing
the arguments 2 and 3:
-
This example fetches the second item from sequence $f, treats it
as a function item and invokes it, passing a xs:string
argument:
-
This example invokes the function item $f passing no arguments,
and filters the result with a positional predicate:
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 non-nodes, 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 non-node, 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 non-nodes.
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
| [113] |
ForwardAxis |
::= |
("child" "::")
| ("descendant" "::")
| ("attribute" "::")
| ("self" "::")
| ("descendant-or-self" "::")
| ("following-sibling" "::")
| ("following" "::") |
| [116] |
ReverseAxis |
::= |
("parent" "::")
| ("ancestor" "::")
| ("preceding-sibling" "::")
| ("preceding" "::")
| ("ancestor-or-self" "::") |
XQuery supports the following axes:
-
The child axis contains the children of the context
node, which are the nodes returned by the dm:children
accessor in [XQuery and XPath Data
Model (XDM) 1.1].
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 and XPath Data Model (XDM) 1.1],
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 and XPath Data Model (XDM) 1.1];
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
[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
| [114] |
AbbrevForwardStep |
::= |
"@"? NodeTest |
| [117] |
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].
If an IntersectExceptExpr contains more than two
InstanceofExprs, they are grouped from left to right. With a
UnionExpr, it makes no difference how operands are grouped, the
results are the same.
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 and XPath Functions and Operators
1.1] 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.)
If an AdditiveExpr contains more than two MultiplicativeExprs,
they are grouped from left to right. So, for instance,
is equivalent to
Similarly, the operands of a MultiplicativeExpr are grouped from
left to right.
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 and XPath Functions and Operators
1.1].
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 and XPath Functions and Operators
1.1], $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)
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.
| [88] |
ComparisonExpr |
::= |
RangeExpr (
(ValueComp
| GeneralComp
| NodeComp) RangeExpr )? |
| [101] |
ValueComp |
::= |
"eq" | "ne" | "lt" | "le" | "gt" | "ge" |
| [100] |
GeneralComp |
::= |
"=" | "!=" | "<" | "<=" | ">" |
">=" |
| [102] |
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 and XPath Functions and Operators
1.1].
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 both atomic values are instances of
xs:untypedAtomic, then the values are cast to the type
xs:string.
-
If exactly one of the atomic values is an instance of
xs:untypedAtomic, it is cast to a type depending on
the other value's dynamic type T according to the following rules,
in which V denotes the value to be cast:
-
If T is a numeric type or is derived from a numeric type, then V
is cast to xs:double.
-
If T is xs:dayTimeDuration or is derived from
xs:dayTimeDuration, then V is cast to
xs:dayTimeDuration.
-
If T is xs:yearMonthDuration or is derived from
xs:yearMonthDuration, then V is cast to
xs:yearMonthDuration.
-
In all other cases, V is cast to the primitive base type of
T.
Note:
The special treatment of the duration types is required to avoid
errors that may arise when comparing the primitive type
xs:duration with any duration type.
-
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 and XPath Data Model (XDM)
1.1] 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 and XPath Data Model (XDM)
1.1]. 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 and XPath Data
Model (XDM) 1.1]. 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, with
the following exceptions:
-
Each occurrence of two consecutive { characters is
replaced by a single { character.
-
Each occurrence of two consecutive } characters is
replaced by a single } character.
-
Each occurrence of two consecutive " characters is
replaced by a single " character.
-
Each occurrence of two consecutive ' characters is
replaced by a single ' character.
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. All the namespace declaration attributes of a
given element must have distinct names [err:XQST0071]. Each namespace declaration
attribute is processed as follows:
-
The value of the namespace declaration attribute (a DirAttributeValue) is
processed as follows. If the DirAttributeValue contains an
EnclosedExpr, a static
error is raised [err:XQST0022]. Otherwise, it is processed as
described in rule 1 of 3.7.1.1
Attributes. An implementation MAY raise a static error
[err:XQST0046] if
the resulting value is of nonzero length and is not in the lexical
space of xs:anyURI. The resulting value is used as the
namespace URI in the following rules.
-
If the prefix of the attribute name is xmlns, then
the local part of the attribute name is interpreted as a namespace
prefix. This prefix and the namespace 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, then the namespace 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 attempts to do any of the following:
-
Bind the prefix xml to some namespace URI other
than http://www.w3.org/XML/1998/namespace.
-
Bind a prefix other than xml to the namespace URI
http://www.w3.org/XML/1998/namespace.
-
Bind the prefix xmlns to any namespace URI.
-
Bind a prefix to the namespace URI
http://www.w3.org/2000/xmlns/.
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:
-
If an enclosed expression returns a function
itemDM11, a type error is raised
[err:XQTY0105].
-
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].
A static
error is raised [ERROR 0044 NOT FOUND] if the node-name of the
constructed element node has any of the following properties:
-
Its namespace prefix is xmlns.
-
It has no namespace prefix and its local name is
xmlns.
-
Its namespace URI is
http://www.w3.org/2000/xmlns/.
-
Its namespace prefix is xml and its namespace URI
is not http://www.w3.org/XML/1998/namespace.
-
Its namespace prefix is other than xml and its
namespace URI is
http://www.w3.org/XML/1998/namespace.
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
| [153] |
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].
A static
error is raised [ERROR 0044 NOT FOUND] if the node-name of the
constructed attribute node has any of the following properties:
-
Its namespace prefix is xmlns.
-
It has no namespace prefix and its local name is
xmlns.
-
Its namespace URI is
http://www.w3.org/2000/xmlns/.
-
Its namespace prefix is xml and its namespace URI
is not http://www.w3.org/XML/1998/namespace.
-
Its namespace prefix is other than xml and its
namespace URI is
http://www.w3.org/XML/1998/namespace.
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
| [150] |
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
| [158] |
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
| [160] |
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
| [159] |
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 namespace 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 is 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 which 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.
Example:
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 whether allowing empty
is specified. If allowing empty is specified, the
output tuple stream consists of one tuple in which the variable is
bound to an empty sequence. If allowing empty 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
allowing empty 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:
for $x allowing empty at $i in ()
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 whether allowing empty is specified.
If allowing empty 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
allowing empty 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
allowing empty 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 allowing empty. Note that allowing
empty 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 allowing empty 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.)
for $y allowing empty 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
| [60] |
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].
[Definition: Equivalence
of two atomic values V1 and V2 is defined by
the following equivalence 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.
|
]
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.
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:
This behavior may be surprising to SQL programmers, since SQL
reduces the equivalent of a non-grouping variable to one
representative value. Consider the following query:
let $x := 64000
for $c in //customer
let $d := $c/department
where $c/salary > $x
group by $d
return
<department name="{$d}">
Number of employees earning more than ${$x} is {count($c)}
</department>
If there are three qualifying customers in the sales department
this evaluates to:
<department name="sales">
Number of employees earning more than $64000 64000 64000 is 3
</department>
In XQuery, each group is a sequence of items that match the
group by criteria—in a tree-structured language like XQuery, this
is convenient, because further structures can be built based on the
items in this sequence. Because there are three items in the group,
$x evaluates to a sequence of three items. To reduce
this to one item, use fn:distinct-values():
let $x := 64000
for $c in //customer
let $d := $c/department
where $c/salary > $x
group by $d
return
<depa
