Introduction to XQuery (Part 4 of 4) : Page 3

Using XQuery's Built-in Functions
XQuery provides a set of built-in functions for number (integer, short, float, double), string, Boolean, datetime, Qname, node and sequence data types.

You can augment the built-in function library by defining your own functions.

Here are some of the most useful built-in functions.

Document() function. Function document(string uri) returns the root node of the referenced document. The URI reference format is implementation dependent. The Ipedo XML Database XQuery implementation uses collectionname/documentname as the parameter to the document() function. For example, document("data/PO.xml") returns the root node of the document PO.xml in the collection named data in an Ipedo XML Database.

Aggregate functions. XQuery provides count, avg, max, min and sum aggregate functions. Function count returns the number of items in the sequence. Function avg returns the average (mean) of a sequence of numbers. Function sum returns the sum of a sequence of numbers. Function max returns the number with maximum value from a sequence while function min returns the number with minimum value.

For example, the following query calculates the number of items in the purchase order 0002.

   # --see XQuery44.ixq in samples.zip
   let $po2 := document("data/PO.xml")//po[@id='0002']
   let $items := $po2/lineitems/lineitem/item
   return 
   <itemCount> {count($items) } </itemCount>

In the preceding XQuery, the variable $po2 represents the purchase order with purchase order id 0002. The variable $items represents all items in the purchase order —in other words, a sequence of node item. The function count($items) returns the count of item in that sequence. The return clause constructs an element that looks like this:

<itemCount> 2 </itemCount>

As another example, the following query calculates the average unit price of all items in the purchase order 0002.

   # --see XQuery45.ixq in samples.zip
   let $po2 := document("data/PO.xml")//po[@id='0002']
   let $unitprices := $po2/lineitems/lineitem/item/price
   return 
   <averageprice> {avg($unitprices) } </averageprice>

The result looks like this:

   <averageprice> 105.575 </averageprice>

String functions. XQuery provides the following string functions: concat, starts-with, ends-with, contains, substring, string-length, normalize, upper-case, and lower-case.

The function starts-with(str1, str2) returns true if beginning of str1 matches the characters in str2. The function ends-with(str1, str2) returns true if the ending characters in str1 match the characters in str2. The function contains(str1, str2) returns true if the str1 contains str2.

The following query uses the contains() function to find items in the document items.xml whose description contains "Ping Pong".

   # --see XQuery46.ixq in samples.zip
   for  $i in document("data/items.xml")//item
   where contains($i/description, "Ping Pong")
   return $i

Node function. XQuery's node-equal, node-before, node-after, copy, and shallow functions act specifically on nodes. The function node-equal provides functionality equivalent to the == and !== operators for nodes. The node-before function works the same way as the << operator. The node-after function backs up the >> operator, and the node-equal() function returns true if two nodes have the same identity; otherwise it returns false.

The copy() function copies a node including its attribute and descendents. Those of you familiar with XSLT—be careful! The XQuery copy() function produces a deep copy—the equivalent of <xsl:copy-of> in XSLT. The following examples illustrate the process of copying nodes in XQuery.

   # Query listing - XQuery47.ixq in samples.zip
   let $customer := 
      document("data/customers.xml")//customer
      [custno='1001]
   let $customercopy := copy($customer)
   return node-equal($customer, $customercopy)

In the preceding example query, the variable $customer represents the customer element with customer number 1001. The variable $customercopy will hold a copy of that customer node. The expression copy($customer) creates a node that is a deep copy of the value of variable $customer but gives it a different node identity, so node-equal($customer, $customercopy) returns false.

In contrast, the shallow() function copies a node and its attributes, but not its descendents.

   # Query listing - XQuery48.ixq in samples.zip
   let $customer := document("data/customers.xml")
      //customer[custno='1001']
   let $customercopy := shallow($customer)
   return  {$customercopy } 

Sequence functions. XQuery provides the sequence functions item-at, index-of, empty, exists, union, intersect, and except. The union function backs up the union and the "|" operator. The intersect function backs up the intersect operator (the intersect operator is the keyword "intersect"). The except function backs up the except operator.

The exists function tests whether a sequence is an empty sequence (contains no nodes). The function item-at returns the item located at the specified index within a sequence. The index is 1-based (not 0-based).

The following query uses the empty() function to check whether customer 1001 ordered any item with a price over 300.

   # Query listing - XQuery49.ixq in samples.zip
   let $v := document("data/PO.xml")//po[customer/custno=
      '1001']/lineitems/lineitem/item/price[. > '300']
   return empty($v)

The query returns true because customer 1001 hasn't ordered any such item.

Previous Page

Next Page

---

• Download The Code for this Article

---