Constructing Maps

Maps can be constructed in queries by using either a map constructor or a built-in function, as described in this section. They can also be created by parsing a JSON object, as described later in the chapter.

Using a map constructor

Example 24-1 shows a simple map constructor that creates a map containing three entries.

Example 24-1. A simple map constructor

xquery version "3.1";
map {
  "ACC": "Accessories",
  "WMN": "Women's",
  "MEN": "Men's"
}

Figure 24-1 shows the syntax for a map constructor.

Figure 24-1. Syntax of a map constructor

The map constructor contains a map keyword followed by curly braces that surround zero or more pairs of expressions that identify the key and the value. The key and value expressions are separated by a colon, and the entries are separated by commas.

Before the colon, the key expression can be any XQuery expression that results in a single atomic value, after atomization. In Example 24-1, the key expressions are just string literals, but it could be a more complex expression, such as a function call or a path expression. The keys can have any atomic data type, and it is even possible (but fairly unusual) to have keys in the same map that have a variety of data types. Because the keys must be unique, a map cannot contain two key values that are equal when taking into account their data types, or error XQDY0137 is raised.

After the colon, the value expression can be any XQuery expression and there is no limitation that it must return an atomic value. The value associated with a key can be a node, an array, a sequence of multiple items, or even another map. Example 24-2 shows a map constructor where the map values are nested maps.

Example 24-2. Nested maps

xquery version "3.1";
map {
    "ACC": map {
              "name": "Accessories",
              "code": 300 },
    "WMN": map {
              "name": "Women's",
              "code": 310 },
    "MEN": map {
              "name": "Men's",
              "code": 320 } 
    }

xquery version "3.1";
declare namespace map = "http://www.w3.org/2005/xpath-functions/map";
map:merge(for $p in doc("catalog.xml")//product
          return map:entry(string($p/number), string($p/name)) )

Looking Up Map Values

Given a map, there are several ways to look up the value for a particular key. For the purposes of this section, assume that the global variables shown in Example 24-4 are declared.

xquery version "3.1";
declare variable $deptnames := map {
  "ACC": "Accessories",
  "WMN": "Women's",
  "MEN": "Men's"
};
declare variable $deptinfo := map {
  "ACC": map {
            "deptname": "Accessories",
            "deptnum": 300 },
  "WMN": map {
            "deptname": "Women's",
            "deptnum": 310 },
  "MEN": map {
            "deptname": "Men's",
            "deptnum": 320 } 
};

xquery version "3.1";
declare variable $deptnames := map {
  "ACC": "Accessories",
  "WMN": "Women's",
  "MEN": "Men's"
};
for $prod in doc("catalog.xml")//product
return <product num="{$prod/number}" 
                dept-name="{$deptnames($prod/@dept)}"/>

<product num="557" dept-name="Women's"/>
<product num="563" dept-name="Accessories"/>
<product num="443" dept-name="Accessories"/>
<product num="784" dept-name="Men's"/>

xquery version "3.1";
declare variable $deptinfo := map {
  "ACC": map {
            "deptname": "Accessories",
            "deptnum": 300 },
  "WMN": map {
            "deptname": "Women's",
            "deptnum": 310 },
  "MEN": map {
            "deptname": "Men's",
            "deptnum": 320 } 
};
for $prod in doc("catalog.xml")//product
return <product num="{$prod/number}"
                dept-name="{$deptinfo($prod/@dept)("deptname")}"
                dept-code="{$deptinfo($prod/@dept)("deptnum")}"/>

<product num="557" dept-name="Women's" dept-code="310"/>
<product num="563" dept-name="Accessories" dept-code="300"/>
<product num="443" dept-name="Accessories" dept-code="300"/>
<product num="784" dept-name="Men's" dept-code="320"/>

$deptnames?("ACC")

$deptnames?("ACC", "MEN")

for $d in ("ACC", "MEN") return $deptnames($d)

$deptnames?(doc("catalog.xml")//@dept)

declare variable $map-with-integer-keys := map{ 10:"a", 20:"b"};

$deptnames?ACC

xquery version "3.1";
declare variable $deptinfo := map {
  "ACC": map {
            "deptname": "Accessories",
            "deptnum": 300 },
  "WMN": map {
            "deptname": "Women's",
            "deptnum": 310 },
  "MEN": map {
            "deptname": "Men's",
            "deptnum": 320 } 
};
for $prod in doc("catalog.xml")//product
return <product num="{$prod/number}"
                dept-name="{$deptinfo?($prod/@dept)?deptname}"
                dept-code="{$deptinfo?($prod/@dept)?deptnum}"/>

$deptinfo?*[?deptname = "Accessories"]

$deptinfo?*[?deptname = "Accessories"]?deptnum

Querying Maps

In addition to being able to look up values in a map based on keys, there are several built-in functions that allow you to query other aspects of maps.

map:size

Returns the number of entries in a map. For example, map:size($deptnames) returns the integer 3.

map:contains

Tests whether a map contains an entry with a particular key. For example, map:contains($deptnames, "ACC") returns true, and map:contains($deptnames, "FOO") returns false.

map:find

Recursively searches a sequence for map entries with a particular key and returns their values as an array. For example, map:find($deptinfo, "deptnum") returns [300, 310, 320].

map:keys

Returns a sequence of all the keys in the map, in no particular order. For example, map:keys($deptnames) returns the sequence of three strings ("ACC", "MEN", "WMN").

deep-equal

Compares the values of two items, which can include maps. If the two maps have the same number of entries with the same keys and values (regardless of the order of the entries), this function will return true.

Changing Maps

Built-in functions are provided to make changes to maps, for example, adding and removing entries, or merging entries. As with all XQuery functions, the original map(s) passed to these functions are unchanged; the “changed” map is an entirely new map returned by the function.

map:put

Adds an entry to a map, or replaces an entry if that key already exists in the map. For example, map:put($deptnames, "SHO", "Shoes") returns a map that is identical to $deptnames except that it has an additional entry whose key is SHO and whose value is Shoes. The function call map:put($deptnames, "ACC", "Other") returns a map that is identical to $deptnames except that the entry whose key is ACC has a value of Other instead of Accessories.

map:remove

Removes an entry from a map. For example, map:remove($deptnames, "ACC") returns a map that is identical to $deptnames except that it no longer has an entry whose key is ACC.

map:merge

Merges the entries in multiple maps. It was described earlier in the chapter as a way to create new variable-size maps in conjunction with the map:entry function. This function is also useful in general any time two or more maps need to be merged. For example, map:merge( ($deptnames, $deptnames2) ) returns a union of all the entries in $deptnames and $deptnames2. A second $options parameter can be used to specify what to do if there are duplicate keys in the maps.

Iterating over Entries in a Map

The map:for-each function is useful if you want to iterate over all the entries in a map, and perform the same function on each entry. The first argument is the map itself, and the second argument is the function. The provided function must accept two arguments, representing the key and the value. For example, if you wanted to create a sequence of strings listing all the key/value pairs in a map, you could use the query shown in Example 24-8.

xquery version "3.1";
declare namespace map = "http://www.w3.org/2005/xpath-functions/map";
declare variable $deptnames := map {
  "ACC": "Accessories",
  "WMN": "Women's",
  "MEN": "Men's"
};
let $f := function($k, $v) 
  {concat('Key: ', $k, ', value: ', $v)}
return map:for-each($deptnames, $f)

("Key: ACC, value: Accessories",
 "Key: WMN, value: Women's",
 "Key: MEN, value: Men's")

Maps and Sequence Types

Sequence types can be used to describe maps. This is useful if, for example, you would like to write a user-defined function that accepts a map as a parameter. The syntax for a map test is shown in Figure 24-2.

Figure 24-2. Syntax of a map test

The generic test map(*) can be used to specify any map, regardless of the types of the keys or values. A more specific sequence type specifies the types of the keys and values allowed in the map. For example, map(xs:integer, xs:string) matches a map where every key matches the sequence type xs:integer and every value matches the sequence type xs:string. For the type of the key, the only allowed sequence type is the name of an atomic or union type, because keys must be atomic values. For the type of the entry, any sequence type can be used, including the very generic item()*. The sequence type could even be another map test. For example, the $deptinfo map defined in Example 24-4 matches the map test:

map(xs:string, map(xs:string, xs:anyAtomicType))

because each value in the map is itself a map whose keys are strings and whose values are either strings or integers.

Sequence types, which are discussed in detail in “Sequence Types”, are used in a variety of XQuery expressions to indicate allowed values. The most common use is in the signatures of user-defined functions. For example, to write a function that takes a map and returns those keys that are greater than 50, you could use the function shown in Example 24-9. The use of the map(xs:integer, item()*) sequence type in the function signature ensures that only a single map whose keys are all integers are passed to this function as the $maparg argument.

xquery version "3.1";
declare namespace map = "http://www.w3.org/2005/xpath-functions/map";
declare function local:large-keys
  ($maparg as map(xs:integer, item()*)) as xs:integer* {
   map:keys($maparg)[. > 50]
};
local:large-keys(map {10:"a", 55:"b", 60:"c"})

(55, 60)

Because a map is a special kind of function, it will also match function tests whose syntax is shown in Figure 23-1. It will match the generic function test function(*) as well as a more specific one that matches the function signature of a map, namely function(xs:anyAtomicType) as item()*. This means that a map can be passed as an argument to higher-order functions that expect a function item as one of their arguments. A map will also match the generic item() sequence type.

Constructing Arrays

An array constructor is used to create an array. There are two distinct varieties of array constructors: the square array constructor and the curly array constructor. For example, a simple square array constructor that creates an array containing three entries looks like this:

[ "a", "b", "c" ]

It simply consists of square brackets surrounding zero or more expressions that are separated by commas. An equivalent curly array constructor looks like this:

array { "a", "b", "c" }

It uses the keyword array followed by curly braces surrounding the expressions. It is important to note that the curly array constructor differs from the square array constructor in the way it determines the members. With a square array constructor, the comma is considered a hard delimiter between members, where each expression returns the value for a single member. The following square array constructor creates an array with two members:

[("a", "b"), "c"]

The first is a sequence of the strings a and b, and the second is the string c. By contrast, the following curly array constructor creates an array with three members (the strings a, b, and c):

array { ("a", "b"), "c" }

The difference is that the expression within curly braces is resolved into a flat sequence of three items first, and then a member is created for each item.

The previous examples use strings as array values, but any expression is valid, so you can have an array of values of other atomic types, or of nodes, function items, maps, or other arrays. There is no requirement that all the members of the array have the same type, so you could create a mixture, for example:

[$myitems, doc("catalog.xml")//product, 
  12, xs:date('2015-01-15'), <foo>bar</foo>]

Using either syntax, you can create an array that contains an array, as in:

array { ["a", "b"], "c" }

or:

[ ["a", "b"], "c" ]

In both of these cases, the outer array has two members: an array, and the string c.

Arrays Versus Sequences

In some ways, it may seem that arrays and sequences are the same thing: they are both ordered lists of items. The main difference is that sequences of items are automatically flattened in XQuery. There is no such thing as sequences of sequences in the data model. Arrays, by contrast, can have members that are other arrays, or sequences of multiple items. For example, the following array constructor creates an array with two members, the first is a sequence of three strings and the second is the string d:

[ ("a", "b", "c"), "d" ]

The items are not flattened to create an array with four members. In contrast, suppose you construct a sequence using similar syntax, but with parentheses instead of square brackets, as in:

( ("a", "b", "c"), "d" )

In this case, the inner sequence is flattened so you end up with a sequence of four strings. However, an array within a sequence is retained, for example in the following:

( ["a", "b", "c"], "d" )

The result is a sequence of two items, the first being an array with three members, and the second being the string d.

Some XQuery expressions that iterate over sequences will give surprising results when used with arrays, because arrays are considered items whereas sequences are not. For example:

for $x in (1,2) return $x + 1

will return a sequence of integers (2,3), but:

for $x in [1,2] return $x + 1

will raise a type error because $x is bound to the entire array, not each member in turn. The return clause, which is evaluated only once, is trying to add 1 to the entire array. Similarly, count([1,2]) will return 1 because the argument is a single item, the array itself. (You can use the array:size function instead.) This also means that positional predicates do not work as expected on arrays. For example:

let $a := [1,2] return $a[1]

will return the entire array, not the first member.

Arrays and Atomization

During atomization, an array is flattened and converted into a sequence of the atomized values of its members. This is most common when calling functions that expect atomic values. For example, it is possible to pass an array to the distinct-values function, as in:

distinct-values( [1,2,3,1] )

This will return the distinct values of the members of the array. The flattening process is recursive, so the following will work as well:

distinct-values( [1,2, [3,1] ] )

returning the sequence (1,2,3). Similarly, sum( [1,2] ) will work as you might expect (returning the value 3) because the sum function expects a sequence of atomic values as its argument, so the array is atomized into a sequence of integers 1 and 2. This works differently from the count example in the previous section because the count function accepts a sequence of any items, not just atomic values, so no atomization takes place.

Looking Up Array Values

Given an array, there are several ways to retrieve the member in a particular position (index) in the array. Using all of these methods, specifying a position that is larger than the number of members in the array will raise error FOAY0001. In XQuery, the first member is in position 1, not 0 as in some programming languages. For the purposes of this section, assume that the global variables shown in Example 24-10 are declared.

xquery version "3.1";
declare variable $array-of-ints := [10, 20, 30];
declare variable $array-of-arrays := [ ["a", "b", "c"], ["d", "e", "f"] ];

$array-of-ints?(2)

$array-of-ints?(2, 3)

for $i in (2, 3) return $array-of-ints($i)

$array-of-ints?(1 to 2)

Querying Arrays

In addition to being able to retrieve a value in an array based on its position, there are several built-in functions that allow you to query other aspects of arrays.

array:size

Returns the number of members in an array. For example, array:size($array-of-ints) returns the integer 3.

array:head

Returns the first member of an array. For example, array:head($array-of-ints) returns the integer 10.

array:tail

Returns an array without its first member. For example, array:tail($array-of-ints) returns the array [20, 30].

deep-equal

Compares two items, which can include arrays. If the two arrays have the same number of members with equal values (taking into account their data types), in the same order, this function will return true.

Changing Arrays

Built-in functions are provided to make changes to arrays, for example adding and removing members, or joining arrays. As with all XQuery functions, the original array(s) passed to these functions are unchanged; the “changed” array is an entirely new array returned by the function.

array:append

Adds one member to the end of the array. For example, array:append($array-of-ints, 40) returns the array [10, 20, 30, 40].

array:insert-before

Inserts one member into a specified position in an array. For example, array:insert-before($array-of-ints, 2, 40) returns the array [10, 40, 20, 30].

array:put

Replaces one member at a specified position in an array. For example, array:put($array-of-ints, 2, 40) returns the array [10, 40, 30].

array:remove

Removes a member from an array. For example, array:remove($array-of-ints, 2) returns the array [10, 30].

array:subarray

Returns a subset of an array based on a starting position and length. For example, array:subarray($array-of-ints, 2, 2) returns two members from $array-of-ints, starting with position 2, so the result is the array [20, 30].

array:filter

Applies a function to each member in an array and returns an array containing those members for which the function returns true. For example, array:filter($array-of-ints, function($n) {$n > 15}) returns [20, 30] because those are the members of $array-of-ints that are greater than 15.

array:flatten

Turns arrays into sequences of items, recursively flattening any arrays that are within arrays. For example, array:flatten($array-of-arrays) returns a sequence of six strings: "a", "b", "c", "d", "e", "f".

array:join

Merges the members in multiple arrays into a single array, retaining the order. For example, array:join( ($array-of-ints, ["a", "b", "c"]) ) returns an array with six members: [10, 20, 30, "a", "b", "c"].

array:sort

Sorts the members of an array, optionally allowing you to pass it a function that determines the sort key. For example, array:sort([6, 2, -4], (), abs#1) returns [2, -4, 6] because the members are sorted on the result of the abs (absolute value) function.

array:reverse

Reverses the order of members of an array. For example, array:reverse($array-of-ints) returns [30, 20, 10].

Arrays and Sequence Types

Sequence types can be used to describe arrays. This is useful if, for example, you would like to write a user-defined function that accepts an array as a parameter. The syntax for an array test is shown in Figure 24-3.

Figure 24-3. Syntax of an array test

The generic test array(*) can be used to specify any array, regardless of the types of the members. A more specific sequence type specifies the types of the members allowed in the array. For example, array(xs:integer) matches an array where every member matches the sequence type xs:integer. Any sequence type is allowed, so it could, for example, match a sequence of multiple nodes, as in array(node()*), where each member can be the empty sequence or one or more nodes of any kind. The sequence type could even be another array test. For example, the $array-of-arrays array defined in Example 24-10 matches the array test array(array(xs:string)) because each member in the array is itself an array whose members are strings.

Sequence types, which are discussed in detail in “Sequence Types”, are used in a variety of XQuery expressions to indicate allowed values. The most common use is in the signatures of user-defined functions. For example, to write a function that takes an array and returns those members that are greater than 50 as a sequence, you could use the function shown in Example 24-11. The use of the array(xs:integer) sequence type in the function signature ensures that only a single array whose members are all integers are passed to this function as the $arrayarg argument.

xquery version "3.1";
declare namespace array = "http://www.w3.org/2005/xpath-functions/array";
declare function local:larger-values
  ($arrayarg as array(xs:integer))as xs:integer* {
   array:flatten($arrayarg)[. > 15]
};
local:larger-values([10, 20, 30])

Because an array is a special kind of function, it will also match function tests whose syntax is shown in Figure 23-1. It will match the generic function test function(*) as well as a more specific one that matches the function signature of an array, namely function(xs:integer) as item()*. This means that an array can be passed as an argument to higher-order functions that expect a function item as one of their arguments. An array will also match the generic item() sequence type.

Parsing JSON

Using XQuery, it is possible to parse a JSON document to retrieve an instance of the XQuery data model that can then be queried and manipulated. This is accomplished using the json-doc function, which parses a document associated with the supplied URI, and returns it as a sequence of items. Typically those items will be maps, but they could also be, for example, strings or arrays. The mapping shown in Table 24-1 tells you what you can expect as output of this function.

Given the following input document called product.json:

{
   "number": 557,
   "name": "Fleece Pullover",
   "colorChoices": ["navy", "black"],
   "is-current": true,
   "other": null
}

The function call json-doc("product.json") will return a map equivalent to the document, as in:

map {
   "number": xs:double(557),
   "name": "Fleece Pullover",
   "colorChoices": ["navy", "black"],
   "is-current": true(),
   "other": ()
}

Another function, parse-json, will convert a string that is in JSON syntax into a sequence of items. It generally has the same behavior as json-doc. In fact, the function call json-doc("uri") is the same as the function call parse-json(unparsed-text("uri")).

Serializing JSON

You can serialize the results of your query as a JSON document by choosing the serialization method json. Generally, the mapping is the same as shown in Table 24-1, in the opposite direction. For example, map items are serialized as JSON objects, and boolean values are serialized using the JSON tokens true and false.

However, you may have some items to serialize that are not easily mapped to the JSON model. When you attempt to serialize XML nodes as JSON, they are turned into strings. By default, the string will look like an XML document, but you can use the json-node-output-method serialization parameter to make it look like text or HTML.

In Example 24-12, the map has an entry, properties, whose value is an XML element. When serializing this node to JSON, it is turned into a string as shown by the quotes around the props element in the result.

xquery version "3.1";
declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization"; 
declare option output:method "json";
declare option output:indent "yes";
map {
   "number": 557,
   "props":
     <props>
       <length>31</length>
     </props>
}

{
   "number": 557,
   "props":
     "<props>
  <length>31</length>
</props>"
}

Some instances of the XQuery data model cannot be serialized as JSON at all. One of these is a sequence of multiple items, which will raise error SERE0023. This error can be avoided by turning the sequence into an array before serialization. Function items that are not maps or arrays also cannot be serialized as JSON; attempting to do so will raise error SERE0021.

Converting Between JSON and XML

Two functions, json-to-xml and xml-to-json, allow conversion between JSON and an XML structure that is analogous to JSON, with elements like map and string. Example 24-13 shows a JSON document and a corresponding XML document.

{   "number": 557,
   "name": "Fleece Pullover",
   "colorChoices": ["navy", "black"],
   "is-current": true,
   "other": null,
   "priceInfo": {
       "price": 19.99,
       "discount": 10.00
       }
}

<map xmlns="http://www.w3.org/2005/xpath-functions">
   <number key="number">557</number>
   <string key="name">Fleece Pullover</string>
   <array key="colorChoices">
      <string>navy</string>
      <string>black</string>
   </array>
   <boolean key="is-current">true</boolean>
   <null key="other"/>
   <map key="priceInfo">
      <number key="price">19.99</number>
      <number key="discount">10.00</number>
   </map>
</map>

json-to-xml will take JSON, as a string, and create the equivalent XML shown in the example. xml-to-json will do the opposite: convert the XML shown into the JSON string.

Each JSON construct is represented by a different element name. Table 24-2 provides a list of these elements and their allowed content. For name/value pairs within an object, a key attribute is used to hold the name. The XML elements are in the namespace http://www.w3.org/2005/xpath-functions.

Two additional attributes, related to escaping, are allowed in the XML. The escaped attribute is used on a string element if the contents of the string are JSON-escaped. The escaped-key attribute appears on any element that has a key attribute, to indicate that the value of the key attribute is JSON-escaped.

Converting JSON to this XML structure by using json-to-xml is preferable to converting it to a map (as is done by the parse-json function) in cases where sophisticated queries need to be performed on that data. If you just need to retrieve the price for a particular product, a map will work fine, because you can chain together map lookups to retrieve the necessary data.

However, sometimes it is useful to have the full power of XPath to query the data. If the JSON structure is flexible, you may need to look for price values at any level in the hierarchy, using // in your path expression. Another case is when you need to use other axes, like parent:: or preceding-sibling::.