XQuery 4.0: An XML Query Language

2 Basics

2.3 Processing Model

Changes in 4.0 ⬇ ⬆

The static typing option has been dropped. [Issue 1343 PR 1344 3 September 2024]

The semantics of XQuery 4.0 are defined in terms of the data model and the expression context.

Figure 1: Processing Model Overview

Figure 1 provides a schematic overview of the processing steps that are discussed in detail below. Some of these steps are completely outside the domain of XQuery 4.0; in Figure 1, these are depicted outside the line that represents the boundaries of the language, an area labeled external processing. The external processing domain includes generation of XDM instances that represent the data to be queried (see 2.3.1 Data Model Generation), schema import processing (see 2.3.2 Schema Import Processing), and serialization (see 2.3.5 Serialization). The area inside the boundaries of the language is known as the query processing domain, which includes the static analysis and dynamic evaluation phases (see 2.3.3 Expression Processing). Consistency constraints on the query processing domain are defined in 2.3.6 Consistency Constraints.

2.3.3 Expression Processing

XQuery 4.0 defines two phases of processing called the static analysis phase and the dynamic evaluation phase (see Figure 1). During the static analysis phase, static errors, dynamic errors, or type errors may be raised. During the dynamic evaluation phase, only dynamic errors or type errors may be raised. These kinds of errors are defined in 2.4.1 Kinds of Errors.

Within each phase, an implementation is free to use any strategy or algorithm whose result conforms to the specifications in this document.

2.3.3.2 Dynamic Evaluation Phase

[Definition: The dynamic evaluation phase is the phase during which the value of an expression is computed.] It is dependent on successful completion of the static analysis phase.

The dynamic evaluation phase can occur only if no errors were detected during the static analysis phase.

The dynamic evaluation phase depends on the operation tree of the expression being evaluated (step DQ1), on the input data (step DQ4), and on the dynamic context (step DQ5), which in turn draws information from the external environment (step DQ3) and the static context (step DQ2). The dynamic evaluation phase may create new data-model values (step DQ4) and it may extend the dynamic context (step DQ5)—for example, by binding values to variables.

[Definition: Every value matches one or more sequence types. A value is said to have a dynamic typeT if it matches (or is an instance of) the sequence type T.]

In many cases (but not all), one of the dynamic types that a value matches will be a subtype of all the others, in which case it makes sense to speak of “the dynamic type” of the value as meaning this single most specific type. In other cases (examples are empty maps^emptyDM maps and empty arrays^{empty DMarrays}) none of the dynamic types is more specific than all the others.

Note:

An atomic item has a type annotation which will always be a subtype of all the other types that it matches; we can therefore refer to this as the dynamic type of the atomic item without ambiguity.

A value may match a dynamic type that is more specific than the static type of the expression that computed it (for example, the static type of an expression might be xs:integer*, denoting a sequence of zero or more integers, but at evaluation time its value may be an instance of xs:integer, denoting exactly one integer).

If an operand of an expression does not have a dynamic type that is a subtype of the static type required for that operand, a type error is raised [err:XPTY0004].

Even though static typing can catch many type errors before an expression is executed, it is possible for an expression to raise an error during evaluation that was not detected by static analysis. For example, an expression may contain a cast of a string into an integer, which is statically valid. However, if the actual value of the string at run time cannot be cast into an integer, a dynamic error will result. Similarly, an expression may apply an arithmetic operator to a value whose static type is xs:untypedAtomic. This is not a static error, but at run time, if the value cannot be successfully cast to a numeric type, a dynamic error will be raised.

3 Types

As noted in 2.1.2 Values, every value in XQuery 4.0 is regarded as a sequence of zero, one, or more items. The type system of XQuery 4.0, described in this section, classifies the kinds of value that the language can handle, and the operations permitted on different kinds of value.

The type system of XQuery 4.0 is related to the type system of [XML Schema 1.0] or [XML Schema 1.1] in two ways:

atomic items in XQuery 4.0 (which are one kind of item) have atomic types such as xs:string, xs:boolean, and xs:integer. These types are taken directly from their definitions in [XML Schema 1.0] or [XML Schema 1.1].
Nodes (which are another kind of item) have a property called a type annotation which determines the type of their content. The type annotation is a schema type. The type annotation of a node must not be confused with the item type of the node. For example, an element <age>23</age> might have been validated against a schema that defines this element as having xs:integer content. If this is the case, the type annotation of the node will be xs:integer, and in the XQuery 4.0 type system, the node will match the item typeelement(age, xs:integer).

This chapter of the specification starts by defining sequence types and item types, which describe the range of values that can be bound to variables, used in expressions, or passed to functions. It then describes how these relate to schema types, that is, the simple and complex types defined in an XSD schema.

Note:

In many situations the terms item type and sequence type are used interchangeably to refer either to the type itself, or to the syntactic construct that designates the type: so in the expression $x instance of xs:string*, the construct xs:string* uses the SequenceType syntax to designate a sequence type whose instances are sequences of strings. When more precision is required, the specification is careful to use the terms item type and sequence type to refer to the actual types, while using the production names ItemType and SequenceType to refer to the syntactic designators of these types.

3.2 Item Types

[Definition: An item type is a type that can be expressed using the ItemType syntax, which forms part of the SequenceType syntax. Item types match individual items.]

Note:

While this definition is adequate for the purpose of defining the syntax of XQuery 4.0, it ignores the fact that there are also item types that cannot be expressed using XQuery 4.0 syntax: specifically, item types that reference an anonymous simple type or complex type defined in a schema. Such types can appear as type annotations on nodes following schema validation.

In most cases, the set of items matched by an item type consists either exclusively of atomic items, exclusively of nodes, or exclusively of function items^DM. Exceptions include the generic types item(), which matches all items, xs:error, which matches no items, and choice item types, which can match any combination of types.

[Definition: An item type designator is a syntactic construct conforming to the grammar rule ItemType. An item type designator is said to designate an item type.]

Note:

Two item type designators may designate the same item type. For example, element() and element(*) are equivalent, as are attribute(A) and attribute(A, xs:anySimpleType).

Lexical QNames appearing in an item type designator(other than within a function assertion) have their prefixes expanded to namespace URIs by means of the statically known namespaces and (where applicable) the default namespace for elements and types. Equality of QNames is defined by the eq operator.

`ItemType`	::=	`AnyItemTest \| TypeName \| KindTest \| FunctionType \| MapType \| ArrayType \| RecordType \| EnumerationType \| ChoiceItemType`
`AnyItemTest`	::=	`"item" "(" ")"`
`TypeName`	::=	`EQName`
`EQName`	::=	`QName \| URIQualifiedName`
`KindTest`	::=	`DocumentTest \| ElementTest \| AttributeTest \| SchemaElementTest \| SchemaAttributeTest \| PITest \| CommentTest \| TextTest \| NamespaceNodeTest \| AnyKindTest`
`DocumentTest`	::=	`"document-node" "(" (ElementTest \| SchemaElementTest \| NameTestUnion)? ")"`
`ElementTest`	::=	`"element" "(" (NameTestUnion ("," TypeName "?"?)?)? ")"`
`SchemaElementTest`	::=	`"schema-element" "(" ElementName ")"`
`NameTestUnion`	::=	`(NameTest ++ "\|")`
`NameTest`	::=	`EQName \| Wildcard`
`Wildcard`	::=	`"" \| (NCName ":") \| (":" NCName) \| (BracedURILiteral "")`
		/* ws: explicit */
`AttributeTest`	::=	`"attribute" "(" (NameTestUnion ("," TypeName)?)? ")"`
`SchemaAttributeTest`	::=	`"schema-attribute" "(" AttributeName ")"`
`PITest`	::=	`"processing-instruction" "(" (NCName \| StringLiteral)? ")"`
`StringLiteral`	::=	`AposStringLiteral \| QuotStringLiteral`
		/* ws: explicit */
`CommentTest`	::=	`"comment" "(" ")"`
`TextTest`	::=	`"text" "(" ")"`
`NamespaceNodeTest`	::=	`"namespace-node" "(" ")"`
`AnyKindTest`	::=	`"node" "(" ")"`
`FunctionType`	::=	`Annotation* (AnyFunctionType \| TypedFunctionType)`
`MapType`	::=	`AnyMapType \| TypedMapType`
`ArrayType`	::=	`AnyArrayType \| TypedArrayType`
`RecordType`	::=	`AnyRecordType \| TypedRecordType`
`EnumerationType`	::=	`"enum" "(" (StringLiteral ++ ",") ")"`
`ChoiceItemType`	::=	`"(" (ItemType ++ "\|") ")"`

This section defines the syntax and semantics of different ItemTypes in terms of the values that they match.

Note:

For an explanation of the EBNF grammar notation (and in particular, the operators ++ and **), see A.1 EBNF.

An item type designator written simply as an EQName (that is, a TypeName) is interpreted as follows:

If the name is written as a lexical QName, then it is expanded using the in-scope namespaces in the static context. If the name is an unprefixed NCName, then it is expanded according to the default namespace for elements and types.
If the name matches a named item type in the static context, then it is taken as a reference to the corresponding item type. The rules that apply are the rules for the expanded item type definition.
Otherwise, it must match the name of a type in the in-scope schema types in the static context: specifically, an atomic type or a pure union type. See 3.5 Schema Types for details.
Note:
A name in the xs namespace will always fall into this category, since the namespace is reserved. See 2.1.3 Namespaces and QNames.
If the name cannot be resolved to a type, a static error is raised [err:XPST0051].

3.2.8 Function, Map, and Array Types

The following sections describe the syntax for item types for functions, including arrays and maps.

The subtype relation among these types is described in the various subsections of 3.3.2 Subtypes of Item Types.

3.2.8.3 Record Types

Changes in 4.0 ⬇ ⬆

Record types are added as a new kind of ItemType, constraining the value space of maps.
The syntax record(*) is allowed; it matches any map. [Issue 52 PR 728 10 October 2023]
The syntax record() is allowed; the only thing it matches is an empty map. [Issue 1491 ]

A RecordType matches maps that meet specific criteria.

For example, the RecordTyperecord(r as xs:double, i as xs:double) matches a map if the map has exactly two entries: an entry with key "r" whose value is a singletonxs:double value, and an entry with key "i" whose value is also a singletonxs:double value.

Record types describe a subset of the value space of maps. They do not define any new kinds of values, or any additional operations. They are useful in many cases to describe more accurately the type of a variable, function parameter, or function result, giving benefits both in the readability of the code, and in the ability of the processor to detect and diagnose type errors and to optimize execution.

`RecordType`	::=	`AnyRecordType \| TypedRecordType`
`AnyRecordType`	::=	`"record" "(" "*" ")"`
`TypedRecordType`	::=	`"record" "(" (FieldDeclaration ** ",") ExtensibleFlag? ")"`
`FieldDeclaration`	::=	`FieldName "?"? ("as" SequenceType)?`
`FieldName`	::=	`NCName \| StringLiteral`
`StringLiteral`	::=	`AposStringLiteral \| QuotStringLiteral`
		/* ws: explicit */
`SequenceType`	::=	`("empty-sequence" "(" ")") \| (ItemTypeOccurrenceIndicator?)`
`ExtensibleFlag`	::=	`"," "*"`

If the list of fields ends with ",*" then the record type is said to be extensible. For example, the RecordTyperecord(e as element(Employee), *) matches a map if it has an entry with key "e" whose value matches element(Employee), regardless what other entries the map might contain.

For generality:

The syntax record() defines a record type that has no explicit fields and that is not extensible. The only thing it matches is an empty map^{empty DMmap}.
The syntax record(*) defines an extensible record type that has no explicit field declarations. It is equivalent to the item type map(*): that is, it matches any map.

A record type can constrain only those entries whose keys are strings, but when the record type is marked as extensible, then other entries may be present in the map with either string or non-string keys. Entries whose key is a string can be expressed using an (unquoted) NCName if the key conforms to NCName syntax, or using a (quoted) string literal otherwise.

Although constructors for named record types produce a map in which the entry order^DM reflects the order of field definitions in the record type definition, the entry order^DM of a map has no effect on whether the map matches a particular record type: the entries in a map do not have to be in any particular order.

Note:

Lookup expressions have been extended in 4.0 so that non-NCName keys can be used without parentheses: employee?"middle name"

If the type declaration for a field is omitted, then item()* is assumed: that is, the map entry may have any type.

If the field name is followed by a question mark, then the value must have the specified type if it is present, but it may also be absent. For example, the RecordTyperecord(first as xs:string, middle? as xs:string, last as xs:string, *) requires the map to have string-valued entries with keys "first" and "last"; it also declares that if the map has an entry with key "middle", the value of that entry must be a single xs:string. Declaring the type as record(first as xs:string, middle? as xs:string?, last as xs:string, *) also allows the entry with key "middle" to be present but empty.

Note:

Within an extensible record type, a FieldDeclaration that is marked optional and has no declared type does not constrain the map in any way, so it serves no practical purpose, but it is permitted because it may have documentary value.

The names of the fields in a record type must be distinct [err:XPST0021].

If a variable $rec is known to conform to a particular record type, then when a lookup expression $rec?field is used, (a) the processor can report a type error if $rec cannot contain an entry with name field (see 4.14.3.4 Implausible Lookup Expressions), and (b) the processor can make static type inferences about the type of value returned by $rec?field.

Note:

(TODO: change function signatures as suggested here!) A number of functions in the standard function library use maps as function arguments; this is a useful technique where the information to be supplied across the interface is highly variable. However, the type signature for such functions typically declares the argument type as map(*), which gives very little information (and places very few constraints) on the values that are actually passed across. Using record types offers the possibility of improving this: for example, the options argument of fn:parse-json, previously given as map(*), can now be expressed as record(liberal? as xs:boolean, duplicates? as xs:string, escape? as xs:boolean, fallback as fn(xs:string) as xs:string, *). In principle the xs:string type used to describe the duplicates option could also be replaced by a schema-defined subtype of xs:string that enumerates the permitted values ("reject", "use-first", "use-last").

The use of a record type in the signature of such a function causes the coercion rules to be invoked. So, for example, if the function expects an entry in the map to be an xs:double value, it becomes possible to supply a map in which the corresponding entry has type xs:integer.

Greater precision in defining the types of such arguments also enables better type checking, better diagnostics, better optimization, better documentation, and better syntax-directed editing tools.

Note:

One of the motivations for introducing record types is to enable better pattern matching in XSLT when processing JSON input. With XML input, patterns are often based around XML element names. JSON has no direct equivalent of XML’s element names; matching a JSON object such as {longitude: 130.2, latitude: 53.4} relies instead on recognizing the property names appearing in the object. XSLT 4.0, by integrating record types into pattern matching syntax, allows such an object to be matched with a pattern of the form match="record(longitude, latitude)"

Rules defining whether one record type is a subtype of another are given in 3.3.2.8 Subtyping Records.

3.4 Coercion Rules

Changes in 4.0 ⬇ ⬆

The term "function conversion rules" used in 3.1 has been replaced by the term "coercion rules". [ PR 254 29 November 2022]
The coercion rules allow “relabeling” of a supplied atomic item where the required type is a derived atomic type: for example, it is now permitted to supply the value 3 when calling a function that expects an instance of xs:positiveInteger. [Issue 117 PR 254 29 November 2022]
The coercion rules now allow any numeric type to be implicitly converted to any other, for example an xs:double is accepted where the required type is xs:double. [Issue 980 PR 911 30 January 2024]
The coercion rules now allow conversion in either direction between xs:hexBinary and xs:base64Binary. [Issues 130 480 PR 815 7 November 2023]

[Definition: The coercion rules are rules used to convert a supplied value to a required type, for example when converting an argument of a function call to the declared type of the function parameter. ] The required type is expressed as a sequence type. The effect of the coercion rules may be to accept the value as supplied, to convert it to a value that matches the required type, or to reject it with a type error.

This section defines how the coercion rules operate; the situations in which the rules apply are defined elsewhere, by reference to this section.

Note:

In previous versions of this specification, the coercion rules were referred to as the function conversion rules. The terminology has changed because the rules are not exclusively associated with functions or function calling.

If the required type is empty-sequence(), no coercion takes place (the supplied value must be an empty sequence, or a type error occurs).

In all other cases, the required sequence typeT comprises a required item typeR and an optional occurrence indicator. The coercion rules are then applied to a supplied value V and the required type T as follows:

Each item in V is processed against the required item type R using the item coercion rules defined in 3.4.1 Item Coercion Rules, and the results are sequence-concatenated into a single sequence V′.
A type error is raised if the cardinality of V′ does not match the required cardinality of T [err:XPTY0004].

3.4.2 Implausible Coercions

An expression is deemed to be implausible [err:XPTY0006] if the static type of the expression, after applying all necessary coercions, is substantively disjoint with the required type T.

[Definition: Two sequence types are deemed to be substantively disjoint if (a) neither is a subtype of the other (see 3.3.1 Subtypes of Sequence Types) and (b) the only values that are instances of both types are one or more of the following:

The empty sequence, ().
The empty map, {}.The empty map^DM, {}.The empty map^{empty DMmap}, {}.
The empty array, [].The empty array^DM, [].The empty array^{empty DMarray}, [].

]

Note:

Examples of pairs of sequence types that are substantively disjoint include:

xs:integer* and xs:string*
map(xs:integer, node()) and map(xs:string, node())
array(xs:integer) and array(xs:string)

For example, supplying a value whose static type is xs:integer* when the required type is xs:string* is implausible, because it can succeed only in the special case where the actual value supplied is an empty sequence.

Note:

The case where the supplied type and the required type are completely disjoint (for example map(*) and array(*)) is covered by the general rules for type errors: that case can always be reported as a static error.

Examples of implausible coercions include the following:

round(timezone-from-time($now)). The result of fn:timezone-from-time is of type xs:dayTimeDuration?, which is substantively disjoint with the required type of fn:round, namely xs:numeric?.
function($x as xs:integer) as array(xs:string) { array { 1 to $x } }. The type of the function body is array(xs:integer), which is substantively disjoint with the required type array(xs:string): the function can succeed only in the exceptional case where the function body delivers an empty array^{empty DMarray}.

4 Expressions

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 4.0 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 4.0 Grammar].

[Definition: A query consists of one or more modules.] If a query is executable, one of its modules has a Query Body containing an expression whose value is the result of the query. An expression is represented in the XQuery grammar by the symbol Expr.

`Expr`	::=	`(ExprSingle ++ ",")`
`ExprSingle`	::=	`FLWORExpr \| QuantifiedExpr \| SwitchExpr \| TypeswitchExpr \| IfExpr \| TryCatchExpr \| OrExpr`

`ExprSingle`	::=	`FLWORExpr \| QuantifiedExpr \| SwitchExpr \| TypeswitchExpr \| IfExpr \| TryCatchExpr \| OrExpr`
`FLWORExpr`	::=	`InitialClauseIntermediateClause* ReturnClause`
`QuantifiedExpr`	::=	`("some" \| "every") (QuantifierBinding ++ ",") "satisfies" ExprSingle`
`SwitchExpr`	::=	`"switch" SwitchComparand (SwitchCases \| BracedSwitchCases)`
`TypeswitchExpr`	::=	`"typeswitch" "(" Expr ")" (TypeswitchCases \| BracedTypeswitchCases)`
`IfExpr`	::=	`"if" "(" Expr ")" (UnbracedActions \| BracedAction)`
`TryCatchExpr`	::=	`TryClauseCatchClause+`
`OrExpr`	::=	`AndExpr ("or" AndExpr)*`

The XQuery 4.0 operator that has lowest precedence is the comma operator, which is used to combine two operands to form a sequence. As shown in the grammar, a general expression (Expr) can consist of multiple ExprSingle operands, separated by commas.

The name ExprSingle denotes an expression that does not contain a top-level comma operator (despite its name, an ExprSingle may evaluate to a sequence containing more than one item.)

The symbol ExprSingle is used in various places in the grammar where an expression is not allowed to contain a top-level comma. For example, each of the arguments of a function call must be a ExprSingle, because commas are used to separate the arguments of a function call.

After the comma, the expressions that have next lowest precedence are FLWORExpr,QuantifiedExpr, SwitchExpr, TypeswitchExpr, IfExpr, TryCatchExpr, and OrExpr. Each of these expressions is described in a separate section of this document.

4.13 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 overall syntax of a FLWOR expression is shown here, and relevant parts of the syntax are expanded in subsequent sections.

`FLWORExpr`	::=	`InitialClauseIntermediateClause* ReturnClause`
`InitialClause`	::=	`ForClause \| LetClause \| WindowClause`
`ForClause`	::=	`"for" (ForBinding ++ ",")`
`LetClause`	::=	`"let" (LetBinding ++ ",")`
`WindowClause`	::=	`"for" (TumblingWindowClause \| SlidingWindowClause)`
`IntermediateClause`	::=	`InitialClause \| WhereClause \| WhileClause \| GroupByClause \| OrderByClause \| CountClause`
`WhereClause`	::=	`"where" ExprSingle`
`WhileClause`	::=	`"while" ExprSingle`
`GroupByClause`	::=	`"group" "by" (GroupingSpec ++ ",")`
`OrderByClause`	::=	`"stable"? "order" "by" (OrderSpec ++ ",")`
`CountClause`	::=	`"count" VarName`
`ReturnClause`	::=	`"return" ExprSingle`

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.

Conceptually, the first clause generates a tuple stream. Each clause between the first clause and the return clause takes the tuple stream generated by the previous clause as input and generates a (possibly different) tuple stream as output. The return 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, or window 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.

4.13.2 For Clause

Changes in 4.0 ⬇ ⬆

A for member clause is added to FLWOR expressions to allow iteration over an array. [Issue 49 PR 344 10 February 2023]
A for key/value clause is added to FLWOR expressions to allow iteration over a map. [Issue 31 PR 1249 1 June 2024]
The value bound to a variable in a for clause is now converted to the declared type by applying the coercion rules. [Issue 189 PR 820 8 November 2023]

`ForClause`	::=	`"for" (ForBinding ++ ",")`
`ForBinding`	::=	`ForItemBinding \| ForMemberBinding \| ForEntryBinding`
`ForItemBinding`	::=	`VarNameAndTypeAllowingEmpty? PositionalVar? "in" ExprSingle`
`VarNameAndType`	::=	`"$" EQNameTypeDeclaration?`
`EQName`	::=	`QName \| URIQualifiedName`
`TypeDeclaration`	::=	`"as" SequenceType`
`SequenceType`	::=	`("empty-sequence" "(" ")") \| (ItemTypeOccurrenceIndicator?)`
`AllowingEmpty`	::=	`"allowing" "empty"`
`PositionalVar`	::=	`"at" VarName`
`VarName`	::=	`"$" EQName`
`ExprSingle`	::=	`FLWORExpr \| QuantifiedExpr \| SwitchExpr \| TypeswitchExpr \| IfExpr \| TryCatchExpr \| OrExpr`
`ForMemberBinding`	::=	`"member" VarNameAndTypePositionalVar? "in" ExprSingle`
`ForEntryBinding`	::=	`((ForEntryKeyBindingForEntryValueBinding?) \| ForEntryValueBinding) PositionalVar? "in" ExprSingle`
`ForEntryKeyBinding`	::=	`"key" VarNameAndType`
`ForEntryValueBinding`	::=	`"value" VarNameAndType`

A for clause is used for iteration. Each variable in a for clause iterates over a sequence, an array, or a map.

The expression following the keyword in is evaluated; we refer to the resulting sequence, array, or map generically as the binding collection, and to its items, members, or entries as the components of the collection.

When a ForItemBinding is used (that is, when none of the keywords member, key, or value is used), the range variable is bound in turn to each item in the binding collection, which is treated as a sequence of items.
When a ForMemberBinding is used (that is, when the keyword member is used), the range variable is bound in turn to each member of the array.
In this case the corresponding ExprSingle must evaluate to a single array, otherwise a type error is raised [err:XPTY0141].
When a ForEntryBinding is used (that is, when either or both of the keywords key and value are used), the key range variable (if present) is bound in turn to each key in the map (in entry order^DM), and the value range variable (if present) is bound to the corresponding value.
In this case the corresponding ExprSingle must evaluate to a single map, otherwise a type error is raised [err:XPTY0141].
If both the key and value variables are declared, their expanded QNames must be distinct [err:XQST0089].

If a for clause contains multiple bindings separated by commas it is semantically equivalent to multiple for clauses, each containing one of the bindings in the original for clause.

Example:

The clause

for $x in $expr1, $y in $expr2

is semantically equivalent to:

for $x in $expr1
for $y in $expr2

The clause

for member $x in $expr1, member $y in $expr2

is semantically equivalent to:

for member $x in $expr1
for member $y in $expr2

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 the binding collection for that variable.

If a single-variable for clause is the initial clause in a FLWOR expression, it iterates over its binding collection, binding the variable(s) to each component 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. The order of tuples in the tuple stream preserves the order of the binding collection.

If the binding collection is empty, 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. This option is not available when the keywords member, key, or value are used. 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:

Initial clause:

for $x in (100, 200, 300)

or (equivalently):

for $x allowing empty in (100, 200, 300)

Output tuple stream:

($x = 100)
($x = 200)
($x = 300)

Initial clause:
```
for $x in ()
```
Output tuple stream contains no tuples.
Initial clause:
```
for $x allowing empty in ()
```
Output tuple stream:
```
($x = ())
```

Initial clause:

for member $x in [ 1, 2, (5 to 10) ]

Output tuple stream:

($x = (1))
($x = (2))
($x = (5, 6, 7, 8, 9, 10)

Initial clause:
```
for member $x in []
```
Output tuple stream contains no tuples.

Initial clause:

for key $k value $v in { 'x': 1, 'y': 2 }

Output tuple stream:

($k = 'x', $v = 1)
($k = 'y', $v = 2)

[Definition: A positional variable is a variable that is preceded by the keyword at.] A positional variable may be associated with the range variable(s) that are bound in a for clause. In this case, as the main range variable(s) iterate over the components of its binding collection, the positional variable iterates over the integers that represent the ordinal numbers of these component in the binding collection, starting with one. Each tuple in the output tuple stream contains bindings for both the main variable and the positional variable. If the binding collection is empty and allowing empty is specified, the positional variable in the output tuple is bound to the integer zero. Positional variables 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 at $i in [1 to 3, 11 to 13, 21 to 23

Output tuple stream:

($x = (1, 2, 3), $i = 1)
($x = (11, 12, 13), $i = 2)
($x = (21, 22, 23), $i = 3)

Initial clause:

for $x allowing empty at $i in ()

Output tuple stream:

($x = (), $i = 0)

If a single-variable for clause is an intermediate clause in a FLWOR expression, its binding collection 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 collecction.

Note:

Although the binding collection is conceptually evaluated independently for each input tuple, an optimized implementation may sometimes be able to avoid re-evaluating the binding collection if it can show that the variables that the binding collection depends on have the same values as in a previous evaluation.

For a given input tuple, if the binding collection for the new variable in the for clause is empty (that is, it is an empty sequence or an empty array^emptyDM array depending on whether member is specified), and if allowing empty is not specified, the input tuple generates zero output tuples (it is not represented in the output tuple stream.)

The allowing empty option is available only when processing sequences, not when processing arrays or maps. The effect is that if the binding collection is an empty sequence, the input tuple generates one output tuple, with the original variable bindings plus a binding of the new variable to an empty sequence.

Note:

If a type declaration is present and allowing empty is specified, the type declaration should include an occurrence indicator of "?" to indicate that the variable may be bound to an empty sequence.

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 collection, the positional variable is bound to the ordinal position of that item within the binding collection, starting with one. Note that, since the positional variable represents a position within a binding collection, the output tuples corresponding to each input tuple are independently numbered, starting with one. For a given input tuple, if the binding collection is empty and allowing empty is specified, the positional variable in the output tuple is bound to the integer zero.

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:
```
for $y in ($x to 3)
```
Output tuple stream:
```
($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 collection 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:

($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:
```
($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 illustrates processing of arrays:

Input tuple stream:

($x = 1)
($x = 2)
($x = 3)

Intermediate for clause:

for member $y in [[$x+1, $x+2], [[$x+3, $x+4]]

Output tuple stream:

($x = 1, $y = [ 2, 3 ])
($x = 1, $y = [ 4, 5 ])
($x = 2, $y = [ 3, 4 ])
($x = 2, $y = [ 5, 6 ])
($x = 3, $y = [ 4, 5 ])
($x = 3, $y = [ 6, 7 ])

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:
```
($x = 1, $y = 1)
($x = 1, $y = 2)
($x = 1, $y = 3)
($x = 2, $y = 2)
($x = 2, $y = 3)
($x = 3, $y = 3)
```

A for clause may contain one or more type declarations, identified by the keyword as. The semantics of type declarations are defined in 4.13.1 Variable Bindings.

4.14 Maps and Arrays

Most modern programming languages have support for collections of key/value pairs, which may be called maps, dictionaries, associative arrays, hash tables, keyed lists, or objects (these are not the same thing as objects in object-oriented systems). In XQuery 4.0, we call these maps. Most modern programming languages also support ordered lists of values, which may be called arrays, vectors, or sequences. In XQuery 4.0, we have both sequences and arrays. Unlike sequences, an array is an item, and can appear as an item in a sequence.

Note:

The XQuery 4.0 specification focuses on syntax provided for maps and arrays, especially constructors and lookup.

Some of the functionality typically needed for maps and arrays is provided by functions defined in Section 17 Maps^FO and Section 18 Arrays^FO, including functions used to read JSON to create maps and arrays, serialize maps and arrays to JSON, combine maps to create a new map, remove map entries to create a new map, iterate over the keys of a map, convert an array to create a sequence, combine arrays to form a new array, and iterate over arrays in various ways.

4.14.1 Maps

Changes in 4.0 ⬇ ⬆

Ordered maps are introduced. [Issue 1651 PR 1703 14 January 2025]

[Definition: A map is a function that associates a set of keys with values, resulting in a collection of key / value pairs.] [Definition: Each key / value pair in a map is called an entry.] [Definition: The value associated with a given key is called the associated value of the key.]

Maps and their properties are defined in the data model: see Section 2.9.5 Map Items^DM. For an overview of the functions available for processing maps, see Section 17 Maps^FO.

Note:

Maps in XQuery 4.0 are ordered. The effect of this property is explained in Section 2.9.5 Map Items^DM. In an ordered map, the order of entries is predictable and depends on the order in which they were added to the map.

4.14.1.1 Map Constructors

Changes in 4.0 ⬇ ⬆

In map constructors, the keyword map is now optional, so map { 0: false(), 1: true() } can now be written { 0: false(), 1: true() }, provided it is used in a context where this creates no ambiguity. [Issue 1070 PR 1071 26 March 2024]
The order of key-value pairs in the map constructor is now retained in the constructed map. [Issue 1651 PR 1703 14 January 2025]

A map can be created using a MapConstructor.

`MapConstructor`	::=	`"map"? "{" (MapConstructorEntry ** ",") "}"`
`MapConstructorEntry`	::=	`MapKeyExpr ":" MapValueExpr`
`MapKeyExpr`	::=	`ExprSingle`
`ExprSingle`	::=	`FLWORExpr \| QuantifiedExpr \| SwitchExpr \| TypeswitchExpr \| IfExpr \| TryCatchExpr \| OrExpr`
`MapValueExpr`	::=	`ExprSingle`

Note:

The keyword map was required in earlier versions of the language; in XQuery 4.0 it becomes optional. There may be cases where using the keyword improves readability.

In order to allow the map keyword to be omitted, an incompatible change has been made to XQuery computed element and attribute constructors: if the name of the constructed element or attribute is a language keyword, it must now be written in quotes, for example element "div" {}.

Although the grammar allows a MapConstructor to appear within an EnclosedExpr (that is, between curly brackets), this may be confusing to readers, and using the map keyword in such cases may improve clarity. In any event, if the EnclosedExpr appears in a context such as a StringTemplate, the two adjacent left opening braces must at least be separated by whitespace.

Note:

In some circumstances, it is necessary to include whitespace before or after the colon of a MapConstructorEntry to ensure that it is parsed as intended.

For instance, consider the expression {a:b}. Although it matches the EBNF for MapConstructor (with a matching MapKeyExpr and b matching MapValueExpr), the "longest possible match" rule requires that a:b be parsed as a QName, which results in a syntax error. Changing the expression to {a :b} or {a: b} will prevent this, resulting in the intended parse.

Similarly, consider these three expressions:

{a:b:c}
{a:*:c}
{*:b:c}

In each case, the expression matches the EBNF in two different ways, but the “longest possible match” rule forces the parse in which the MapKeyExpr is a:b, a:*, or *:b (respectively) and the MapValueExpr is c. To achieve the alternative parse (in which the MapKeyExpr is merely a or *), insert whitespace before and/or after the first colon.

See A.3 Lexical structure.

The value of the expression (whether or not the map keyword is present) is a map whose entries correspond to the key-value pairs obtained by evaluating the successive MapKeyExpr and MapValueExpr expressions.

Each MapKeyExpr expression is evaluated and atomized; a type error [err:XPTY0004] occurs if the result is not a single atomic item. The associated value is the result of evaluating the corresponding MapValueExpr. If the MapValueExpr evaluates to a node, the associated value is the node itself, not a new node with the same values. [Definition: Two atomic items K1 and K2 have the same key value if fn:atomic-equal(K1, K2) returns true, as specified in Section 13.2.1 fn:atomic-equal^FO ] If two or more entries have the same key value then a dynamic error is raised [err:XQDY0137]. The error may be raised statically if two or more entries can be determined statically to have the same key value.

The entry order^DM of the entries in the constructed map retains the order of the MapConstructorEntry entries in the input.

Example: Constructing a fixed map

The following expression constructs a map with seven entries:

{
  "Su" : "Sunday",
  "Mo" : "Monday",
  "Tu" : "Tuesday",
  "We" : "Wednesday",
  "Th" : "Thursday",
  "Fr" : "Friday",
  "Sa" : "Saturday"
}

Example: Constructing nested maps

Maps can nest, and can contain any XDM value. Here is an example of a nested map with values that can be string values, numeric values, or arrays:

{
  "book": {
    "title": "Data on the Web",
    "year": 2000,
    "author": [
      {
        "last": "Abiteboul",
        "first": "Serge"
      },
      {
        "last": "Buneman",
        "first": "Peter"
      },
      {
        "last": "Suciu",
        "first": "Dan"
      }
    ],
    "publisher": "Morgan Kaufmann Publishers",
    "price": 39.95
  }
}

Note:

The syntax deliberately mimics JSON, but there are a few differences. JSON constructs that are not accepted in XQuery 4.0 map constructors include the keywords true, false, and null, and backslash-escaped characters such as "\n" in string literals. In an XQuery 4.0 map constructor, of course, any literal value can be replaced with an expression.

Both the keys and the values in a map constructor can be supplied as expressions rather than as constants; the number of entries in the map, however, is fixed. There are several functions that can be used to construct maps with a variable number of entries:

map:build takes any sequence as input, and for each item in the sequence, it computes a key and a value, by calling user-supplied functions.
map:merge takes a sequence of maps (often but not necessarily single-entry map^{single-DMentry maps}) and merges them into a single map.
map:of-pairs takes a sequence of key-value pair maps^FO and merges them into a single map.

Any of these functions can be used to build an index of employee elements using the value of the @id attribute as a key:

map:build(//employee, fn{@id})
map:merge(//employee ! {@id, .})
map:of-pairs(//employee ! {'key':@id, 'value':.})

All three functions also provide control over:

The way in which duplicate keys are handled, and
The ordering of entries in the resulting map.

4.14.3 Lookup Expressions

Changes in 4.0 ⬇ ⬆

The lookup operator ? can now be followed by a string literal, for cases where map keys are strings other than NCNames. It can also be followed by a variable reference.
A deep lookup operator ?? is provided for searching trees of maps and arrays. [Issue 297 PR 837 23 November 2023]
Lookup expressions can now take a modifier (such as keys, values, or pairs) enabling them to return structured results rather than a flattened sequence. [Issues 960 1094 PR 1125 23 April 2024]

XQuery 4.0 provides two lookup operators ? and ?? for maps and arrays. These provide a terse syntax for accessing the entries in a map or the members of an array.

The operator "?", known as the shallow lookup operator, returns values found immediately in the operand map or array. The operator "??", known as the deep lookup operator, also searches nested maps and arrays. The effect of the deep lookup operator "??" is explained in 4.14.3.3 Deep Lookup.

4.14.3.3 Deep Lookup

The deep lookup operator ?? has both unary and postfix forms. The unary form ??modifier::KS (where KS is any KeySpecifier) has the same effect as the binary form .??modifier::KS.

The semantics are defined as follows.

First we define the recursive content of an item as follows:

declare function immediate-content($item as item()) as record(key, value)* {
  if ($item instance of map(*)) {
    map:pairs($item)
  } else if ($item instance of array(*)) {
    for member $m at $p in $item
    return { "key": $p, "value": $m }
  }
};    

declare function recursive-content($item as item()) as record(key, value)* {
  immediate-content($item) ! (., ?items::value =!> recursive-content())
};

Note:

Explanation: the immediate content of a map is obtained by splitting it into a sequence of key-value pairs, each representing one entry. The immediate content of an array is obtained by constructing a sequence of key-value pairs, one for each array member, where the key is the array index and the value is the corresponding member. Each key-value pair is of type record(key as xs:anyAtomicType, value as item()*). The recursive content of an item contains the key-value pairs in its immediate content, each followed by the recursive content obtained by expanding any maps or arrays in the immediate content.

It is then useful to represent the recursive content as a sequence of single-entry-maps^{single-DMentry maps}: so each pair { "key": $K, "value": $V } is converted to the form { $K: $V }. This can be achieved using the expression recursive-content($V) ! { ?key: ?value }.

In addition we define the function array-or-map as follows:

declare function array-or-map($item as item()) {
  typeswitch ($item) {
    case array(*) | map(*) return $item
    default return error(xs:QName("err:XPTY0004"))
  }
}

The result of the expression E??pairs::KS, where E is any expression and KS is any KeySpecifier, is then:

(
  (E =!> array-or-map() => recursive-content()) 
  ! { ?key: ?value }
) ? pairs::KS.

Note:

This is best explained by considering examples.

Consider the expression let $V := [ { "first": "John", "last": "Smith" }, { "first": "Mary", "last": "Evans" } ].

The recursive content of this array is the sequence of six maps:

{ "key": 1, "value": { "first": "John", "last": "Smith" } }
{ "key": 2, "value": { "first": "Mary", "last": "Evans" } }
{ "key": "first", "value": "John" }
{ "key": "last", "value": "Smith" }
{ "key": "first", "value": "Mary" }
{ "key": "last", "value": "Evans" }

The expression $V??pairs::* returns this sequence.

With some other KeySpecifierKS, $V??pairs::KS returns selected items from this sequence that match KS. Formally this is achieved by converting the key-value pairs to single-entry maps^{single-DMentry maps}, applying the KeySpecifier to the sequence of single-entry maps, and then converting the result back into a sequence of key-value pairs.

For example, given the expression $V??pairs::first, the selection from the converted sequence will include the two single entry maps^DM{ "first" : "John" } and { "first" : "Mary" }, which will be delivered in key-value pair form as { "key": "first", "value": "John" }, { "key": "first", "value": "Mary" }.

The effect of using modifiers other than pairs is the same as with shallow lookup expressions:

If the modifier is items (explicitly or by default), the result of $V??items::KS is the same as the result of $V??pairs::KS ! map:get(., "value"); that is, it is the sequence concatenation of the value parts.
If the modifier is values, the result of $V??values::KS is the same as the result of $V??pairs::KS ! array { map:get(., "value") }.
If the modifier is keys, the result of $V??keys::KS is the same as the result of $V??pairs::KS ! map:get(., "key").

Note:

This means that with the example given earlier:

The expression $V ?? first returns the sequence "John", "Mary".
The expression $V ?? last returns the sequence "Smith", "Evans".
The expression $V ?? 1 returns the sequence { "first": "John", "last": "Smith" }.
The expression $V ?? *[. instance of record(first, last)] ! `{ ?first } { ?last }` returns the sequence "John Smith", "Mary Evans".

Note:

The effect of evaluating all shallow lookups on maps rather than arrays is that no error arises if an array subscript is out of bounds. In the above example, $value??3 would return an empty sequence, it would not raise an error.

This also affects the way an xs:untypedAtomic key value is handled. Given the shallow lookup expression $A?$x, if $A is an array and $x (after atomization) is xs:untypedAtomic then the value of $x is converted to an integer (by virtue of the coercion rules applying to a call on array:get). With a deep lookup expression $A??$x, by contrast, the semantics are defined in terms of a map lookup, in which xs:untypedAtomic items are always treated as strings.

Note:

The definition of the recursive-content function is such that items in the top-level value that are not maps or arrays are ignored, whereas items that are not themselves maps or arrays, but which appear in the content of a map or array at the top level, are included. This means that E??X mirrors the behavior of E//X, in that it includes all items that are one-or-more levels deep in the tree.

Note:

The result of the deep lookup operator retains order when processing sequences and arrays, but not when processing maps.

Note:

An expression involving multiple deep lookup operators may return duplicates. For example, the result of the expression [ [ [ "a" ], [ "b" ] ], [ [ "c" ], [ "d" ] ] ] ?? 1 ?? 1 is ([ "a" ], "a", "b", "a", "c"). This is because the first ?? operator selects members in position 1 at all three levels, that is it selects the arrays [ [ "a" ], [ "b" ] ], [ "a" ], and [ "c" ] as well as each of the four string values. The second ?? operator selects members in position 1 within each of these values, which results in the string "a" being selected twice.

Note:

A type error is raised if the value of the left-hand expression includes an item that is neither a map nor an array.

Example: Examples of Deep Lookup Expressions

Consider the tree $tree of maps and arrays that results from applying the fn:parse-json function to the following input:

{
  "desc"    : "Distances between several cities, in kilometers.",
  "updated" : "2014-02-04T18:50:45",
  "uptodate": true,
  "author"  : null,
  "cities"  : {
    "Brussels": [
      { "to": "London",    "distance": 322 },
      { "to": "Paris",     "distance": 265 },
      { "to": "Amsterdam", "distance": 173 }
    ],
    "London": [
      { "to": "Brussels",  "distance": 322 },
      { "to": "Paris",     "distance": 344 },
      { "to": "Amsterdam", "distance": 358 }
    ],
    "Paris": [
      { "to": "Brussels",  "distance": 265 },
      { "to": "London",    "distance": 344 },
      { "to": "Amsterdam", "distance": 431 }
     ],
    "Amsterdam": [
      { "to": "Brussels",  "distance": 173 },
      { "to": "London",    "distance": 358 },
      { "to": "Paris",     "distance": 431 }
    ]
  }
}

Given two variables $from and $to containing the names of two cities that are present in this table, the distance between the two cities can be obtained with the expression:

$tree ?? $from ?? *[. instance of record(to, distance)][?to = $to] ? distance

The names of all pairs of cities whose distance is represented in the data can be obtained with the expression:

$tree ?? $cities
=> map:for-each(fn($key, $val) { $val ?? to ! ($key || "-" || .) })

Example: Comparison with JSONPath

This example provides XPath equivalents to some examples given in the JSONPath specification. [TODO: add a reference].

The examples query the result of parsing the following JSON value, representing a store whose stock consists of four books and a bicycle:

{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 399
    }
  }
}

The following table illustrates some queries on this data, expressed both in JSONPath and in XQuery 4.0.

JSONPath vs XQuery 4.0 Comparison
Query	JSONPath	XQuery 4.0
The authors of all books in the store	`$.store.book[*].author`	`$m?store?book??author`
All authors	`$..author`	`$m??author`
All things in store (four books and a red bicycle)	`$.store.*`	`$m?store?*`
The prices of everything in the store	`$.store..price`	`$m?store??price`
The third book	`$..book[2]`	`$m??book?3`
The third book's author	`$..book[2].author`	`$m??book?3?author`
The third book's publisher (empty result)	`$..book[2].publisher`	`$m??book?3?publisher`
The last book (in order)	`$..book[-1]`	`$m??book => array:foot()`
The first two books	`$..book[0,1]`	`$m??book?(1, 2)`
All books with an ISBN	`$..book[?@.isbn]`	`$m??book[?isbn]`
All books cheaper than 10	`$..book[?@.price<10]`	`$m??book[?price lt 10]`
All member values and array elements contained in the input value	`$..*`	`$m??*`

4.14.4 Filter Expressions for Maps and Arrays

Changes in 4.0 ⬇ ⬆

Filter expressions for maps and arrays are introduced. [Issue 1159 PR 1163 20 April 2024]
Predicates in filter expressions for maps and arrays can now be numeric. [Issue 1207 PR tba 15 May 2024]

`FilterExprAM`	::=	`PostfixExpr "?[" Expr "]"`
`PostfixExpr`	::=	`PrimaryExpr \| FilterExpr \| DynamicFunctionCall \| LookupExpr \| FilterExprAM`
`Expr`	::=	`(ExprSingle ++ ",")`

Maps and arrays can be filtered using the construct INPUT?[FILTER]. For example, $array?[count(.)=1] filters an array to retain only those members that are single items.

Note:

The character-pair ?[ forms a single token; no intervening whitespace or comment is allowed.

The required type of the left-hand operand INPUT is (map(*)|array(*))?: that is, it must be either an empty sequence, a single map, or a single array [err:XPTY0004]. If it is an empty sequence, the result of the expression is an empty sequence.

If the value of INPUT is an array, then the FILTER expression is evaluated for each member of the array, with that member as the context value, with its position in the array as the context position, and with the size of the array as the context size. The result of the expression is an array containing those members of the input array for which the predicate truth value of the FILTER expression is true. The order of retained members is preserved.

For example, the following expression:

let $array := [ (), 1, (2, 3), (4, 5, 6) ]
return $array?[count(.) ge 2]

returns:

[ (2, 3), (4, 5, 6) ]

Note:

Numeric predicates are handled in the same way as with filter expressions for sequences. However, the result is always an array, even if only one member is selected. For example, given the $array shown above, the result of $array?[3] is the entry single-member array^DM[ (2, 3) ]. Contrast this with $array?3 which delivers the sequence 2, 3.

If the value of INPUT is a map, then the FILTER expression is evaluated for each entry in the map, with the context value set to an item of type record(key as xs:anyAtomicType, value as item()*), in which the key and value fields represent the key and value of the map entry. The context position is the position of the entry in the map (in entry order^DM), and the context size is the number of entries in the map. The result of the expression is a map containing those entries of the input map for which the predicate truth value of the FILTER expression is true. The relative order of entries in the result retains the relative order of entries in the input.

For example, the following expression:

let map := { 1: "alpha", 2: "beta", 3: "gamma" }
return $map?[?key ge 2]

returns:

{ 2: "beta", 3: "gamma" }

Note:

A filter expression such as $map?[last()-1, last()] might be used to return the last two entries of a map in entry order^DM.

G Glossary (Non-Normative)

anonymous function

An anonymous function is a function item with no name. Anonymous functions may be created, for example, by evaluating an inline function expression or by partial function application.

application function

Application functions are function definitions written in a host language such as XQuery or XSLT whose syntax and semantics are defined in this family of specifications. Their behavior (including the rules determining the static and dynamic context) follows the rules for such functions in the relevant host language specification.

argument expression

An argument to a function call is either an argument expression or an ArgumentPlaceholder (?); in both cases it may either be supplied positionally, or identified by a name (called a keyword).

arity range

A function definition has an arity range, which is a range of consecutive non-negative integers. If the function definition has M required parameters and N optional parameters, then its arity range is from M to M+N inclusive.

array

An array is a function item that associates a set of positions, represented as positive integer keys, with values.

associated value

The value associated with a given key is called the associated value of the key.

atomic item

An atomic item is a value in the value space of an atomic type, as defined in [XML Schema 1.0] or [XML Schema 1.1].

atomic type

An atomic type is a simple schema type whose {variety}^XS11-1 is atomic.

atomization

Atomization of a sequence is defined as the result of invoking the fn:data function, as defined in Section 2.1.4 fn:data^FO.

available documents

Available documents. This is a mapping of strings to document nodes. Each string represents the absolute URI of a resource. The document node is the root of a tree that represents that resource using the data model. The document node is returned by the fn:doc function when applied to that URI.

available item collections

Available collections. This is a mapping of strings to sequences of items. Each string represents the absolute URI of a resource. The sequence of items represents the result of the fn:collection function when that URI is supplied as the argument.

available text resources

Available text resources. This is a mapping of strings to text resources. Each string represents the absolute URI of a resource. The resource is returned by the fn:unparsed-text function when applied to that URI.

available uri collections

Available URI collections. This is a mapping of strings to sequences of URIs. The string represents the absolute URI of a resource which can be interpreted as an aggregation of a number of individual resources each of which has its own URI. The sequence of URIs represents the result of the fn:uri-collection function when that URI is supplied as the argument.

axis step

An axis step returns a sequence of nodes that are reachable from a starting 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 .

base URI declaration

A base URI declaration specifies the Static Base URI property. The Static Base URI property is used when resolving relative URI references.

binding collection

In a for clause, when an expression is preceded by the keyword in, the value of that expression is called a binding collection.

binding sequence

In a window clause, when an expression is preceded by the keyword in, the value of that expression is called a binding sequence.

boundary-space declaration

A boundary-space declaration sets the boundary-space policy in the static context, overriding any implementation-defined default. Boundary-space policy controls whether boundary whitespace is preserved by element constructors during processing of the query.

boundary-space policy

Boundary-space policy. This component controls the processing of boundary whitespace by direct element constructors, as described in 4.12.1.4 Boundary Whitespace.

boundary whitespace

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.

character reference

A character reference is an XML-style reference to a [Unicode] character, identified by its decimal or hexadecimal codepoint.

choice item type

A choice item type defines an item type that is the union of a number of alternatives. For example the type (xs:hexBinary | xs:base64Binary) defines the union of these two primitive atomic types, while the type (map(*) | array(*)) matches any item that is either a map or an array.

coercion rules

The coercion rules are rules used to convert a supplied value to a required type, for example when converting an argument of a function call to the declared type of the function parameter.

collation

A collation is a specification of the manner in which strings and URIs are compared and, by extension, ordered. For a more complete definition of collation, see Section 5.3 Comparison of strings^FO.

comma operator

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.

complex terminal

A complex terminal is a variable terminal whose production rule references, directly or indirectly, an ordinary production rule.

computed element constructor

A computed element constructor creates an element node, allowing both the name and the content of the node to be computed.

construction declaration

A construction declaration sets the construction mode in the static context, overriding any implementation-defined default.

construction mode

Construction mode. The construction mode governs the behavior of element and document node constructors. If construction mode is preserve, the type of a constructed element node is xs:anyType, and all attribute and element nodes copied during node construction retain their original types. If construction mode is strip, the type of a constructed element node is xs:untyped; all element nodes copied during node construction receive the type xs:untyped, and all attribute nodes copied during node construction receive the type xs:untypedAtomic.

constructor function

The constructor function for a given simple type is used to convert instances of other simple types into the given type. The semantics of the constructor function call T($arg) are defined to be equivalent to the expression $arg cast as T?.

content expression

In an enclosed expression, the optional expression enclosed in curly brackets is called the content expression.

context dependent

A function definition is said to be context dependent if its result depends on the static or dynamic context of its caller. A function definition may be context-dependent for some arities in its arity range, and context-independent for others: for example fn:name#0 is context-dependent while fn:name#1 is context-independent.

context node

When the context value is a single item, it can also be referred to as the context item; when it is a single node, it can also be referred to as the context node.

context position

The context position is the position of the context value within the series of values currently being processed.

context size

The context size is the number of values in the series of values currently being processed.

context value

The context value is the value currently being processed.

copy-namespaces declaration

A copy-namespaces declaration sets the value of copy-namespaces mode in the static context, overriding any implementation-defined default. Copy-namespaces mode controls the namespace bindings that are assigned when an existing element node is copied by an element constructor or document constructor.

copy-namespaces mode

Copy-namespaces mode. This component controls the namespace bindings that are assigned when an existing element node is copied by an element constructor, as described in 4.12.1 Direct Element Constructors. Its value consists of two parts: preserve or no-preserve, and inherit or no-inherit.

current dateTime

Current dateTime. This information represents an implementation-dependent point in time during the processing of a query , and includes an explicit timezone. It can be retrieved by the fn:current-dateTime function. If called multiple times during the execution of a query , this function always returns the same result.

data model

XQuery 4.0 operates on the abstract, logical structure of an XML document or JSON object rather than its surface syntax. This logical structure, known as the data model, is defined in [XQuery and XPath Data Model (XDM) 4.0].

decimal-format declaration

A decimal format declaration adds a decimal format to the statically known decimal formats, which define the properties used to format numbers using the fn:format-number() function

decimal-separator

decimal-separator(M, R) is used to separate the integer part of the number from the fractional part. The default value for both the marker and the rendition is U+002E (FULL STOP, PERIOD, .) .

default calendar

Default calendar. This is the calendar used when formatting dates in human-readable output (for example, by the functions fn:format-date and fn:format-dateTime) if no other calendar is requested. The value is a string.

default collation

Default collation. This identifies one of the collations in statically known collations as the collation to be used by functions and operators for comparing and ordering values of type xs:string and xs:anyURI (and types derived from them) when no explicit collation is specified.

default collation declaration

A default collation declaration sets the value of the default collation in the static context, overriding any implementation-defined default.

default collection

Default collection. This is the sequence of items that would result from calling the fn:collection function with no arguments.

default function namespace

Default function namespace. This is either a namespace URI, or absent^DM. The namespace URI, if present, is used for any unprefixed QName appearing in a position where a function name is expected.

default language

Default language. This is the natural language used when creating human-readable output (for example, by the functions fn:format-date and fn:format-integer) if no other language is requested. The value is a language code as defined by the type xs:language.

default namespace for elements and types

Default namespace for elements and types. This is either a namespace URI, or the special value "##any", or absent^DM. This indicates how unprefixed QNames are interpreted when they appear in a position where an element name or type name is expected.

default order for empty sequences

Default order for empty sequences. This component controls the processing of empty sequences and NaN values as ordering keys in an order by clause in a FLWOR expression, as described in 4.13.9 Order By Clause.

default place

Default place. This is a geographical location used to identify the place where events happened (or will happen) when processing dates and times using functions such as fn:format-date, fn:format-dateTime, and fn:civil-timezone, if no other place is specified. It is used when translating timezone offsets to civil timezone names, and when using calendars where the translation from ISO dates/times to a local representation is dependent on geographical location. Possible representations of this information are an ISO country code or an Olson timezone name, but implementations are free to use other representations from which the above information can be derived. The only requirement is that it should uniquely identify a civil timezone, which means that country codes for countries with multiple timezones, such as the United States, are inadequate.

default URI collection

Default URI collection. This is the sequence of URIs that would result from calling the fn:uri-collection function with no arguments.

delimiting terminal symbol

The delimiting terminal symbols are: !!=##)$%((#)**:+,--->->...////>::*:::=;<<!--<![CDATA[</<<<=<?==!>=>=?>>>=>>??>???[@[]]]>]```````[`{{{{|||}}`}}×÷AposStringLiteral BracedURILiteral QuotStringLiteral S StringLiteral

depends on

A variable value (or the context value) depends on another variable value (or the context value) if, during the evaluation of the initializing expression of the former, the latter is accessed through the module context.

derives from

A schema typeS₁ is said to derive fromschema typeS₂ if any of the following conditions is true:

S₁ is the same type as S₂.
S₂ is the base type of S₁.
S₂ is a pure union type of which S₁ is a member type.
There is a schema typeM such that S₁derives fromM and Mderives fromS₂.

digit

digit(M) is a character used in the picture string to represent an optional digit; the default value is U+0023 (NUMBER SIGN, #) .

direct element constructor

A direct element constructor is a form of element constructor in which the name of the constructed element is a constant.

document order

Informally, document order is the order in which nodes appear in the XML serialization of a document.

dynamically known function definitions

Dynamically known function definitions. This is a set of function definitions. It includes the statically known function definitions as a subset, but may include other function definitions that are not known statically.

dynamic context

The dynamic context of an expression is defined as information that is needed for the dynamic evaluation of an expression, beyond any information that is needed from the static context.

dynamic error

A dynamic error is an error that must be detected during the dynamic evaluation phase and may be detected during the static analysis phase.

dynamic evaluation phase

The dynamic evaluation phase is the phase during which the value of an expression is computed.

dynamic function call

A dynamic function call consists of a base expression that returns the function and a parenthesized list of zero or more arguments (argument expressions or ArgumentPlaceholders).

dynamic function call

A dynamic function call is an expression that is evaluated by calling a function item, which is typically obtained dynamically.

dynamic type

Every value matches one or more sequence types. A value is said to have a dynamic typeT if it matches (or is an instance of) the sequence type T.

effective boolean value

The effective boolean value of a value is defined as the result of applying the fn:boolean function to the value, as defined in Section 7.3.1 fn:boolean^FO.

effective case

The effective case of a switch expression is the first case clause that matches, using the rules given above, or the default clause if no such case clause exists.

effective case

The effective case in a typeswitch expression is the first case clause in which the value of the operand expression matches a SequenceType in the SequenceTypeUnion of the case clause, using the rules of SequenceType matching.

empty order declaration

An empty order declaration sets the default order for empty sequences in the static context, overriding any implementation-defined default. This declaration controls the processing of empty sequences and NaN values as ordering keys in an order by clause in a FLWOR expression.

empty sequence

A sequence containing zero items is called an empty sequence.

enclosed expression

An enclosed expression is an instance of the EnclosedExpr production, which allows an optional expression within curly brackets.

encoding declaration

If present, a version declaration may optionally include an encoding declaration. The value of the string literal following the keyword encoding is an encoding name, and must conform to the definition of EncName specified in [XML 1.0] [err:XQST0087]. The purpose of an encoding declaration is to allow the writer of a query to provide a string that indicates how the query is encoded, such as "UTF-8", "UTF-16", or "US-ASCII".

entry

Each key / value pair in a map is called an entry.

enumeration type

An EnumerationType accepts a fixed set of string values.

environment variables

Environment variables. This is a mapping from names to values. Both the names and the values are strings. The names are compared using an implementation-defined collation, and are unique under this collation. The set of environment variables is implementation-defined and may be empty.

equivalent grouping keys

Two tuples T₁ and T₂ have equivalent grouping keys if and only if, for each grouping variable GV, the atomized value of GV in T₁ is deep-equal to the atomized value of GV in T₂, as defined by applying the function fn:deep-equal using the appropriate collation.

error value

In addition to its identifying QName, a dynamic error may also carry a descriptive string and one or more additional values called error values.

Executable Base URI

Executable Base URI. This is an absolute URI used to resolve relative URIs during the evaluation of expressions; it is used, for example, to resolve a relative URI supplied to the fn:doc or fn:unparsed-text functions.

expanded QName

An expanded QName is a triple: its components are a prefix, a local name, and a namespace URI. In the case of a name in no namespace, the namespace URI and prefix are both absent. In the case of a name in the default namespace, the prefix is absent.

exponent-separator

exponent-separator(M, R) is used to separate the mantissa from the exponent in scientific notation. The default value for both the marker and the rendition is U+0065 (LATIN SMALL LETTER E, e) .

expression context

The expression context for a given expression consists of all the information that can affect the result of the expression.

extension expression

An extension expression is an expression whose semantics are implementation-defined.

external function

External functions can be characterized as functions that are neither part of the processor implementation, nor written in a language whose semantics are under the control of this family of specifications. The semantics of external functions, including any context dependencies, are entirely implementation-defined. In XSLT, external functions are called Section 24.1 Extension Functions ^XT30.

filter expression

A filter expression is an expression in the form E1[E2]: its effect is to return those items from the value of E1 that satisfy the predicate in E2.

fixed focus

A fixed focus is a focus for an expression that is evaluated once, rather than being applied to a series of values; in a fixed focus, the context value is set to one specific value, the context position is 1, and the context size is 1.

focus

The first three components of the dynamic context (context value, context position, and context size) are called the focus of the expression.

focus function

A focus function is an inline function expression in which the function signature is implicit: the function takes a single argument of type item()* (that is, any value), and binds this to the context value when evaluating the function body, which returns a result of type item()*.

function assertion

A function assertion is a predicate that restricts the set of functions matched by a FunctionType. It uses the same syntax as 5.15 Annotations.

function coercion

Function coercion wraps a function item in a new function whose signature is the same as the expected type. This effectively delays the checking of the argument and return types until the function is called.

function definition

A function definition contains information used to evaluate a static function call, including the name, parameters, and return type of the function.

function item

A function item is an item that can be called using a dynamic function call.

generalized atomic type

A generalized atomic type is an item type whose instances are all atomic items. Generalized atomic types include (a) atomic types, either built-in (for example xs:integer) or imported from a schema, (b) pure union types, either built-in (xs:numeric and xs:error) or imported from a schema, (c) choice item types if their alternatives are all generalized atomic types, and (d) enumeration types.

grouping key

The atomized value of a grouping variable is called a grouping key.

grouping-separator

grouping-separator(M, R) is used to separate groups of digits (for example as a thousands separator). The default value for both the marker and the rendition is U+002C (COMMA, ,) .

grouping variable

Each grouping specification specifies one grouping variable, which refers to variable bindings in the pre-grouping tuples. The values of the grouping variables are used to assign pre-grouping tuples to groups.

guarded

An expression E is said to be guarded by some governing condition C if evaluation of E is not allowed to fail with a dynamic error except when C applies.

ignorable whitespace

Ignorable whitespace consists of any whitespace characters that may occur between terminals, unless these characters occur in the context of a production marked with a ws:explicit annotation, in which case they can occur only where explicitly specified (see A.3.5.2 Explicit Whitespace Handling).

implausible

Certain expressions, while not erroneous, are classified as being implausible, because they achieve no useful effect.

implementation defined

Implementation-defined indicates an aspect that may differ between implementations, but must be specified by the implementer for each particular implementation.

implementation dependent

Implementation-dependent indicates an aspect that may differ between implementations, is not specified by this or any W3C specification, and is not required to be specified by the implementer for any particular implementation.

implicit timezone

Implicit timezone. This is the timezone to be used when a date, time, or dateTime value that does not have a timezone is used in a comparison or arithmetic operation. The implicit timezone is an implementation-defined value of type xs:dayTimeDuration. See Section 3.2.7.3 Timezones ^XS1-2 or Section 3.3.7 dateTime ^XS11-2 for the range of valid values of a timezone.

infinity

infinity(R) is the string used to represent the double value infinity (INF); the default value is the string "Infinity"

initial context value

In the dynamic context of every module in a query, the context value component must have the same setting. If this shared setting is not absent^DM, it is referred to as the initial context value.

initializing expression

If a variable declaration includes an expression (VarValue or VarDefaultValue), the expression is called an initializing expression. The static context for an initializing expression includes all functions, variables, and namespaces that are declared or imported anywhere in the Prolog.

inline function expression

An inline function expression, when evaluated, creates an anonymous function defined directly in the inline function expression.

in-scope attribute declarations

In-scope attribute declarations. Each attribute declaration is identified either by an expanded QName (for a top-level attribute declaration) or by an implementation-dependent attribute identifier (for a local attribute declaration). If the Schema Aware Feature is supported, in-scope attribute declarations include all attribute declarations found in imported schemas.

in-scope element declarations

In-scope element declarations. Each element declaration is identified either by an expanded QName (for a top-level element declaration) or by an implementation-dependent element identifier (for a local element declaration). If the Schema Aware Feature is supported, in-scope element declarations include all element declarations found in imported schemas.

in-scope named item types

In-scope named item types. This is a mapping from expanded QName to named item types.

in-scope namespaces

The in-scope namespaces property of an element node is a set of namespace bindings, each of which associates a namespace prefix with a URI.

in-scope schema definitions

In-scope schema definitions is a generic term for all the element declarations, attribute declarations, and schema type definitions that are in scope during static analysis of an expression.

in-scope schema type

In-scope schema types. Each schema type definition is identified either by an expanded QName (for a named type) or by an implementation-dependent type identifier (for an anonymous type). The in-scope schema types include the predefined schema types described in 3.5 Schema Types. If the Schema Aware Feature is supported, in-scope schema types also include all type definitions found in imported schemas.

in-scope variables

In-scope variables. This is a mapping from expanded QName to type. It defines the set of variables that are available for reference within an expression. The expanded QName is the name of the variable, and the type is the static type of the variable.

item

An item is either an atomic item, a node, or a function item.

item type

An item type is a type that can be expressed using the ItemType syntax, which forms part of the SequenceType syntax. Item types match individual items.

item type designator

An item type designator is a syntactic construct conforming to the grammar rule ItemType. An item type designator is said to designate an item type.

kind test

An alternative form of a node test called a kind test can select nodes based on their kind, name, and type annotation.

lexical QName

A lexical QName is a name that conforms to the syntax of the QName production

library module

A module that does not contain a Query Body is called a library module. A library module consists of a module declaration followed by a Prolog.

literal

A literal is a direct syntactic representation of an atomic item.

literal terminal

A literal terminal is a token appearing as a string in quotation marks on the right-hand side of an ordinary production rule.

main module

A main module consists of a Prolog followed by a Query Body.

map

A map is a function that associates a set of keys with values, resulting in a collection of key / value pairs.

mapping arrow operator

The mapping arrow operator=!> applies a function to each item in a sequence.

may

MAY means that an item is truly optional.

member

The values of an array are called its members.

minus-sign

minus-sign(R) is the string used to mark negative numbers; the default value is U+002D (HYPHEN-MINUS, -) .

module

A module is a fragment of XQuery code that conforms to the Module grammar and can independently undergo the static analysis phase described in 2.3.3 Expression Processing. Each module is either a main module or a library module.

module declaration

A module declaration serves to identify a module as a library module. A module declaration begins with the keyword module and contains a namespace prefix and a URILiteral.

module feature

The Module Feature allows a query Prolog to contain a Module Import and allows library modules to be created.

module import

A module import imports the public variable declarations, public function declarations, and public item type declarations from one or more library modules into the statically known function definitions, in-scope variables, or in-scope named item types of the importing module.

must

MUST means that the item is an absolute requirement of the specification.

must not

MUST NOT means that the item is an absolute prohibition of the specification.

named function reference

A named function reference is an expression (written name#arity) which evaluates to a function item, the details of the function item being based on the properties of a function definition in the static context.

named item type

A named item type is an ItemType identified by an expanded QName.

name expression

When an expression is used to specify the name of a constructed node, that expression is called the name expression of the constructor.

namespace declaration

A namespace declaration declares a namespace prefix and associates it with a namespace URI, adding the (prefix, URI) pair to the set of statically known namespaces.

namespace declaration attribute

A namespace declaration attribute is used inside a direct element constructor. Its purpose is to bind a namespace prefix (including the zero-length prefix) for the constructed element node, including its attributes.

namespace-sensitive

The namespace-sensitive types are xs:QName, xs:NOTATION, types derived by restriction from xs:QName or xs:NOTATION, list types that have a namespace-sensitive item type, and union types with a namespace-sensitive type in their transitive membership.

name test

A node test that consists only of an EQName or a Wildcard is called a name test.

NaN

NaN(R) is the string used to represent the double value NaN (not a number); the default value is the string "NaN"

node

A node is an instance of one of the node kinds defined in Section 5 Nodes^DM.

node test

A node test is a condition on the name, kind (element, attribute, text, document, comment, or processing instruction), and/or type annotation of a node. A node test determines which nodes contained by an axis are selected by a step.

non-delimiting terminal symbol

The non-delimiting terminal symbols are: allowingancestorancestor-or-selfandarrayasascendingatattributebase-uriboundary-spacebycasecastcastablecatchchildcollationcommentconstructioncontextcopy-namespacescountdecimal-formatdecimal-separatordeclaredefaultdescendantdescendant-or-selfdescendingdigitdivdocumentdocument-nodeelementelseemptyempty-sequenceencodingendenumeqeveryexceptexponent-separatorexternalfalsefixedfnfollowingfollowing-or-selffollowing-siblingfollowing-sibling-or-selfforfunctiongegreatestgroupgrouping-separatorgtidivifimportininfinityinheritinstanceintersectisitemitemskeykeyslaxleleastletltmapmemberminus-signmodmodulenamespacenamespace-nodeNaNnenextno-inheritno-preservenodeofonlyoptionororderorderedorderingotherwisepairsparentpattern-separatorper-millepercentprecedingpreceding-or-selfpreceding-siblingpreceding-sibling-or-selfpreservepreviousprocessing-instructionrecordreturnsatisfiesschemaschema-attributeschema-elementselfslidingsomestablestartstrictstripswitchtextthentotreattruetrytumblingtypetypeswitchunionunorderedvalidatevaluevaluesvariableversionwhenwherewhilewindowxqueryzero-digitBinaryIntegerLiteral DecimalLiteral DoubleLiteral HexIntegerLiteral IntegerLiteral NCName QName URIQualifiedName

numeric

The type xs:numeric is defined as a union type with member types xs:double, xs:float, and xs:decimal. An item that is an instance of any of these types is referred to as a numeric value, and a type that is a subtype of xs:numeric is referred to as a numeric type.

numeric predicate

A predicate whose predicate expression returns a value of type xs:numeric+ is called a numeric predicate.

option declaration

An option declaration declares an option that affects the behavior of a particular implementation. Each option consists of an identifying EQName and a StringLiteral.

ordinary production rule

An ordinary production rule is a production rule in A.1 EBNF that is not annotated ws:explicit.

output declaration

An output declaration is an option declaration in the namespace http://www.w3.org/2010/xslt-xquery-serialization; it is used to declare serialization parameters.

partial function application

A static or dynamic function call is a partial function application if one or more arguments is an ArgumentPlaceholder.

partially applied function

A partially applied function is a function created by partial function application.

path expression

A path expression consists of a series of one or more steps, separated by / or //, and optionally beginning with / or //. A path expression is typically used to locate nodes within trees.

pattern-separator

pattern-separator(M) is a character used to separate positive and negative sub-pictures in a picture string; the default value is U+003B (SEMICOLON, ;) .

percent

percent(M, R) is used to indicate that the number is written as a per-hundred fraction; the default value for both the marker and the rendition is U+0025 (PERCENT SIGN, %) .

per-mille

per-mille(M, R) is used to indicate that the number is written as a per-thousand fraction; the default value for both the marker and the rendition is U+2030 (PER MILLE SIGN, ‰) .

pipeline operator

The pipeline operator-> evaluates an expression and binds the result to the context value before evaluating another expression.

positional variable

A positional variable is a variable that is preceded by the keyword at.

pragma

A pragma is denoted by the delimiters (# and #), and consists of an identifying EQName followed by implementation-defined content.

predefined entity reference

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.

predicate truth value

The predicate truth value of a value $V is the result of the expression if ($V instance of xs:numeric+) then ($V = position()) else fn:boolean($V).

primary expression

Primary expressions are the basic primitives of the language. They include literals, variable references, context value references, 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.

principal node kind

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.

private function

A private function is a function with a %private annotation. A private function is hidden from module import, which can not import it into the statically known function definitions of another module.

private item type

A private item type is a named item type with a %private annotation. A private item type is hidden from module import, which can not import it into the in-scope named item types of another module.

private variable

A private variable is a variable with a %private annotation. A private variable is hidden from module import, which can not import it into the in-scope variables of another module.

Prolog

A Prolog is a series of declarations and imports that define the processing environment for the module that contains the Prolog.

public function

A public function is a function without a %private annotation. A public function is accessible to module import, which can import it into the statically known function definitions of another module.

public item type

A public item type is an item type declaration without a %private annotation. A public item type is accessible to module import, which can import it into the in-scope named item types of another module.

public variable

A public variable is a variable without a %private annotation. A public variable is accessible to module import, which can import it into the in-scope variables of another module. Using %public and %private annotations in a main module is not an error, but it does not affect module imports, since a main module cannot be imported. It is a static error [err:XQST0116] if a variable declaration contains both a %private and a %public annotation, more than one %private annotation, or more than one %public annotation.

pure union type

A pure union type is a simple type that satisfies the following constraints: (a) {variety}^XS11-1 is union, (b) the {facets}^XS11-1 property is empty, (c) no type in the transitive membership of the union type has {variety}^XS11-1list, and (d) no type in the transitive membership of the union type is a type with {variety}^XS11-1union having a non-empty {facets}^XS11-1 property

query

A query consists of one or more modules.

query body

The Query Body, if present, consists of an expression that defines the result of the query.

reserved namespaces

A reserved namespace is a namespace that must not be used in the name of a function declaration.

resolve

To resolve a relative URI$rel against a base URI $base is to expand it to an absolute URI, as if by calling the function fn:resolve-uri($rel, $base).

reverse document order

The node ordering that is the reverse of document order is called reverse document order.

same key

Two atomic items K1 and K2 have the same key value if fn:atomic-equal(K1, K2) returns true, as specified in Section 13.2.1 fn:atomic-equal^FO

schema aware feature

The Schema Aware Feature permits the query Prolog to contain a schema import, and permits a query to contain a validate expression (see 4.25 Validate Expressions).

schema import

A schema import imports the element declarations, attribute declarations, and type definitions from a schema into the in-scope schema definitions. For each named user-defined simple type in the schema, schema import also adds a corresponding constructor function.

schema type

A schema type is a complex type or simple type as defined in the [XML Schema 1.0] or [XML Schema 1.1] specifications, including built-in types as well as user-defined types.

sequence

A sequence is an ordered collection of zero or more items.

sequence arrow operator

The sequence arrow operator=> applies a function to a supplied sequence.

sequence concatenation

The sequence concatenation of a number of sequences S₁, S₂, ... S_n is defined to be the sequence formed from the items of S₁, followed by the items from S₂, and so on, retaining order.

sequence type

A sequence type is a type that can be expressed using the SequenceType syntax. Sequence types are used whenever it is necessary to refer to a type in an XQuery 4.0 expression. Since all values are sequences, every value matches one or more sequence types.

sequence type designator

A sequence type designator is a syntactic construct conforming to the grammar rule SequenceType. A sequence type designator is said to designate a sequence type.

SequenceType matching

SequenceType matching compares a value with an expected sequence type.

serialization

Serialization is the process of converting an XDM instance to a sequence of octets (step DM4 in Figure 1.), as described in [XSLT and XQuery Serialization 4.0].

serialization feature

The Serialization Feature provides means for serializing the result of a query as specified in 2.3.5 Serialization.

setter

Setters are declarations that set the value of some property that affects query processing, such as construction mode or default collation.

should

SHOULD means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

singleton

A sequence containing exactly one item is called a singleton.

singleton focus

A singleton focus is a fixed focus in which the context value is a singleton item.

stable

Document order is stable, which means that the relative order of two nodes will not change during the processing of a given query , even if this order is implementation-dependent.

statically known collations

Statically known collations. This is an implementation-defined mapping from URI to collation. It defines the names of the collations that are available for use in processing queries and expressions.

statically known decimal formats

Statically known decimal formats. This is a mapping from QNames to decimal formats, with one default format that has no visible name, referred to as the unnamed decimal format. Each format is available for use when formatting numbers using the fn:format-number function.

statically known function definitions

Statically known function definitions. This is a set of function definitions.

statically known namespaces

Statically known namespaces. This is a mapping from prefix to namespace URI that defines all the namespaces that are known during static processing of a given expression.

static analysis phase

The static analysis phase depends on the expression itself and on the static context. The static analysis phase does not depend on input data (other than schemas).

Static Base URI

Static Base URI. This is an absolute URI, used to resolve relative URIs during static analysis.

static context

The static context of an expression is the information that is available during static analysis of the expression, prior to its evaluation.

static error

An error that can be detected during the static analysis phase, and is not a type error, is a static error.

static function call

A static function call consists of an EQName followed by a parenthesized list of zero or more arguments.

static type

The static type of an expression is the best inference that the processor is able to make statically about the type of the result of the expression.

step

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 postfix expression.

string constructor

A String Constructor creates a string from literal text and interpolated expressions.

string value

The string value of a node is a string and can be extracted by applying the Section 2.1.3 fn:string^FO function to the node.

substantively disjoint

Two sequence types are deemed to be substantively disjoint if (a) neither is a subtype of the other (see 3.3.1 Subtypes of Sequence Types) and (b) the only values that are instances of both types are one or more of the following:

The empty sequence, ().
The empty map, {}.The empty map^DM, {}.The empty map^{empty DMmap}, {}.
The empty array, [].The empty array^DM, [].The empty array^{empty DMarray}, [].

substitution group

Substitution groups are defined in Section 2.2.2.2 Element Substitution Group ^XS1-1 and Section 2.2.2.2 Element Substitution Group ^XS11-1. Informally, the substitution group headed by a given element (called the head element) consists of the set of elements that can be substituted for the head element without affecting the outcome of schema validation.

subtype

Given two sequence types or item types, the rules in this section determine if one is a subtype of the other. If a type A is a subtype of type B, it follows that every value matched by A is also matched by B.

subtype substitution

The use of a value that has a dynamic type that is a subtype of the expected type is known as subtype substitution.

symbol

Each rule in the grammar defines one symbol, using the following format:

symbol ::= expression

symbol separators

Whitespace and Comments function as symbol separators. For the most part, they are not mentioned in the grammar, and may occur between any two terminal symbols mentioned in the grammar, except where that is forbidden by the /* ws: explicit */ annotation in the EBNF, or by the /* xgc: xml-version */ annotation.

system function

System functions include the functions defined in [XQuery and XPath Functions and Operators 4.0], functions defined by the specifications of a host language, constructor functions for atomic types, and any additional functions provided by the implementation. System functions are sometimes called built-in functions.

target namespace

The target namespace of a module is the namespace of the objects (such as elements or functions) that it defines.

terminal

A terminal is a symbol or string or pattern that can appear in the right-hand side of a rule, but never appears on the left-hand side in the main grammar, although it may appear on the left-hand side of a rule in the grammar for terminals.

tuple

A tuple is a set of zero or more named variables, each of which is bound to a value that is an XDM instance.

tuple stream

A tuple stream is an ordered sequence of zero or more tuples.

type annotation

Each element node and attribute node in an XDM instance has a type annotation (described in Section 2.8 Schema Information^DM). The type annotation of a node is a reference to a schema type.

typed data feature

The Typed Data Feature permits an XDM instance to contain element node types other than xs:untyped and attributes node types other than xs:untypedAtomic.

type declaration

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 3.1 Sequence Types.

typed value

The typed value of a node is a sequence of atomic items and can be extracted by applying the Section 2.1.4 fn:data^FO function to the node.

type error

A type error may be raised during the static analysis phase or the dynamic evaluation phase. During the static analysis phase, a type error occurs when the static type of an expression does not match the expected type of the context in which the expression occurs. During the dynamic evaluation phase, a type error occurs when the dynamic type of a value does not match the expected type of the context in which the value occurs.

URI

Within this specification, the term URI refers to a Universal Resource Identifier as defined in [RFC3986] and extended in [RFC3987] with the new name IRI.

user-defined function

User defined functions are functions that contain a function body, which provides the implementation of the function as a content expression.

value

In the data model, a value is always a sequence.

variable declaration

A variable declaration in the XQuery prolog defines the name and static type of a variable, and optionally a value for the variable. It adds to the in-scope variables in the static context, and may also add to the variable values in the dynamic context.

variable reference

A variable reference is an EQName preceded by a $-sign.

variable terminal

A variable terminal is an instance of a production rule that is not itself an ordinary production rule but that is named (directly) on the right-hand side of an ordinary production rule.

variable values

Variable values. This is a mapping from expanded QName to value. It contains the same expanded QNames as the in-scope variables in the static context for the expression. The expanded QName is the name of the variable and the value is the dynamic value of the variable, which includes its dynamic type.

version declaration

A version declaration can identify the applicable XQuery syntax and semantics for a module, as well as its encoding.

warning

In addition to static errors, dynamic errors, and type errors, an XQuery 4.0 implementation may raise warnings, either during the static analysis phase or the dynamic evaluation phase. The circumstances in which warnings are raised, and the ways in which warnings are handled, are implementation-defined.

whitespace

A whitespace character is any of the characters defined by [http://www.w3.org/TR/REC-xml/#NT-S].

wildcard-matches

In these rules, if MU and NU are NameTestUnions, then MUwildcard-matchesNU is true if every name that matches MU also matches NU.

window

A window is a sequence of consecutive items drawn from the binding sequence.

XDM instance

The term XDM instance is used, synonymously with the term value, to denote an unconstrained sequence of items.

XPath 1.0 compatibility mode

XPath 1.0 compatibility mode.This component must be set by all host languages that include XPath 3.1 as a subset, indicating whether rules for compatibility with XPath 1.0 are in effect. XQuery sets the value of this component to false.

XQuery 1.0 Processor

An XQuery 1.0 Processor processes a query according to the XQuery 1.0 specification.

XQuery 3.0 Processor

An XQuery 3.0 Processor processes a query according to the XQuery 3.0 specification.

XQuery 3.1 Processor

An XQuery 3.1 Processor processes a query according to the XQuery 3.1 specification.

XQuery 4.0 Processor

An XQuery 4.0 Processor processes a query according to the XQuery 4.0 specification.

XQuery version number

An XQuery version number consists of two integers, referred to as the major version number and the minor version number.

xs:anyAtomicType

xs:anyAtomicType is an atomic type that includes all atomic items (and no values that are not atomic). Its base type is xs:anySimpleType from which all simple types, including atomic, list, and union types, are derived. All primitive atomic types, such as xs:decimal and xs:string, have xs:anyAtomicType as their base type.

xs:dayTimeDuration

xs:dayTimeDuration is derived by restriction from xs:duration. The lexical representation of xs:dayTimeDuration is restricted to contain only day, hour, minute, and second components.

xs:error

xs:error is a simple type with no value space. It is defined in Section 3.16.7.3 xs:error ^XS11-1 and can be used in the 3.1 Sequence Types to raise errors.

xs:untyped

xs:untyped is used as the type annotation of an element node that has not been validated, or has been validated in skip mode.

xs:untypedAtomic

xs:untypedAtomic is an atomic type that is used to denote untyped atomic data, such as text that has not been assigned a more specific type.

xs:yearMonthDuration

xs:yearMonthDuration is derived by restriction from xs:duration. The lexical representation of xs:yearMonthDuration is restricted to contain only year and month components.

zero-digit

zero-digit(M) is the character used in the picture string to represent the digit zero; the default value is U+0030 (DIGIT ZERO, 0) . This character must be a digit (category Nd in the Unicode property database), and it must have the numeric value zero. This property implicitly defines the ten Unicode characters that are used to represent the values 0 to 9 in the function output: Unicode is organized so that each set of decimal digits forms a contiguous block of characters in numerical sequence. Within the picture string any of these ten character can be used (interchangeably) as a place-holder for a mandatory digit. Within the final result string, these ten characters are used to represent the digits zero to nine.

XQuery 4.0: An XML Query Language

W3C Editor's Draft 23 February 2026

Abstract

Status of this Document

Dedication

2 Basics

2.3 Processing Model

2.3.3 Expression Processing

2.3.3.2 Dynamic Evaluation Phase

3 Types

3.2 Item Types

3.2.8 Function, Map, and Array Types

3.2.8.3 Record Types

3.4 Coercion Rules

3.4.2 Implausible Coercions

4 Expressions

4.13 FLWOR Expressions

4.13.2 For Clause

4.14 Maps and Arrays

4.14.1 Maps

4.14.1.1 Map Constructors

4.14.3 Lookup Expressions

4.14.3.3 Deep Lookup

4.14.4 Filter Expressions for Maps and Arrays

G Glossary (Non-Normative)