XQuery 4.0: An XML Query Language

4.13.3 Let Clause

The purpose of a let clause is to bind values to one or more variables. Each variable is bound to the result of evaluating an expression.

If a let clause declares multiple variables separated by commas, it is semantically equivalent to multiple let clauses, each containing a single variable. For example, the clause

let $x := $expr1, $y := $expr2

is semantically equivalent to the following sequence of clauses:

let $x := $expr1
let $y := $expr2

After performing this expansion, the effect of a let clause is as follows:

1. If the let expression uses multiple variables, it is first expanded to a set of nested let expressions, each of which uses only one variable. Specifically, any separating comma is replaced by let.

   Example:

   The expression:

   let $x := 4, $y := 3 return $x + $y

   is expanded to:

   let $x := 4 let $y := 3 return $x + $y

2. In a LetValueBinding such as let $V as T := EXPR:

   1. The variable V is declared as a range variable.

   2. The sequence type T is called the declared type. If there is no declared type, then item()* is assumed.

   3. The expression EXPR is evaluated, and its value is converted to the declared type by applying the coercion rules. The resulting value forms the binding sequence for the range variable.

3. In a LetSequenceBinding such as let $( $A1 as T1, $A2 as T2, ... , $An as Tn ) as ST := EXPR:

   1. The sequence type ST is called the declared sequence type. If there is no declared sequence type, then item()* is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared sequence type ST by applying the coercion rules. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n-1) is effectively replaced by a LetValueBinding of the form let Ai as Ti := items-at(V, i). That is, a range variable named A_i is declared, whose binding sequence is the item V[ i ], after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()?).

   4. The last variable A_n is effectively replaced by a LetValueBinding of the form let An as Tn := subsequence(V, n). That is, the last variable is bound to the rest of the binding sequence (or to the empty sequence if the binding sequence has fewer items than the number of variables).

   Note:

   For any variable A_i, including the last, if i exceeds the length of the sequence V, then A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

   Note:

   It is permissible to bind several variables with the same name; all but the last are occluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the subsequence starting at the third item, while causing the first two items to be ignored.

   Example:

   The expression:

   let $( $a, $b as xs:integer, $local:c ) := (2, 4, 6)
   return $a + $b + $local:c

   is expanded to:

   let $temp := (2, 4, 6)
   let $a := fn:items-at($temp, 1)
   let $b as xs:integer := fn:items-at($temp, 2)
   let $local:c := fn:subsequence($temp, 3)
   return $a + $b + $local:c

   where $temp is some variable name that is otherwise unused.

    

   Example:

   Consider the element $E := <e A="p q r" B="x y z"/>, where $E has been validated against a schema that defines both attributes A and B as being lists of strings.Consider the element $E := <e A="p q r" B="x y z"/>.Consider the element $E := <e A="p q r" B="x y z"/>, where $E has been validated against a schema that defines both attributes A and B as being lists of strings.

   Then the expression:

   Then the expression:

   let $( $a, $b ) := $E/(@A, @B)

   binds $a to the attribute node A="p q r", and $b to the attribute node B="x y z".

   If type declarations are added to the individual variables, thus:

   let $( $a as xs:string, $b as xs:string ) := $E/(@A, @B)

   then the attributes are atomized, so that $a is bound to the string "p q r", and $b to the string "x y z".

   The same result is achieved if a type declaration is added for the sequence as a whole:

   let $( $a, $b ) as xs:string* := $E/(@A, @B)

   Now consider the case where the same element $E is validated against a schema that defines both attributes as lists of strings.

   Then the raw expression, without type declarations:

   let $( $a, $b ) := $E/(@A, @B)

   still binds $a and $b to the two attribute nodes (the only difference being that the typed value of each attribute is now a sequence of three strings).

   If type declarations are added to the individual variables, thus:

   let $( $a as xs:string*, $b as xs:string* ) := $E/(@A, @B)

   binds $a to the sequence ("p", "q", "r") and $b to the sequence ("x", "y", "z"). The evaluation of the expression $E/(@A, @B) returns a sequence of two attribute nodes; the value of $a is formed by atomizing the first of these nodes, while $b is formed by atomizing the second.

   then $a is bound to the result of atomizing the first attribute (that is, to the sequence of three strings ("p", "q", "r")), while $b is bound to the result of atomizing the second attribute (that is, to the sequence of three strings ("x", "y", "z")).

   If however, a type declaration is added for the sequence as a whole, namely:

   let $( $a, $b ) as xs:string* := $E/(@A, @B)

   then the binding sequence is a sequence of six strings, ("p", "q", "r", "x", "y", "z"). The variable $a is bound to the first string, "p", while $b is bound to the remaining five strings, ("q", "r", "x", "y", "z").

    

   Example:

   Consider transforming the string "Nf3 Nf6 c4 g6 Nc3 Bg7 d4 O-O Bf4 d5" (notation for the start of a chess game) to the form (["Nf3", "Nf6",] ["c4", "g6"], [ "Nc3", "Bg7"], [ "d4", "O-O"], ["Bf4", "d5"]). This can be achieved as follows:Consider transforming the string "Nf3 Nf6 c4 g6 Nc3 Bg7 d4 O-O Bf4 d5" (notation for the start of a chess game) to the form (["Nf3", "Nf6"], ["c4", "g6"], ["Nc3", "Bg7"], ["d4", "O-O"], ["Bf4", "d5"]). This can be achieved as follows:Consider transforming the string "Nf3 Nf6 c4 g6 Nc3 Bg7 d4 O-O Bf4 d5" (notation for the start of a chess game) to the form (["Nf3", "Nf6",], ["c4", "g6"], [ "Nc3", "Bg7"], [ "d4", "O-O"], ["Bf4", "d5"]). This can be achieved as follows:

   declare function local:grouped-moves($moves) {
      if (exists($moves)) {
        let $($m1, $m2, $rest) := $moves
        return [$m1, $m2], local:grouped-moves($rest)
     }
   };
   local:grouped-moves(tokenize("Nf3 Nf6 c4 g6 Nc3 Bg7 d4 O-O Bf4 d5"))

   declare function local:grouped-moves($moves) {
      if (exists($moves)) {
         let $($m1, $m2, $rest) := $moves
         return [$m1, $m2], local:grouped-moves($rest)
      }
   };
   local:grouped-moves(tokenize("Nf3 Nf6 c4 g6 Nc3 Bg7 d4 O-O Bf4 d5"))

4. In a LetArrayBinding such as let $[ $A1 as T1, $A2 as T2, ... , $An as Tn ] as AT := EXPR:

   1. The sequence type AT is called the declared array type. If there is no declared array type, then array(*) is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared array type AT by applying the coercion rules. A type error [err:XPTY0004] is raised if the result is not a singleton array. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := array:get(V, i). That is, a range variable named A_i is declared, whose binding sequence is the array member V ? i, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).

      Note:

      If i exceeds the length of the array V, then an error [err:FOAR0001]^FO is raised.

      Note:

      It is permissible to bind several variables with the same name; all but the last are occluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.

      Example:

      The expression:

      let $[ $a, $b as xs:integer, $local:c ] := [ 2, 4, 6 ]
      return $a + $b + $local:c

      is expanded to:

      let $temp := [ 2, 4, 6 ]
      let $a := array:get($temp, 1, ())
      let $b as xs:integer := array:get($temp, 2)
      let $local:c := array:get($temp, 3, ())
      return $a + $b + $local:c

      where $temp is some variable name that is otherwise unused.

5. In a LetMapBinding such as let ${ $A1 as T1, $A2 as T2, ... , $An as Tn } as MT := EXPR:

   1. The sequence type MT is called the declared map type. If there is no declared map type, then map(*) is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared map type MT by applying the coercion rules. A type error [err:XPTY0004] is raised if the result is not a singleton map. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := map:get(V, "Ni", ()), where N_i is the local part of the name of the variable A_i. That is, a range variable named A_i is declared, whose binding sequence is the value of the map entry in V whose key is an xs:string (or xs:anyURI or xs:untypedAtomic) equal to the local part of the variable name, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).

      Note:

      If there is no entry in the map with a key corresponding to the variable name, then the variable A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

      Note:

      It is not possible to use this mechanism to bind variables to values in a map unless the keys in the map are strings in the form of NCNames.

      Example:

      The expression:

      let ${ $a, $b as xs:integer, $local:c } := { "a": 2, "b": 4, "c": 6, "d": 8 }
      return $a + $b + $local:c

      is expanded to:

      let $temp := { "a": 2, "b": 4, "c": 6 }
      let $a := map:get($temp, "a", ())
      let $b as xs:integer := map:get($temp, "b", ())
      let $local:c := map:get($temp, "c", ())
      return $a + $b + $local:c

      where $temp is some variable name that is otherwise unused.

6. The effect of the LetClause is to add one or more variable bindings to the tuple stream. Specifically, each range variable declared within the LetClause is bound to its corresponding binding sequence, and the resulting variable binding is added to the current tuple, replacing any existing variable binding with the same variable name.

   If the LetClause is the initial clause in a FLWOR expression, it creates an initial tuple for the tuple stream, containing these variable bindings. This tuple stream serves as input to the next clause in the FLWOR expression.

   If the LetClause is an intermediate clause in a FLWOR expression, it adds the relevant variable bindings to each tuple in the input tuple stream. The resulting tuples become the output tuple stream of the let clause.

   The number of tuples in the output tuple stream of an intermediate let clause is the same as the number of tuples in the input tuple stream. The number of variable bindings in the output tuples is always greater than the number of variable bindings in the input tuples, unless the input tuples already contain bindings for every variable binding created by the LetClause; in this case, the new binding for any given variable name occludes (replaces) an earlier binding for that variable name, and the number of bindings is unchanged.

The semantics of type declarations are further defined in 4.13.1 Variable Bindings.

The following code fragment illustrates how a for clause and a let clause can be used together. The for clause produces an initial tuple stream containing a binding for variable $d to each department number found in a given input document. The let clause adds an additional binding to each tuple, binding variable $e to a sequence of employees whose department number matches the value of $d in that tuple.

for $d in doc("depts.xml")/depts/deptno
let $e := doc("emps.xml")/emps/emp[deptno eq $d]