urn:uuid:c4a74a0f-6c37-4f74-a250-a22e5fd3af64 2012-01-17T09:09:41+01:00 Switch Expression ljo 35e280da-3631-41a4-895c-b156f1b86232 XQ3Notes html true 2012-04-09T15:59:52.211+02:00 2012-04-09T16:17:06.841+02:00 editor XQuery 3.0 Implementation Notes

The XQuery 3.0 specification introduces a number of additions to the language. eXist-db 2.0 already supports most of the new language constructs.

To use XQuery 3.0 features, your query or module must start with an XQuery declaration specifying version "3.0":

xquery version "3.0";

The following notes cover selected features:

 urn:uuid:768115e7-00e4-4da5-be7c-5daeeb0fef49 2011-03-17T17:57:34+01:00 2011-03-13T12:33:31+01:00 Group By Clause GroupByClause ljo

To make the awareness of the longtime addition of the Group by Clause supplied by Boris Verhaegen already in November 2006 to eXist-db bigger, I give you Boris's short but clean example of its use. This posting is the first step in order to close bug #3165906 about documenting this feature.

let $g-b-data := <items> <item> <key1>1</key1> <key2>a</key2> </item> <item> <key1>1</key1> <key2>b</key2> </item> <item> <key1>0</key1> <key2>c</key2> </item> <item> <key1>0</key1> <key2>d</key2> </item> </items> (: grouping query :) return for $item in $g-b-data//item group $item as $partition by $item/key1 as $key1 return <group> {$key1,$partition} </group>

Which gives the following result:

<group> <key1>1</key1> <item> <key1>1</key1> <key2>a</key2> </item> <item> <key1>1</key1> <key2>b</key2> </item> </group> <group> <key1>0</key1> <item> <key1>0</key1> <key2>c</key2> </item> <item> <key1>0</key1> <key2>d</key2> </item> </group>
urn:uuid:70a9285e-5d4a-4692-a9e5-e276ff150827 2011-10-25T22:08:20+02:00 2011-03-13T12:31:41+01:00 Switch Expression SwitchExpressionExample dizzzz

The Switch Expression is a welcome addition to the XML Query Language. This example presents its potential.

xquery version "3.0"; let $animal := "Cat" return switch ($animal) case "Cow" case "Calf" return "Moo" case "Cat" return "Meow" case "Duck" return "Quack" default return "What's that odd noise?"

returns

Meow

Note the sequence of switch case clauses

case "Cow" case "Calf" return "Moo"
sharing the same return expression.

The expression is available starting eXist-db 1.5

urn:uuid:90f7a15c-778f-4582-ae78-9f54dec73eca 2012-01-17T09:09:41+01:00 2011-03-13T12:29:53+01:00 Try-Catch Expression Try-CatchExpression admin

The Try-Catch Expression is another welcome addition to the XML Query Language. This page introduces the expression and provides some examples.

XQuery 1.0

While the first version of the xquery language provided the possibility to raise errors, the language had no standard mechanism to handle these errors. The following two queries show how it works:

xquery version '1.0'; 7 + "a"

results in "XPTY0004: can not be an operand for +"

xquery version '1.0'; xmldb:store('/db/not-existent/', 'test.xml', <a/>)

results into "Could not locate collection: /db/not-existent/"

For a long time eXist-db provided a custom mechanism to handle these errors with the function. An example:

xquery version '1.0'; util:catch( "*", 7 + "a" , "handle error" )

Additional information about the error can be obtained from two variables which are set by the function:

$util:exception , $util:exception-message

For more details check the eXist-db function documentation.

XQuery 3.0

In version 3.0 of XQuery language the handling of errors has become part of the language: the try-catch expression. An introduction example:

xquery version '3.0'; try { (try expression) } catch (catch error list or "*") { (catch expression) }

The "catch error list" specifies wich errors are handled in the next catch expression; the asterix wildcard is an special example meaning all errors match.

It is possible to have more catch clauses, the values in the catch-error-list determines which catch block is executed.

The following query is a nice complete example of the try-catch expression. The outcome of the query is 2:

xquery version '3.0'; try { 'a' + 7 } catch err:XPTY0001 | err:XPTY0002 { 1 } catch err:XPTY0004 { 2 } catch err:XPDY0003 | err:XPDY0005 { 3 } catch * { 4 }

The java exception of the second example can be handled as well:

xquery version '3.0'; try { xmldb:store('/db/not-existent/', 'test.xml', <a/>) } catch java:org.xmldb.api.base.XMLDBException { "b" }

Finally it is possible to raise and handle an xquery error using the function:

xquery version '3.0'; try { fn:error( fn:QName('http://www.w3.org/2005/xqt-errors', 'err:FOER0000') ) } catch err:FOER0000 { $err:code , $err:description, $err:value }

For more details check the examples in the specification and in the corresponding usecases. These examples are integrated into our test suite.

The expression is available starting eXist-db 1.5 ; in Jan 2012 changes were made to reflect the latest specification