The syntax of a variable declaration is shown in Figure 12-4. For example, the declaration:

declare variable $maxItems := 12;

binds the value 12 to the variable $maxItems.

Figure 12-4. Syntax of a variable declaration^[a]

 define variable $maxItems {12}

Some popular XQuery implementations still use this old syntax.

The processor evaluates all variable declarations in the order they appear, before it evaluates the query body. When a variable declaration is evaluated, the variable is bound to a specific value.

After a variable is bound, you can reference that variable anywhere in the query. If a function body references a variable that is declared in the prolog, the function declaration must appear after the variable declaration. Similarly, if one global variable references another, the referencing variable must come after the referenced variable. This differs from functions referencing other functions, where forward references are allowed.

As with all other XQuery variables, a variable can only be bound once. Therefore, you cannot declare a variable in the prolog and then set its value later, for example, in a let expression. If you attempt to do this, it will be considered an entirely new variable with the same name and a smaller scope (the FLWOR).

Each variable declaration specifies a unique variable name. Variables have qualified names, meaning that they can be associated with a namespace. In the main module, variable declarations can have either unprefixed or prefixed names. If they have unprefixed names, they are not in any namespace, since variable names are not affected by default namespace declarations. If they are prefixed, they can be associated with any namespace that was also declared in the prolog.

In library modules, on the other hand, the names of declared variables must be in the target namespace of the module. Since default namespace declarations do not apply to variable names, this means that they must be prefixed, with a prefix mapped to the target namespace. This applies only to the variables that are declared in the prolog. If other variables are bound inside a function body, for example in let clauses, they can be in no namespace (unprefixed) or associated with a namespace other than the target namespace.

The expression that specifies the value of the variable is known as the initializing expression. In the previous example, it was 12. It does not have to be a constant; it can be any valid XQuery expression. For example:

declare variable $firstNum := doc("catalog.xml")//product[1]/number;

binds the value of the first product number in the catalog to the $firstNum variable.

The initializing expression can call any function that is declared anywhere in the module or in an imported module. However, it can only reference variables that are declared before it. The following example is invalid because the initializing expression of $firstNum references a variable that is declared later:

declare variable $firstNum := $firstProd/number;
declare variable $firstProd := doc("catalog.xml")//product[1];

Neither can the declarations be circular. For example, an initializing expression cannot call a function that itself references the variable being initialized.

External variables are variables whose values are bound by the processor outside the scope of the query. This is useful for parameterizing queries. For example, an external variable might allow a query user to specify the maximum number of items she wants returned from the query.

To declare an external variable, you use the keyword external instead of an initializing expression, as in:

declare variable $maxItems external;

In this case, the processor must have bound $maxItems to a value before the query is evaluated. Consult the documentation of your XQuery implementation to determine exactly how you can specify the values of external variables outside the query. It may allow them to be specified on a command-line interface or set programmatically.

Note that external variables are not the same thing as variables that are imported from other XQuery modules. Variables from imported modules do not need to be redeclared in the importing module.