XQuery 4.0: An XML Query Language

4.6.1 Absolute Path Expressions

The expression consisting of / on its own is treated as an abbreviation for the path expression/..

An expression of the form /PP (that is, a path expression with a leading /) is treated as an abbreviation for the expression self::gnode()/(fn:root(.) treat as (document-node()|jnode())/PP. The effect of this expansion is that for every item J in the context value V:

1. A type error occurs if J is not a GNode [err:XPTY0020].

2. The root GNode R of the GTree containing J is selected.

3. A type error occurs if R is neither a JNode nor a document node [err:XPDY0050].

4. The expression that follows the leading / is evaluated with R as the context value.

The results of these multiple evaluations are then combined into a single sequence; if the result is a set of GNodes, the GNodes are delivered in document order with duplicates eliminated.

An expression of the form //PP (that is, an absolute path expression with a leading //) is treated as an abbreviation for the expression self::gnode()/(fn:root(.) treat as (document-node()|jnode())/descendant-or-self::gnode()/PP. The effect of this expansion is that for every item J in the context value V:

1. A type error occurs if J is not a GNode [err:XPTY0020].

2. The root GNode R of the GTree containing J is selected.

3. A type error occurs if R is neither a JNode nor a document node [err:XPDY0050].

4. The descendants of R are selected, along with R itself.

5. For every GNode D in this set of GNodes, the expression that follows the leading // is evaluated with D as the context value.

The results of these multiple evaluations are then combined into a single sequence; if the result is a set of GNodes, the GNodes are delivered in document order with duplicates eliminated.

Any map or array that is present in the context value is first coerced to a JNode by applying the JNode function.Any map or array that is present in the context value is first coerced to a JNode by applying the fn:jtree function.Any map or array that is present in the context value is first coerced to a JNode by applying the JNodefn:jtree function.

If (after this coercion) the context value is not a sequence of GNodes, a type error is raised [err:XPTY0020]. At evaluation time, if the root GNode of any item in the context value is not a document node or a JNode, a type error is raised [err:XPDY0050].

4.6.3 Path operator (/)

The path operator / is primarily used for locating GNodes within GTrees. The value of the left-hand operand may include maps and arrays; such items are implicitly converted to JNodes as if by a call on the jnode function. After this conversion, the left-hand operand must return a sequence of GNodes. The result of the operator is either a sequence of GNodes (in document order, with no duplicates), or a sequence of non-GNodes.The path operator / is primarily used for locating GNodes within GTrees. The value of the left-hand operand may include maps and arrays; such items are implicitly converted to JNodes as if by a call on the fn:jtree function. After this conversion, the left-hand operand must return a sequence of GNodes. The result of the operator is either a sequence of GNodes (in document order, with no duplicates), or a sequence of non-GNodes.The path operator / is primarily used for locating GNodes within GTrees. The value of the left-hand operand may include maps and arrays; such items are implicitly converted to JNodes as if by a call on the jnodefn:jtree function. After this conversion, the left-hand operand must return a sequence of GNodes. The result of the operator is either a sequence of GNodes (in document order, with no duplicates), or a sequence of non-GNodes.

The operation E1/E2 is evaluated as follows: Expression E₁ is evaluated. Any maps or arrays in the result are converted to JNodes by applying the JNode function. If the result is not a (possibly empty) sequence S of GNodes, a type error is raised [err:XPTY0019]. Each GNode in S then serves in turn to provide an inner focus (the GNode as the context value, its position in S as the context position, the length of S as the context size) for an evaluation of E₂, as described in 2.2.2 Dynamic Context. The sequences resulting from all the evaluations of E₂ are combined as follows:The operation E1/E2 is evaluated as follows: Expression E₁ is evaluated. Any maps or arrays in the result are converted to JNodes by applying the fn:jtree function. If the result is not a (possibly empty) sequence S of GNodes, a type error is raised [err:XPTY0019]. Each GNode in S then serves in turn to provide an inner focus (the GNode as the context value, its position in S as the context position, the length of S as the context size) for an evaluation of E₂, as described in 2.2.2 Dynamic Context. The sequences resulting from all the evaluations of E₂ are combined as follows:The operation E1/E2 is evaluated as follows: Expression E₁ is evaluated. Any maps or arrays in the result are converted to JNodes by applying the JNodefn:jtree function. If the result is not a (possibly empty) sequence S of GNodes, a type error is raised [err:XPTY0019]. Each GNode in S then serves in turn to provide an inner focus (the GNode as the context value, its position in S as the context position, the length of S as the context size) for an evaluation of E₂, as described in 2.2.2 Dynamic Context. The sequences resulting from all the evaluations of E₂ are combined as follows:

1. If every evaluation of E₂ returns a (possibly empty) sequence of GNodes, these sequences are combined, and duplicate GNodes are eliminated based on GNode identity. The resulting GNode sequence is returned in document order.

2. If every evaluation of E₂ returns a (possibly empty) sequence of non-GNodes, these sequences are concatenated, in order, and returned. The returned sequence preserves the orderings within and among the subsequences generated by the evaluations of E₂.

   Note:

   The use of path expressions to select values other than GNodes is for backwards compatibility. Generally it is preferable to use the simple mapping operator ! for this purpose. For example, write $nodes!node-name() in preference to $nodes/node-name().

3. If the multiple evaluations of E₂ return at least one GNode and at least one non-GNode, a type error is raised [err:XPTY0018].

let $R := E1 ! E2
return if (every $r in $R satisfies $r instance of gnode())
       then (fn:distinct-ordered-nodes($R))
       else if (every $r in $R satisfies not($r instance of gnode()))
       then $R
       else error()

4.6.4 Axis Steps

[Definition: An axis step is an instance of the production AxisStep: it is an expression that returns a sequence of GNodes that are reachable from a starting GNode via a specified axis. An axis step has three parts: an axis, which defines the direction of movement for the step, a node test, which selects GNodes based on their properties, and zero or more predicates which are used to filter the results.]

If the context value for an axis step includes a map or array, this is implicitly converted to a JNode as if by applying the fn:jnode function. If, after this conversion, the sequence contains a value that is not a GNode, a type error is raised [err:XPTY0020]. The result of evaluating the axis step is a sequence of zero or more GNodes.If the context value for an axis step includes a map or array, this is implicitly converted to a JNode as if by applying the fn:jtree function. If, after this conversion, the sequence contains a value that is not a GNode, a type error is raised [err:XPTY0020]. The result of evaluating the axis step is a sequence of zero or more GNodes.If the context value for an axis step includes a map or array, this is implicitly converted to a JNode as if by applying the fn:jnodefn:jtree function. If, after this conversion, the sequence contains a value that is not a GNode, a type error is raised [err:XPTY0020]. The result of evaluating the axis step is a sequence of zero or more GNodes.

The axis stepS is equivalent to ./S. Thus, if the context value is a sequence containing multiple GNodes, the semantics of a axis step are equivalent to a path expression in which the step is always applied to a single GNode. The following description therefore explains the semantics for the case where the context value is a single GNode, called the origin.

In the abbreviated syntax for a step, the axis can be omitted and other shorthand notations can be used as described in 4.6.7 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 GNodes reachable from the origin via the specified axis that match the node test. For example, the step child::para selects the para element children of the origin XNode: 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 4.6.4.1 Axes. The available node tests are described in 4.6.4.2 Node Tests. Examples of steps are provided in 4.6.6 Unabbreviated Syntax and 4.6.7 Abbreviated Syntax.

4.6.5 Predicates within Steps

A predicate within an AxisStep has similar syntax and semantics to a predicate within a filter expression. The only difference is in the way the context position is set for evaluation of the predicate.

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.

More formally:

• For a step using a forwards axis, such as child::test[P], the result is the same as for the equivalent filter expression(child::test)[P] (note the parentheses). The same applies if there are multiple predicates, for example child::test[P1][P2][P3] is equivalent to (child::test)[P1][P2][P3].

• For a step using a reverse axis, such as ancestor::test[P], the result is the same as the expression reverse(ancestor::test)[P] => reverse(). The same applies if there are multiple predicates, for example ancestor::test[P1][P2][P3] is equivalent to reverse(ancestor::test)[P1][P2][P3] => reverse().

<doc><a/><b/><c/><d/><e/><f/></doc>

Here are some examples of axis steps that contain predicates to select XNodes:

• This example selects the second chapter element that is a child of the context node:

  child::chapter[2]

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

• This example selects the innermost div ancestor of the context node:

  ancestor::div[1]

• This example selects the outermost div ancestor of the context node:

  ancestor::div[last()]

• This example selects the names of all the ancestor elements of the context node that have an @id attribute, outermost element first:

  ancestor::*[@id]

When the context value for evaluation of a step includes multiple GNodes, the step is evaluated separately for each of those GNodes, and the results are combined, eliminating duplicates and sorting into document order.

4.7.3 Combining GNode Sequences

XQuery 4.0 provides the following operators for combining sequences of GNodes:

• The union and | operators are equivalent. They take two node sequences as operands and return a sequence containing all the GNodes that occur in either of the operands.

• The intersect operator takes two GNodes sequences as operands and returns a sequence containing all the GNodes that occur in both operands.

• The except operator takes two node sequences as operands and returns a sequence containing all the GNodes that occur in the first operand but not in the second operand.

All these operators eliminate duplicate GNodes from their result sequences based on GNode identity. The resulting sequence is returned in document order.

If an operand of union, intersect, or except contains an item that is not a GNode, a type error is raised [err:XPTY0004].

If an IntersectExceptExpr contains more than two InstanceofExpr operands, they are evaluated from left to right. With a UnionExpr, it makes no difference how operands are grouped, the results are the same.

The following example demonstrates the use of the except operator with JNodes:

let $m := jtree($map)
for $e in $m/child::* except $m/child::xx 
return ...

In addition to the sequence operators described here, see [Functions and Operators 4.0] section 2 Processing sequences for functions defined on sequences.

4.14.3 Lookup Expressions

The operator "?", known as the lookup operator, returns values found in the operand map or array.