XQuery 1.0: An XML Query Language

2.1 Basics

The basic building block of XQuery is the expression. The language provides several kinds of expressions which may be constructed from keywords, symbols, and operands. In general, the operands of an expression are other expressions. XQuery is a functional language which allows various kinds of expressions to be nested with full generality. It is also a strongly-typed language in which the operands of various expressions, operators, and functions must conform to designated types.

Like XML, XQuery is a case-sensitive language. All keywords in XQuery use lower-case characters.

The value of an expression is either a sequence or the error value. A sequence is an ordered collection of zero or more items. An item is either an atomic value or a node. An atomic value is a value in the value space of an XML Schema atomic type, as defined in [XML Schema] (that is, a simple type that is not a list type or a union type). A node conforms to one of the seven node kinds described in [XQuery 1.0 and XPath 2.0 Data Model]. Some kinds of nodes have typed values, string values, and names, which can be extracted from the node. The typed value of a node is a sequence of zero or more atomic values. The string value of a node is a value of type xs:string. The name of a node is a value of type xs:QName.

Error is a special value indicating that an error has been encountered during the evaluation of an expression. Except as noted in this document, if any operand of an expression is the error value, the value of the expression is also the error value.

A sequence containing exactly one item is called a singleton sequence. An item is identical to a singleton sequence containing that item. Sequences are never nested--for example, combining the values 1, (2, 3), and ( ) into a single sequence results in the sequence (1, 2, 3). A sequence containing zero items is called an empty sequence.

In this document, the namespace prefixes xs: and xsi: are considered to be bound to the XML Schema namespaces http://www.w3.org/2001/XMLSchema and http://www.w3.org/2001/XMLSchema-instance, respectively (as described in [XML Schema]), and the prefix xf: is considered to be bound to the namespace of XPath/XQuery functions and operators, http://www.w3.org/2002/04/xquery-operators (described in [XQuery 1.0 and XPath 2.0 Functions and Operators]). In some cases, where the meaning is clear and namespaces are not important to the discussion, built-in XML Schema typenames such as integer and string will be used without a namespace prefix.

2.2 Primary Expressions

Primary expressions are the basic primitives of the language. They include literals, variables, function calls, and the use of parentheses to control precedence of operators. The use of qualifiers in primary expressions is discussed in 2.3.2 Qualifiers.

2.3 Path Expressions

A path expression locates nodes within a tree, and returns a sequence of distinct nodes in document order. A path expression is always evaluated with respect to an evaluation context. There are two kinds of path expressions: relative path expressions and rooted path expressions.

A relative path expression consists of two expressions, separated by / or //. This section describes the meaning of /; the use of // is described in 2.3.4 Abbreviated Syntax.

We will refer to the expression on the left side of / as E1 and the expression on the right side of / as E2. The expression E1 is evaluated, and if the result is not a sequence of nodes, the error value is returned. 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.1.2 Evaluation Context. Each evaluation of E2 must result in a sequence of nodes; otherwise, the error value is returned. The sequences of nodes resulting from all the evaluations of E2 are merged, eliminating duplicate node identities and sorting the results in document order.

As an example of a relative 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.

A rooted path expression consists of / or //, followed by an expression. If the rooted path expression begins with /, the following expression is optional. This section describes the meaning of /; the use of // is described in 2.3.4 Abbreviated Syntax.

A / by itself selects the context document. A / followed by an expression E1 establishes an inner focus in which the context node is set equal to the context document, and the context position and context length are set to 1. The expression E1 is then evaluated. If the value of E1 is a sequence of nodes, the result of the rooted path expression is this sequence of nodes, in document order, after elimination of duplicates based on nodeid. If the value of E1 is not a sequence of nodes, the error value is returned.

2.4 Sequence Expressions

XQuery supports operators to construct and combine sequences. A sequence is an ordered collection of zero or more items. An item may be an atomic value or a node. An item is identical to a sequence of length one containing that item. Sequences are never nested--for example, combining the values 1, (2, 3), and ( ) into a single sequence results in the sequence (1, 2, 3).

2.5 Arithmetic Expressions

XQuery provides arithmetic operators for addition, subtraction, multiplication, division, and modulus, in their usual binary and unary forms.

The binary subtraction operator must be preceded by white space if it follows an NCName, in order to distinguish it from a hyphen, which is a valid name character. For example, a-b will be interpreted as a single token.

An arithmetic expression is evaluated by applying the following rules, in order, until an error is encountered or a value is computed:

1. Atomization is applied to each operand, resulting in a single atomic value or an empty sequence for each operand.

2. If either operand is an empty sequence, the result of the operation is an empty sequence.

3. If an operand has the type xs:anySimpleType, it is cast to xs:double. If the cast fails, the error value is returned.

4. If the two operands have different types, and these types can be promoted to a common type using the promotion rules in B.1 Type Promotion, the operands are both promoted to their least common type. For example, if the first operand is of type hatsize which is derived from xs:decimal, and the second operand is of type shoesize which is derived from xs:integer, then both operands are promoted to the type xs:decimal.

5. If the operand type(s) are valid for the given operator, the operator is applied to the operand(s), resulting in an atomic value or an 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. If the operand type(s) are not valid for the given operator, a type exception is raised.

Here are some examples of arithmetic expressions:

• In general, arithmetic operations on numeric values result in numeric values:

  ($salary + $bonus) div 12

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

  -($bellcost + $whistlecost)

2.6 Comparison Expressions

Comparison expressions allow two values to be compared. XQuery provides four kinds of comparison expressions, called value comparisons, general comparisons, node comparisons, and order comparisons.

The "<" comparison operator must be followed by white space in order to distinguish it from a tag-open character. [Ed. Note: This rule may be relaxed, pending resolution of some general grammar issues.]

2.7 Logical Expressions

A logical expression is either an and-expression or an or-expression. In the absence of errors, the value of a logical expression is always one of the boolean values true or false.

The first step in evaluating a logical expression is to reduce each of its operands to an effective boolean value, which is true, false, or the error value. The effective boolean value of an operand is defined as follows:

1. If the operand is an empty sequence, its effective boolean value is false.

2. If the operand is an atomic value of type xs:boolean, the operand serves as its own effective boolean value.

3. If the operand is a sequence that contains at least one node and does not contain any item that is not a node, its effective boolean value is true. [Ed. Note: This rule is pending approval by the XSLT Working Group.]

4. In any other case, a type exception is raised. In XQuery, a type exception always results in the error value.

The value of an and-expression is determined by the effective boolean values (EBV's) of its operands, according to the following table:

The value of an or-expression is determined by the effective boolean values (EBV's) of its operands, according to the following table:

The order in which the operands of a logical expression are evaluated is implementation-dependent. The tables above are defined in such a way that an or-expression can return true if the first expression evaluated is true, and it can return the error value if the first expression evaluated contains an error. Similarly, an and-expression can return false if the first expression evaluated is false, and it can return the error value if the first expression evaluated contains an error. As a result of these rules, the value of a logical expression is not deterministic in the presence of errors, as illustrated in the examples below.

Here are some examples of logical expressions:

• The following expressions return true:

  1 = 1 and 2 = 2

  1 = 1 or 2 = 3

• The following expression may return either false or the error value:

  1 = 2 and 3 div 0 = 47

• The following expression may return either true or the error value:

  1 = 1 or 3 div 0 = 47

• The following expression returns the error value:

  1 = 1 and 3 div 0 = 47

In addition to and- and or-expressions, XQuery provides a function named not that takes a general sequence as parameter and returns a boolean value. The not function reduces its parameter to an effective boolean value using the same rules that are used for the operands of logical expressions. It then returns true if the effective boolean value of its parameter is false, and false if the effective boolean value of its parameter is true. If the effective boolean value of its operand is the error value, not returns the error value. The not function is described in [XQuery 1.0 and XPath 2.0 Functions and Operators].

Ed. Note: Functions named and3, or3, and not3 may be provided to implement three-valued logic. See Issue 28.

2.8 Constructors

XQuery provides constructors that can create XML structures within a query. There are constructors for elements, attributes, CDATA sections, processing instructions, and comments. A special form of constructor called a computed element or attribute constructor can be used to create an element or attribute with a computed name.

<book isbn="isbn-0060229357">
    <title>Harold and the Purple Crayon</title>
    <author>
        <first>Crockett</first>
        <last>Johnson</last>
    </author>
</book>

<example>
   <p> Here is a query. </p>
   <eg> $i//title </eg>
   <p> Here is the result of the above query. </p>
   <eg>{ $i//title }</eg>
</example>

<example>
  <p> Here is a query. </p>
  <eg> $i//title </eg>
  <p> Here is the result of the above query. </p>
  <eg><title>Harold and the Purple Crayon</title></eg>
</example>

<book isbn="{$i/@booknum}" />

element book 
{
    attribute isbn { "isbn-0060229357" },
    element author 
    {
        element first { "Crockett" },
        element last { "Johnson" }
    }
} 

<entry word="address">
   <variant lang="German">Adresse</variant>
   <variant lang="Italian">indirizzo</variant>
</entry> 

<address>123 Roosevelt Ave. Flushing, NY 11368</address>

  element 
    {cast as xs:Qname
       (data($dict/entry[word=name($e)]/variant[lang="Italian"]))}
    {$e/node()}

<indirizzo>123 Roosevelt Ave. Flushing, NY 11368</indirizzo>

<?format role="output" ?>
<!-- Tags are ignored in the following section -->
<![CDATA[ 
    <address>123 Roosevelt Ave. Flushing, NY 11368</address>
]]>

{-- This is an XQuery comment --}
<!-- This is an XML comment -->

<!-- This is an XML comment -->

2.9 FLWR Expressions

XQuery provides a FLWR expression for iteration and for binding variables to intermediate results. This kind of expression is often useful for computing joins between two or more documents and for restructuring data. The name "FLWR", pronounced "flower", stands for the keywords for, let, where, and return, the four clauses found in a FLWR expression.

The clauses of a FLWR Expression are interpreted as follows:

1. A for clause associates one or more variables with expressions, creating tuples of variable bindings drawn from the Cartesian product of the sequences of values to which the expressions evaluate. The variable binding tuples are generated as an ordered sequence as described below.

2. A let clause binds a variable directly to an entire expression. If for clauses are present, the variable bindings created by let clauses are added to the tuples generated by the for clauses. If there are no for clauses, the let clauses generate one tuple with all variable bindings.

3. A where clause can be used as a filter for the tuples of variable bindings generated by the for and let clauses. 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 and its variable bindings are used in an execution of the return clause. If the effective boolean value of the where-expression is false, the tuple is discarded. The effective boolean value of an expression is defined in 2.7 Logical Expressions.

4. The return clause contains an expression that is used to construct the result of the FLWR expression. The return clause is invoked once for every tuple generated by the for and let clauses, after eliminating any tuples that do not satisfy the conditions of a where clause. The expression in the return clause is evaluated once for every invocation, and the result of the FLWR expression is an ordered sequence containing the results of these invocations.

A variable name may not be used before it is bound, nor may it be used in the expression to which it is bound. Any variable bound in a for or let clause is in scope until the end of the FLWR expression in which it is bound. If the variable name used in the binding was already bound in the current scope, the variable name refers to the newly bound variable until that variable goes out of scope. At this point, the variable name again refers to the variable of the prior binding.

Although for and let both bind variables, the manner in which variables are bound is quite different. In a let clause, the variable is bound directly to the expression, and it is bound to the expression as a whole. Consider the following query:

let $s := (<one/>, <two/>, <three/>)
return <out>{$s}</out>

The variable $s is bound to the expression (<one/>, <two/>, <three/>). There are no for clauses, so the let clause generates one tuple that contains the variable binding of $s. The return clause is invoked for this tuple, creating the following output:

<out>
   <one/>
   <two/>
   <three/>
</out>

Now consider a similar query which contains a for clause instead of a let clause:

for $s in (<one/>, <two/>, <three/>)
return <out>{$s}</out>

The variable $s is associated with the expression (<one/>, <two/>, <three/>), from which the variable bindings of $s will be drawn. When only one expression is present, the Cartesian product is equivalent to the sequence of values returned by that expression. In this example, the variable $s is bound three times; first it is bound to <one/>, then to <two/>, and finally to <three/>. One tuple is generated for each of these variable bindings, and the return clause is invoked for each tuple, creating the following output:

<out>
   <one/>
</out>
<out>
   <two/>
</out>
<out>
   <three/>
</out>

A FLWR Expression may contain multiple for clauses. In this case, the tuples of variable bindings are drawn from the Cartesian product of the sequences returned by the expressions in all the for clauses. The ordering of the tuples is governed by the ordering of the sequences from which they were formed, working from left to right.

The following expression illustrates how tuples are generated from the Cartesian product of expressions in a for clause:

for $i in (1, 2),
    $j in (3, 4)
return
    <tuple>
      <i>{ $i }</i>
      <j>{ $j }</j>
    </tuple>

Here is the result of the above expression (the order is significant).

<tuple>
   <i>1</i>
   <j>3</j>
</tuple>
<tuple>
   <i>1</i>
   <j>4</j>
</tuple>
<tuple>
   <i>2</i>
   <j>3</j>
</tuple>
<tuple>
   <i>2</i>
   <j>4</j>
</tuple>

The unordered function indicates that the order of a sequence is not significant and can be changed during processing of an expression. Using this function in the expressions of a for clause allows an implementation more freedom in optimization, and the resulting queries may be faster. The following query returns the same results as above, but the tuples may occur in any order.

for $i in unordered((1, 2)),
    $j in unordered((3, 4))
return
    <tuple>
      <i>{ $i }</i>
      <j>{ $j }</j>
    </tuple>

The following example inverts a document hierarchy to transform a bibliography into an author list. The bibliography is a list of books in which each book contains a list of authors. The example is based on the following input:

<bib>
  <book>
    <title>TCP/IP Illustrated</title>
    <author>
      W. Stevens
    </author>
    <publisher>Addison-Wesley</publisher>
  </book>
  <book>
    <title>Advanced Programming in the Unix environment</title>
    <author>
      W. Stevens
    </author>
    <publisher>Addison-Wesley</publisher>
  </book>
</bib>

The author list is a list of authors, where each author element contains the name of the author and a list of books written by that author. If an author has written more than one book, that author's name will occur more than once in the bibliography, but we want each author's name to occur only once in the author list. We will remove duplicates using the distinct-values function.

The distinct-values function takes a sequence of nodes or values as input, and returns a sequence in which duplicates have been removed by value. The order of this sequence is not significant. Two elements are considered to have duplicate values if their names, attributes, and normalized content are equal.

The following expression is used to transform the input bibliography into an author list:

<authlist>
 {
   let $input := document("bib.xml")
   for $a in distinct-values($input//author)
   return
     <author>
      {
        <name>
           { $a/text() }
        </name>,
        <books>
         {
           for $b in $input//book
           where $b/author = $a
           return $b/title 
         }
        </books>
      }
     </author>
 }
</authlist>

Here is the result of the above expression.

<authlist>
  <author>
    <name>
      W. Stevens
    </name>
    <books>
      <title>TCP/IP Illustrated</title>
      <title>Advanced Programming in the Unix environment</title>
    </books>
  </author>
</authlist>

2.10 Sorting Expressions

A sorting expression provides a way to control the order of items in a sequence.

The value of the expression on the left side of the sortby keyword is called the input sequence. The items in the input sequence are called input items. The result of the sorting expression is called the output sequence. The output sequence contains all the input items, retaining their original identities (if any), but possibly in a different order.

The expressions on the right side of the sortby keyword are called ordering expressions. For each input item, the ordering expressions are evaluated with an inner focus derived from the input item, as described in 2.1.1.2 Evaluation Context. The input items are then reordered according to the values of their respective ordering expressions. If more than one ordering expression is specified, the leftmost ordering expression controls the primary sort, followed by the remaining ordering expressions from left to right. Each ordering expression can be followed by the keyword ascending or descending, which specifies the direction of the sort (ascending is the default). An ordering expression can also be followed by the optional keywords empty greatest or empty least, which specify the placement of input items whose ordering expression returns the empty sequence.

The process of evaluating and comparing the ordering expressions is based on the following rules:

1. Atomization is applied to the result of each ordering expression, resulting in a single atomic value or an empty sequence for each operand ordering expression.

2. If the result of an ordering expression has the type xs:anySimpleType (such as character data in a schemaless document), it is cast to the type xs:string.

3. Each ordering expression must return values of the same type for all input items, and this type must be a (possibly optional) atomic type for which the gt operator is defined--otherwise, the error value is returned.

4. For the purpose of the following rule:

   1. For any ordering expression in which empty greatest is specified, an ordering value that is an empty sequence is treated as greater than any non-empty ordering value (that is ( ) gt x is true for any non-empty x.)

   2. For any ordering expression in which empty least is specified, an ordering value that is an empty sequence is treated as less than any non-empty ordering value (that is x gt ( ) is true for any non-empty x.)

   3. For any ordering expression in which neither empty greatest nor empty least is specified, an implementation may consistently treat an ordering value that is an empty sequence either as greater than any non-empty ordering value or as less than any non-empty ordering value.

5. If V1 and V2 are the values of an ordering expression for input items I1 and I2 respectively, then:

   1. If the ordering expression is ascending, and if V2 gt V1 is true, then I1 precedes I2 in the output sequence.

   2. If the ordering expression is descending, and if V1 gt V2 is true, then I1 precedes I2 in the output sequence.

   3. If neither V1 gt V2 nor V2 gt V1 is true, and stable is specified, then the input order of I1 and I2 is preserved in output sequence.

   4. If neither V1 gt V2 nor V2 gt V1 is true, and stable is not specified, then the order of I1 and I2 in the output sequence is implementation-defined.

Here are some examples of ordering expressions:

• This example lists all books with price greater than 100, in order by first author; within each group of books with the same first author, the books are ordered by title.

  //book[price > 100] sortby (author[1], title)

• Ordering may be specified at multiple levels of a query result. The following example returns an alphabetic list of publishers. Within each publisher element it returns a list of books, each containing a title and a price, in descending order by price.

  <publisher_list>
     {for $p in distinct-values(document("bib.xml")//publisher)
      return
         <publisher>
            <name> {$p/text()} </name> 
            {for $b in document("bib.xml")//book[publisher = $p]
             return
                <book>
                   {$b/title}
                   {$b/price}
                </book> 
             sortby(price descending)
            }
         </publisher> 
      sortby(name)
     }
  </publisher_list>

(employees sortby (salary))/name

for $e in (employees sortby (salary)) return $e/name

2.11 Conditional Expressions

XQuery supports a conditional expression based on the keywords if, then, and else.

The expression following the if keyword is called the test expression, and the expressions following the then and else keywords are called result expressions.

The first step in processing a conditional expression is to find the effective boolean value of the test expression, as defined in 2.7 Logical Expressions.

The value of a conditional expression is defined as follows: If the effective boolean value of the test expression is true, the value of the first ("then") result expression is returned. If the effective boolean value of the test expression is false, the value of the second ("else") result expression is returned.

Here are some examples of conditional expressions:

• In this example, the test expression is a comparison expression:

  if ($widget1/unit-cost < $widget2/unit-cost) 
    then $widget1
    else $widget2

• In this example, the test expression tests for the existence of an attribute named discounted, independently of its value:

  if ($part/@discounted) 
    then $part/wholesale 
    else $part/retail

2.12 Quantified Expressions

Quantified expressions support existential and universal quantification. The value of a quantified expression is always true or false.

A quantified expression begins with a quantifier, which is the keyword some or every, followed by one or more in-clauses that are used to bind variables, followed by the keyword satisfies and a test expression. Each in-clause associates a variable with an expression that returns a sequence of values. As in the case of a for-clause in a FLWR-expression, the in-clauses generate tuples of variable bindings, using values drawn from the Cartesian product of the sequences returned by the binding expressions. Conceptually, the test expression is evaluated for each tuple of variable bindings. Results depend on the effective boolean values of the test expressions, as defined in 2.7 Logical Expressions. The value of the quantified expression is defined by the following rules:

1. If the quantifier is some, the quantified expression is true if at least one evaluation of the test expression has the effective boolean value true; otherwise the quantified expression is false. This rule implies that, if the in-clauses generate zero binding tuples, the value of the quantified expression is false.

2. If the quantifier is every, the quantified expression is true if every evaluation of the test expression has the effective boolean value true; otherwise the quantified expression is false. This rule implies that, if the in-clauses generate zero binding tuples, the value of the quantified expression is true.

The order in which test expressions are evaluated for the various binding tuples is implementation-defined. If the quantifier is some, an implementation may return true as soon as it finds one binding tuple for which the test expression has an effective Boolean value of true, and it may return an error as soon as it finds one binding tuple for which the test expression returns an error. Similarly, if the quantifier is every, an implementation may return false as soon as it finds one binding tuple for which the test expression has an effective Boolean value of false, and it may return an error as soon as it finds one binding tuple for which the test expression returns an error. As a result of these rules, the value of a quantified expression is not deterministic in the presence of errors, as illustrated in the examples below.

Here are some examples of quantified expressions:

• This expression is true if every part element has a discounted attribute (regardless of the values of these attributes):

  every $part in //part satisfies $part/@discounted

• This expression is true if at least one employee element satisfies the given comparison expression:

  some $emp in //employee satisfies ($emp/bonus > 0.25 * $emp/salary)

• In the following examples, each quantified expression evaluates its test expression over nine tuples of variable bindings, formed from the Cartesian product of the sequences (1, 2, 3) and (2, 3, 4). The expression beginning with some evaluates to true, and the expression beginning with every evaluates to false.

  some $x in (1, 2, 3), $y in (2, 3, 4) satisfies $x + $y = 4
  every $x in (1, 2, 3), $y in (2, 3, 4) satisfies $x + $y = 4

• This quantified expression may return either true or the error value, since its test expression returns true for one variable binding and the error value for another:

  some $x in (1, 2, "cat") satisfies $x * 2 = 4

• This quantified expression may return either false or the error value, since its test expression returns false for one variable binding and the error value for another:

  every $x in (1, 2, "cat") satisfies $x * 2 = 4

2.13 Expressions on Datatypes

SequenceTypes occur explicitly in several kinds of XQuery expressions.

The boolean operator instance of returns true if the value of its first operand matches the type named in its second operand, according to the rules for SequenceType Matching; otherwise it returns false. Examples:

• $x instance of element of type animal

  This example returns true if the value associated with variable $x is an element whose content is a value of the type animal.

• <a>5</a> instance of xs:integer

  This example returns false because the given value is not an integer; instead, it is an element whose value is an integer.

• <a>5</a> instance of element of type xs:integer

  This example returns true because the given value matches the given type according to the rules for SequenceType Matching.

The typeswitch expression chooses one of several expressions to evaluate based on the dynamic type of an input value.

In a typeswitch expression, the typeswitch keyword is followed by an expression enclosed in parentheses, called the operand expression. This is the expression whose type is being tested. The operand expression can be followed by an as clause that defines a variable, called the operand variable, that binds to the value of the operand expression. The remainder of the typeswitch expression consists of one or more case clauses and a default clause.

Each case clause specifies a SequenceType followed by a return expression. The effective case is the first case clause such that the value of the operand expression matches the SequenceType in the case clause, using the rules of SequenceType Matching. The value of the typeswitch expression is the value of the return expression in the effective case. If the value of the operand expression is not a value of any type named in a case clause, the value of the typeswitch expression is the value of the return expression in the default clause.

The return expressions in case and default clauses typically contain references to the operand variable (defined in the as clause). If the operand expression consists of a single variable, it can serve as the operand variable and the as clause can be omitted. The as clause can also be omitted if the return expressions do not contain references to the operand variable.

The following example shows how a typeswitch expression might be used to invoke one of several functions depending on the type of a variable.

typeswitch ($animal)
     case element duck return quack($animal)
     case element dog return woof($animal)
     default return "No sound"

Occasionally it is necessary to convert a value to a specific datatype. For this purpose, XQuery provides a cast expression that creates a new value of a specific type based on an existing value. A cast expression takes two operands: an input expression and a SequenceType, called the target type. The cast expression first performs atomization on its input expression, resulting in a single atomic input value or the empty sequence. If the input value is the empty sequence, the cast expression returns an empty sequence. Otherwise, the cast expression creates a new instance of the target type that is equal to the input value. The type of the input value is called the input type. cast is supported only for certain combinations of input type and target type, as listed below:

• cast is supported for the combinations of input type and target type listed in [XQuery 1.0 and XPath 2.0 Functions and Operators]. For each of these combinations, both the input type and the target type are primitive schema types. For example, a value of type xs:string can be cast into the type xs:decimal.

• A value of a derived atomic type can always be cast into its base type. For example, if the type shoesize is derived by restriction from the type xs:integer, a value of type shoesize can always be cast into the type xs:integer.

For any combination of input type and target type that is not in the above list, a cast expression returns the error value.

If the input value is not in the value space of the target type, the error value is returned. A cast expression also returns the error value if any facet of the target type is not satisfied. For example, cast as xs:integer($x) returns the error value if the value of $x is 4.99 because this value cannot be represented with zero fractional digits.

In addition to cast, XQuery provides type-checking expressions called treat and assert. Each of these expressions takes two operands: an expression and a SequenceType. Unlike cast, however, treat and assert do not change the type or value of their operands. Instead, the purpose of a treat or assert expression is to ensure that its operand has an expected type. Each of these expressions has semantics that are applied during static type-checking, and additional semantics that are applied during expression evaluation. If static type checking is disabled or not supported, only the run-time semantics of treat and assert apply. The semantics of the two expressions are as follows:

Semantics of treat as type1 (expr2):

• During static type checking:

  type1 must be a subtype of the static type of expr2, using the definition of subtype in [XQuery 1.0 Formal Semantics]--otherwise, a static error is raised. The static type of the treat expression is type1. This enables the expression to be used as an argument of a function that requires a parameter of type1.

• During expression evaluation (at "run-time"):

  If expr2 matches type1, using the SequenceType Matching rules in [id-sequencetype], the treat expression returns the value of expr2; otherwise, it returns the error value. If the value of expr2 is returned, its identity is preserved. The treat expression ensures that the value of its expression operand conforms to the expected type at run-time.

• Example:

  treat as element of type USAddress ($myaddress)

  The static type of $myaddress may be element of type Address, a less specific type than element of type USAddress. However, at run-time, the value of $myaddress must match the type element of type USAddress using SequenceType Matching rules; otherwise the error value is returned.

Semantics of assert as type1 (expr2):

• During static type checking:

  The static type of expr2 must be a subtype of type1, using the definition of subtype in [XQuery 1.0 Formal Semantics]--otherwise, a static error is raised. The static type of the assert expression is type1. assert provides a stronger static type guarantee than treat.

• During expression evaluation (at "run-time"):

  If expr2 matches type1, using the SequenceType Matching rules in [id-sequencetype], the assert expression returns the value of expr2; otherwise, it returns the error value. If the value of expr2 is returned, its identity is preserved. If the assert expression has passed static type checking without an error, and expr2 does not return an error, then the assert expression will never return the error value at run-time.

• Example:

  assert as element of type USAddress ($myaddress)

  The static type of $myaddress must be element of type USAddress or one of its proper subtypes, and at run-time, the value of $myaddress must match the type element of type USAddress using SequenceType Matching rules; otherwise the error value is returned.

2.14 Validate Expressions

Ed. Note: Curly braces in this syntax may cause problems if this expression is embedded in XSLT--see Issue 267.)

A validate expression validates its argument with respect to the in-scope schema definitions, using the schema validation process described in [XML Schema]. The argument of a validate expression may be any sequence of elements. Validation replaces element and attribute nodes with new nodes that have their own identity and that contain type annotations and defaults created by the validation process. If a node that has a parent is validated, the parent of the original node will not be the parent of the validated node.

To allow locally declared elements and attributes to be validated, a schema context may optionally be specified. If no context is specified, all top-level names in the material to be validated are treated as global names.

The following example creates and validates a globally-declared person element:

   validate {
      <person>
        <name>
          <first>Elvira</first>
          <last>Fischbein</last>
        </name>
      </person>
   } 

The validate expression invokes the full schema validation process, except that identity constraints, as defined in section 3.11.4 of [XML Schema] Part 1, are not applied. All facets of simple types are checked, and default values are supplied as defined in the XML Schema specification.

Validating an expression is equivalent to the following series of steps:

1. Serialize the value of the expression, using xsi:type attributes to indicate the types of elements that have type annotations or that contain a single atomic value of a known type (however, do not generate an xsi:type attribute for any element that already has such an attribute).

2. Invoke schema validation on the resulting serialized expression, using the in-scope schema definitions.

3. Remove any xsi:type attributes that were generated in Step 1.

A validate expression may contain a SchemaContext that is used in validating locally declared elements and attributes. When a schema context is supplied, all element QNames are interpreted as they would be if found in that context in an XML document. If the schema context begins with a QName, the QName is interpreted as the name of a globally declared element; however, if the schema context begins with the keyword type, the first QName is interpreted as the name of a globally declared type. The steps inside the schema context trace a path relative to the globally declared element or type, as illustrated in the following examples, which are based on schemas defined in [XML Schema], Part 0:

• Suppose that $x is bound to a shipTo element. Then validate in po:purchaseOrder {$x} validates the value of $x in the context of the global element declaration po:purchaseOrder.

• Suppose that $y is bound to an productName element. Then validate in po:purchaseOrder/items/item {$y} validates the value of $y in the context of an item element, inside an items element, inside the global element declaration po:purchaseOrder.

• Suppose that $z is bound to a zip element. Then validate in type po:USAddress {$z} validates the value of $z in the context of the global type declaration po:USAddress.

Under certain circumstances, validation of an element or attribute may result in the loss of some type information. The following examples illustrate some of these circumstances:

• validate { <sizes>{1, 2, 3}</sizes> }

  The constructed <sizes> element node has no type annotation. Its value is a sequence of integers, but "sequence of integers" is not a built-in type that can be represented by an xsi:type attribute.

  The effective serialized value to be validated is <sizes>1 2 3</sizes>. After validation, if no more specific type is found, the value of the <sizes> element will be "1 2 3", an instance of xs:anySimpleType.

• validate { <animal>{ "A cat", "named Oscar" }</animal> }

  The constructed animal element node has no type annotation. Its value was derived from two strings, but the boundaries between the strings will be lost during validation.

  The effective serialized value to be validated is <animal>A cat named Oscar</animal>. If animal is a global element declared to have xs:string as its type, the validated value of the element will consist of a single string. On the other hand, if the declared type of animal is xs:string*, the validated value of the element will consist of the following four strings: "A", "cat", "named", and "Oscar".

• validate { <mixture>{ 1, "2", "three" }</mixture> }

  The constructed <mixture> element node has no type annotation. Its typed value consists of an integer and two strings, but there is no possible schema type that can be assigned to the element node that will preserve this type information.

  The effective serialized value to be validated is <mixture>1 2 three</mixture>. After validation, the value of the <mixture> element might be two integers and a string, or three strings, or one string.

• validate { <shoe size="{7}"/> }

  The constructed size attribute node has no type annotation. Its value is an integer, but there is no way to represent the type of a serialized attribute.

  The effective serialized value to be validated is <shoe size="7"/>. After validation, if no more specific type is found, the value of the size attribute will be "7", an instance of xs:anySimpleType.

3.1 Namespace Declarations and Schema Imports

Ed. Note: The QName in NamespaceDecl should be a NCName. However, there is currently a technical problem with token ambiguity between QName and NCName.

A Namespace Declaration defines a namespace prefix and associates it with a namespace URI, adding the (prefix, URI) pair to the set of in-scope namespaces. The namespace URI must be a valid URI, and may not be an empty string. The namespace declaration is in scope for the rest of the query in which it is declared. Consider the following query:

namespace foo = "http://www.foo.com"
<foo:bar> Lentils </foo:bar> 

In the query result, the newly created node is in the namespace associated with the namespace URI http://www.foo.com.

In element constructors, namespace declaration attributes also associate a namespace with a prefix, adding a (prefix, URI) pair to the set of in-scope namespaces. In the data model, a namespace declaration is not an attribute, and it will not be retrieved by queries that return the attributes of an element. Namespace declarations are in scope within their containing element. Nested elements and attributes inherit the in-scope namespaces of their parents. The following query creates the same result as the previous query.

<foo:bar xmlns:foo="http://www.foo.com"> Lentils </foo:bar>

Because namespace declarations are in-scope within their containing element, they may be used in expressions that occur within an element constructor, as in the following query.

<foo:bar xmlns:foo="http://www.foo.com">{ //foo:bing }</foo:bar>

Names are compared on the basis of the expanded name (see [XML Names] for this and other namespace terms), not the QName. When element or attribute names are compared, they are considered identical if the local part and namespace URI match. Namespace prefixes are disregarded in name comparisons. This is illustrated by the following example:

namespace xx = "http://www.foo.com"

let $i := <foo:bar xmlns:foo = "http://www.foo.com">
              <foo:bing> Lentils </foo:bing>
          </foo:bar>
return $i/xx:bing 

Although the namespace prefixes xx and foo differ, both are bound to the namespace URI "http://www.foo.com". Since xx:bing and foo:bing have the same local name and the same namespace URI, they match. The output of the above query is as follows.

<foo:bing> Lentils </foo:bing>

It is invalid to redefine namespace prefixes using the NamespaceDecl production.

{-- Error: attempt to redefine 'xx' in NamespaceDecl --}

namespace xx = "http://www.foo.com"
namespace xx = "http://www.bar.com"

//xx:bing

It is also invalid to use a QName with a namespace prefix that has not been declared. The following query is also semantically invalid.

{-- Error: use of undeclared namespace prefix --}
//xx:bing 

Namespace declaration attributes may redefine a namespace prefix within a given scope. The following query is valid.

namespace xx = "http://www.fee.com"

<xx:bar xmlns:xx = "http://www.fie.com">
    <xx:bing xmlns:xx = "http://www.fo.com"> One </xx:bing>
    <xx:bing xmlns:xx = "http://www.fum.com"> Two </xx:bing>
    <xx:bing> Three </xx:bing>
</xx:bar> 

The result of the above query is as follows.

<xx:bar xmlns:xx = "http://www.fie.com">
    <xx:bing xmlns:xx = "http://www.fo.com"> One </xx:bing>
    <xx:bing xmlns:xx = "http://www.fum.com"> Two </xx:bing>
    <xx:bing xmlns:xx = "http://www.fie.com"> Three </xx:bing>
</xx:bar> 

Default Namespace Declarations can be used to define namespace URIs to be associated with unprefixed names. The following kinds of default namespace declarations are supported:

• default element namespace defines a namespace URI that is associated with unprefixed names of elements and types.

• default function namespace defines a namespace URI that is associated with unprefixed names of functions.

If no default element namespace is in effect, unqualified names of elements and types are in no namespace. If no default function namespace is in effect, unqualified function names are in no namespace. Unqualified attribute names are always in no namespace, since XQuery provides no way to declare a default namespace for attributes.

The following example illustrates a default element namespace:

default element namespace = "http://www.foo.com"
<bar> Lentils </bar> 

The result of the above query is shown below. Note that the name of the newly created element is in the namespace associated with the namespace URI http://www.foo.com, even though no namespace prefix occurs in the query.

 <bar xmlns = "http://www.foo.com"> Lentils </bar> 

A Schema Import imports the element and attribute declarations and type definitions from a schema, mapping them into the Query Data Model using rules that will be specified in a future edition of [XQuery 1.0 Formal Semantics]. The URI in a schema import specifies the namespace to be imported, and optionally the location of the schema in which the namespace is defined. Importing a schema has no effect on the in-scope namespaces, since it does not associate a prefix with the namespace. When a schema is imported, the query generally accompanies the schema import with appropriate namespace or default namespace declarations to make it possible to refer to the names defined in the schema.

The following query searches for table elements in an XHTML document, after declaring the namespace and schema location for XHTML.

schema "http://www.w3.org/1999/xhtml" 
            at "http:/www.w3.org/1999/xhtml/xhtml.xsd"
namespace xhtml = "http://www.w3.org/1999/xhtml"

document("aspect.xhtml")//xhtml:table 

A shorthand notation is provided to allow a schema to be imported, and a namespace prefix to be bound to the target namespace of the schema, in a single step. This shorthand notation is illustrated by the following example, which is equivalent to the previous example:

schema namespace xhtml="http://www.w3.org/1999/xhtml" 
            at "http:/www.w3.org/1999/xhtml/xhtml.xsd"

document("aspect.xhtml")//xhtml:table 

The shorthand notation includes two URI's: the first one identifies a namespace and the second identifies a schema location. If the given namespace is not the target namespace of the schema at the given location, an error results.

It is an error to import two schemas that both define the same name in the same symbol space and in the same scope. For instance, a query may not import two schemas that provide global element declarations for two elements with the same expanded name.

3.2 Function Definitions

In addition to the built-in functions described in [XQuery 1.0 and XPath 2.0 Functions and Operators], XQuery allows users to define functions of their own. A function definition specifies the name of the function, the names and datatypes of the parameters, and the datatype of the result. All datatypes are specified using the syntax described in 2.1.3.2 SequenceType. A function definition also includes an expression called the function body that defines how the result of the function is computed from its parameters.

The name of a function may be qualified with a namespace. The default namespace for functions is the namespace of the XML Query 1.0 and XPath 2.0 Functions and Operators, so these functions can be used without prefixes. The default namespace for functions may be changed by a default namespace declaration, as in this example:

default function namespace = "www.mylib.com" 

If a function parameter is declared using a name but no type, it accepts arguments of any type. If the returns clause is omitted from a function definition, the function may return a value of any type.

The following example illustrates the definition and use of a function that accepts a sequence of employee elements, summarizes them by department, and returns a sequence of dept elements.

• Using a function, prepare a summary of employees that are located in Denver.

  define function summary(element employee* $emps) 
     returns element dept*
  {
     for $d in distinct-values($emps/deptno)
     let $e := $emps[deptno = $d]
     return
        <dept>
           {$d}
           <headcount> {count($e)} </headcount>
           <payroll> {sum($e/salary)} </payroll>
        </dept>
  }
  
  summary(document("acme_corp.xml")//employee[location = "Denver"])
  

The type of a function parameter or result may be a global type (declared as a top-level typename in some schema) or a local type (declared at some level of nesting inside a schema). Function parameters and results of local type can be declared with the help of a SchemaContext, as in the following example:

define function price(element product in type catalog $p)
  returns element USPrice in type catalog/product
{
   $p/USPrice
}

Rules for converting function arguments to their declared parameter types, and for converting the result of a function to its declared result type, are described in 2.2.4 Function Calls

A function may be defined recursively--that is, it may reference its own definition. Mutually recursive functions, whose bodies reference each other, are also allowed. The following example defines a recursive function that computes the maximum depth of an element hierarchy, and calls the function to find the maximum depth of a particular document. In its definition, the user-defined function depth calls the built-in functions empty and max.

• Find the maximum depth of the document named partlist.xml.

  define function depth(element $e) returns xs:integer
  {
     {-- An empty element has depth 1 --}
     {-- Otherwise, add 1 to max depth of children --}
     if (empty($e/*)) then 1
     else max(for $c in $e/* return depth($c)) + 1
  }
  
  depth(document("partlist.xml"))
  

In XQuery 1.0, user-defined functions may not be overloaded. Only one function definition may have a given name. We consider function overloading to be a useful and important feature that deserves further study in future versions of XQuery. Although XQuery does not allow overloading of user-defined functions, some of the built-in functions in the XQuery core library are overloaded--for example, the string function of XPath can convert an instance of almost any type into a string.

4.1 Filtering

One of the functions in the XQuery core function library is called filter. This function takes a single parameter which can be any expression. The function evaluates its argument and returns a shallow copy of the nodes that are selected by the argument, preserving any relationships that exist among these nodes. For example, suppose that the argument to filter is a path expression that selects nodes X, Y, and Z from some document. Suppose that, in the original document, nodes Y and Z are descendants (at any level) of node X. Then the result of filter is a copy of node X, with copies of nodes Y and Z as its immediate children. Any other intervening nodes from the original document are not present in the result. The name filter suggests a function that operates on a document to extract the parts that are of interest and discard the remainder, while retaining the structure of the original document.

The semantics of filter are illustrated by Figure 1. Suppose that the left side of Figure 1 represents a node hierarchy that is bound to the variable $doc. The right side of Figure 1 shows the result of the function filter($doc//(A | B)). The result contains copies of all nodes of type A and B in the original hierarchy, with their original relationships preserved. Note that the action of the filter function may split a node hierarchy into multiple hierarchies (preserving the sequential relationships among the root nodes of the resulting hierarchies.)

Figure 1: Action of the filter function

The following example illustrates how filter might be used to compute a table of contents for a document that contains many levels of nested sections. The query filters the document, retaining only section elements, title elements nested directly inside section elements, and the text of those title elements. Other elements, such as paragraphs and figure titles, are eliminated, leaving only the "skeleton" of the document. The example generates a table of contents for a document named cookbook.xml.

<toc>
   {
   filter(document("cookbook.xml") //
      (section | section/title | section/title/text()))
   }
</toc>

4.2 Joins

Joins, which combine data from multiple sources into a single result, are a very important type of query. In this section we will illustrate how several types of joins can be expressed in XQuery. We will base our examples on the following three documents:

1. A document named parts.xml that contains many part elements; each part element in turn contains partno and description subelements.

2. A document named suppliers.xml that contains many supplier elements; each supplier element in turn contains suppno and suppname subelements.

3. A document named catalog.xml that contains information about the relationships between suppliers and parts. The catalog document contains many item elements, each of which in turn contains partno, suppno, and price subelements.

A conventional ("inner") join returns information from two or more related sources, as illustrated by the following example, which combines information from three documents. The example generates a "descriptive catalog" derived from the catalog document, but containing part descriptions instead of part numbers and supplier names instead of supplier numbers. The new catalog is ordered alphabetically by part description and secondarily by supplier name.

<descriptive-catalog>
   { 
     for $i in document("catalog.xml")//:item,
         $p in document("parts.xml")//part[partno = $i/partno],
         $s in document("suppliers.xml")//supplier[suppno = $i/suppno]
     return
        <item>
           {
           $p/description,
           $s/suppname,
           $i/price
           }
        </item>
     sortby(description, suppname)
   }
</descriptive-catalog>

The previous query returns information only about parts that have suppliers and suppliers that have parts. An outer join is a join that preserves information from one or more of the participating sources, including elements that have no matching element in the other source. For example, a left outer join between suppliers and parts might return information about suppliers that have no matching parts.

The following query demonstrates a left outer join. It returns names of all the suppliers in alphabetic order, including those that supply no parts. In the result, each supplier element contains the descriptions of all the parts it supplies, in alphabetic order.

for $s in document("suppliers.xml")//supplier
return
   <supplier>
      { 
        $s/suppname,
        for $i in document("catalog.xml")//:item
                 [suppno = $s/suppno],
            $p in document("parts.xml")//part
                 [partno = $i/pno]
        return $p/description 
        sortby(.)
      }
   </supplier>
sortby(suppname)

The previous query preserves information about suppliers that supply no parts. Another type of join, called a full outer join, might be used to preserve information about both suppliers that supply no parts and parts that have no supplier. The result of a full outer join can be structured in any of several ways. The following query generates a list of supplier elements, each containing nested part elements for the parts that it supplies (if any), followed by a list of part elements for the parts that have no supplier. This might be thought of as a "supplier-centered" full outer join. Other forms of outer join queries are also possible.

<master-list>
 {
    for $s in document("suppliers.xml")//supplier
    return
        <supplier>
           { 
             $s/suppname,
             for $i in document("catalog.xml")//:item
                     [suppno = $s/suppno],
                 $p in document("parts.xml")//part
                     [partno = $i/partno]
             return
                <part>
                   {
                     $p/description,
                     $i/price
                   }
                </part> 
             sortby (description)
           }
        </supplier> 
    sortby (suppname) 
    ,
    {-- parts that have no supplier --}
    <orphan-parts>
       { for $p in document("parts.xml")//part
         where empty(document("catalog.xml")//:item
               [partno = $p/partno] )
         return $p/description 
         sortby (.)
       }
    </orphan-parts>
 }
</master-list>

The previous query uses an element constructor to enclose its output inside a master-list element. The concatenation operator (",") is used to combine the two main parts of the query. The result is an ordered sequence of supplier elements followed by an orphan-parts element that contains descriptions of all the parts that have no supplier.

4.3 Grouping

Many queries involve forming data into groups and applying some aggregation function such as count or avg to each group. The following example shows how such a query might be expressed in XQuery, using the catalog document defined in the previous section.

This query finds the part number and average price for parts that have at least 3 suppliers.

for $pn in distinct-values(document("catalog.xml")//partno)
let $i := document("catalog.xml")//:item[partno = $pn]
where count($i) >= 3
return 
   <well-supplied-item>
      {$pn}
      <avgprice> {avg($i/price)} </avgprice>
   </well-supplied-item> 
sortby(partno)

The distinct-values function in this query eliminates duplicate part numbers from the set of all part numbers in the catalog document. The result of distinct-values is a sequence in which order is not significant.

Note that $pn, bound by a for clause, represents an individual part number, whereas $i, bound by a let clause, represents a set of items which serves as argument to the aggregate functions count($i) and avg($i/price). The query uses an element constructor to enclose each part number and average price in a containing element called well-supplied-item.

4.4 Queries on Sequence

XQuery uses the precedes, follows, <<, and >> operators to express conditions based on sequence. Although these operators are quite simple, they can be used to express sophisticated queries for XML documents in which sequence is meaningful. The first two queries in this section involve a surgical report that contains procedure, incision, and anesthesia elements. The following query returns a critical sequence that contains all elements and nodes found between the first and second incisions of the first procedure.

<critical-sequence>
 {
    let $proc := //procedure[1]
    for $n in $proc//node()
    where $n follows ($proc//incision)[1]
      and $n precedes ($proc//incision)[2]
    return $n
 }
</critical-sequence> 

The following query reports incisions for which no prior anesthesia was recorded in the surgical report.

for $p in //procedure
where some $i in $proc//incision satisfies
        empty($proc//anesthesia[. precedes $i])
return $p 

In some documents, particular sequences of elements may indicate a logical hierarchy. This is most commonly true of HTML. The following query returns the introduction of an XHTML document, wrapping it in a div element. In this example, we assume that an h2 element containing the text "Introduction" marks the beginning of the introduction, and the introduction continues until the next h2 or h1 element, or the end of the document, whichever comes first.

let $intro := //h2[text()="Introduction"],
      $next-h := //(h1|h2)[. follows $intro][1]
return
    <div>
      {
        $intro,
        if (empty($next-h))
          then //node()[. follows $intro]
          else //node()[. follows $intro and . precedes $next-h]
      }
    </div> 

Note that the above query also makes explicit the hierarchy that was implicit in the original document.