This chapter covers the structure of queries in more detail. It discusses the query prolog and its various declarations. It then describes how to assemble queries from multiple modules, declare global variables, and define external functions.
An XQuery query is made up of two parts: a prolog and a body. The query prolog is an optional section that appears at the beginning of a query. The prolog can contain various declarations that affect settings used in evaluating the query. This includes namespace declarations, imports of schemas, variable declarations, function declarations, and other setting values. In a query module of any size, the prolog is actually likely to be much larger than the body.
Example 12-1 shows a query with a prolog containing several different types of declarations.
Example 12-1. A query prolog
xquery version "1.0";
declare default element namespace "http://datypic.com/cat";
declare boundary-space preserve;
declare default collation "http://datypic.com/collation/custom";
declare namespace ord = "http://datypic.com/ord";
import schema namespace prod="http://datypic.com/prod"
at "http://datypic.com/prod.xsd";
declare function local:getProdNums
($catalog as element( )) as xs:integer*
{for $prod in $catalog/product
return xs:integer($prod/number)};The query body is a single expression, but that expression can consist of a sequence of one or more expressions that are separated by commas. Example 12-2 shows a query body that contains a sequence of two expressions, a constructed element, and a FLWOR. The comma after the title element is used to separate the two expressions in the query body.
Example 12-2. A query body
<title>Order Report</title>,
(for $item in doc("order.xml")//item
order by $item/@num
return $item)The prolog consists of a series of declarations terminated by semicolon (;) characters. There are three distinct sections of the prolog.
The first declaration to appear in the query prolog is a version declaration, if it exists.
The second prolog section consists of setters, imports, and namespace declarations. Setters are the declarations listed in Table 12-1, along with a link to where they are covered fully in the book. Each kind of setter can only appear once. Imports and namespace declarations, listed in Table 12-2, can appear intermingled with setters in any order.
Table 12-1. Query prolog setters
|
Declaration |
Description |
Chapter |
|---|---|---|
|
Boundary-space |
How to process boundary whitespace in element constructors |
5 |
|
Ordering mode |
Whether the default order is document order or some implementation-dependent order |
7 |
|
Empty order |
Whether empty sequences should come first or last when ordered |
7 |
|
Copy-namespaces |
Whether nodes copied in constructors should copy namespaces from their parents |
10 |
|
Construction |
Whether nodes copied in constructors should be typed |
13 |
|
Default collation |
The default collation for string comparison |
17 |
|
Base URI |
The base URI of the static context |
20 |
Table 12-2. Query prolog imports and namespace declarations
|
Declaration |
Description |
Chapter |
|---|---|---|
|
Default namespace declaration |
Maps unprefixed names to a namespace for the entire scope of the query |
10 |
|
Namespace declaration |
Maps a prefix to a namespace for the entire scope of the query |
10 |
|
Module import |
Imports a function module from a specified location |
12 |
|
Schema import |
Imports a schema definition from a specified location |
13 |
The last section of the prolog consists of function, variable, and option declarations, listed in Table 12-3. They must appear after all the setters, imports, and namespace declarations.
Table 12-3. Query prolog variable and function declarations
|
Declaration |
Description |
Chapter |
|---|---|---|
|
Function declaration |
Declares a user-defined function |
8 |
|
Variable declaration |
Declares global variables |
12 |
|
Option declaration |
Declares implementation-specific parameters |
23 |
It is important to note that your processor might also be setting these values. For example, different XQuery implementations can choose to build in different default collations or different sets of predefined functions. In addition, an implementation might allow the user to specify these values outside the query—for example, using a command-line interface. Prolog declarations override or augment the default settings defined outside the scope of the query.
The first of the declarations in Example 12-1 is a version declaration, whose syntax is shown in Figure 12-1. The version declaration
is used to indicate the version of the XQuery language. 1.0 is the default (and the only allowed value), so it does not actually need to be explicitly specified, though it's recommended if you expect your query to be long-lived. If a version declaration does appear, it must appear first in the query, even before any comments.
The version declaration also allows you to specify a character encoding for the query itself using the encoding keyword and a literal string. For example, the following version declaration specifies an encoding of UTF-8:
xquery version "1.0" encoding "UTF-8";
Other example values for the encoding include UTF-16, ISO-8859-1, and US-ASCII. The way encoding is handled is somewhat implementation-dependent, in that processors are allowed to ignore the encoding value specified in the query if they have other knowledge about the encoding.
Because the encoding of a file can easily change unintentionally—for example, when you save it using a text editor—it's safest to stick to using ASCII characters in the query, using numeric character references for any non-ASCII characters.