Difference between revisions of "XQuery 3.0"

From BaseX Documentation
Jump to navigation Jump to search
(34 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This article is part of the [[XQuery|XQuery Portal]].
+
This article is part of the [[XQuery|XQuery Portal]]. It provides a summary of the most important features of the [https://www.w3.org/TR/xquery-30/ XQuery 3.0] Recommendation.
It summarizes the most interesting features of the
 
[http://www.w3.org/TR/xquery-30/ XQuery 3.0] Recommendations.
 
XQuery 3.0 is fully supported by BaseX.
 
  
==Enhanced FLWOR Expressions==
+
=Enhanced FLWOR Expressions=
  
Most clauses of FLWOR expressions can now be specified in an arbitrary order: additional {{Code|let}} and {{Code|for}} clauses can be put after a {{Code|where}} clause, and multiple {{Code|where}}, {{Code|order by}} and {{Code|group by}} statements can be used. This means that many nested loops can now be rewritten to a single FLWOR expression.
+
Most clauses of FLWOR expressions can be specified in an arbitrary order: additional {{Code|let}} and {{Code|for}} clauses can be put after a {{Code|where}} clause, and multiple {{Code|where}}, {{Code|order by}} and {{Code|group by}} statements can be used. This means that many nested loops can now be rewritten to a single FLWOR expression.
  
 
'''Example:'''  
 
'''Example:'''  
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
for $country in db:open('factbook')//country
 
for $country in db:open('factbook')//country
 
where $country/@population > 100000000
 
where $country/@population > 100000000
let $name := $country/name[1]
 
 
for $city in $country//city[population > 1000000]
 
for $city in $country//city[population > 1000000]
group by $name
+
group by $name := $country/name[1]
return &lt;country name='{ $name }'&gt;{ $city/name }&lt;/country&gt;
+
count $id
</pre>
+
return <country id='{ $id }' name='{ $name }'>{ $city/name }</country>
 +
</syntaxhighlight>
  
A new {{Code|count}} clause enhances the FLWOR expression with a variable that enumerates the iterated tuples.
+
==group by==
  
<pre class="brush:xquery">
+
FLWOR expressions have been extended to include the [https://www.w3.org/TR/xquery-30/#id-group-by group by] clause, which is well-established in SQL. <code>group by</code> can be used to apply value-based partitioning to query results:
for $n in (1 to 10)[. mod 2 = 1]
 
count $c
 
return &lt;number count="{ $c }" number="{ $n }"/&gt;
 
</pre>
 
 
 
The {{Code|allowing empty}} provides functionality similar to outer joins in SQL:
 
 
 
<pre class="brush:xquery">
 
for $n allowing empty in ()
 
return 'empty? ' || empty($n)
 
</pre>
 
 
 
Window clauses provide a rich set of variable declarations to process sub-sequences of iterated tuples. An example:
 
 
 
<pre class="brush:xquery">
 
for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
 
    start at $s when fn:true()
 
    only end at $e when $e - $s eq 2
 
return &lt;window&gt;{ $w }&lt;/window&gt;
 
</pre>
 
 
 
More information on window clauses, and all other enhancements, can be found in the [http://www.w3.org/TR/xquery-30/#id-windows specification].
 
 
 
==Simple Map Operator==
 
 
 
The [http://www.w3.org/TR/xquery-30/#id-map-operator simple map] operator {{Code|!}} provides a compact notation for applying the results of a first to a second expression: the resulting items of the first expression are bound to the context item one by one, and the second expression is evaluated for each item. The map operator may be used as replacement for FLWOR expressions:
 
 
 
'''Example:'''
 
<pre class="brush:xquery">
 
(: Simple map notation :)
 
(1 to 10) ! element node { . },
 
(: FLWOR notation :)
 
for $i in 1 to 10
 
return element node { $i }
 
</pre>
 
  
A map operator is defined to be part of a path expression, which may now be mixed of path and map operators. In contrast to the map operator, the results of the map operator will not be made duplicate-free and returned in document order.
+
'''XQuery:'''  
 
+
<syntaxhighlight lang="xquery">
==Group By==
 
 
 
FLWOR expressions have been extended to include the [http://www.w3.org/TR/xquery-30/#id-group-by group by] clause, which is well-established among relational database systems. <code>group by</code> can be used to apply value-based partitioning to query results:
 
 
 
'''Example:'''  
 
<pre class="brush:xquery">  
 
 
for $ppl in doc('xmark')//people/person   
 
for $ppl in doc('xmark')//people/person   
 
let $ic := $ppl/profile/@income
 
let $ic := $ppl/profile/@income
Line 78: Line 34:
 
order by $income
 
order by $income
 
return element { $income } { count($ppl) }
 
return element { $income } { count($ppl) }
 +
</syntaxhighlight>
  
</pre>
+
This query is a rewrite of [https://www.ins.cwi.nl/projects/xmark/Assets/xmlquery.txt Query #20] contained in the [https://projects.cwi.nl/xmark/ XMark Benchmark Suite] to use <code>group by</code>.
 
 
This query is a rewrite of [http://www.ins.cwi.nl/projects/xmark/Assets/xmlquery.txt Query #20] contained in the [http://www.ins.cwi.nl/projects/xmark XMark Benchmark Suite] to use <code>group by</code>.
 
 
The query partitions the customers based on their income.  
 
The query partitions the customers based on their income.  
  
 
'''Result:'''  
 
'''Result:'''  
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<challenge>4731</challenge>
 
<challenge>4731</challenge>
 
<na>12677</na>
 
<na>12677</na>
<prefered>314</prefered>
+
<preferred>314</preferred>
 
<standard>7778</standard>
 
<standard>7778</standard>
</pre>
+
</syntaxhighlight>
  
In contrast to the relational GROUP BY statement, the XQuery counterpart
+
In contrast to the relational GROUP BY statement, the XQuery counterpart concatenates the values of all non-grouping variables that belong to a specific group. In the context of our example, all nodes in <code>//people/person</code> that belong to the <code>preferred</code> partition are concatenated in <code class="brush:xquery">$ppl</code> after grouping has finished. You can see this effect by changing the return statement to:
concatenates the values of all non-grouping variables that belong to a specific group.
 
In the context of our example, all nodes in <code>//people/person</code> that belong to the <code>preferred</code> partition are concatenated in <code class="brush:xquery">$ppl</code> after grouping has finished.
 
You can see this effect by changing the return statement to:
 
  
<pre class="brush:xquery">  
+
<syntaxhighlight lang="xquery">  
 
...
 
...
 
return element { $income } { $ppl }
 
return element { $income } { $ppl }
</pre>
+
</syntaxhighlight>
 +
 
 
'''Result:'''
 
'''Result:'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<challenge>
 
<challenge>
 
   <person id="person0">
 
   <person id="person0">
Line 110: Line 63:
 
     …
 
     …
 
</challenge>
 
</challenge>
</pre>
+
</syntaxhighlight>
 +
 
 +
Moreover, a value can be assigned to the grouping variable. This is shown in the following example:
 +
 
 +
'''XQuery:'''
 +
<syntaxhighlight lang="xquery">
 +
let $data :=
 +
  <xml>
 +
    <person country='USA' name='John'/>
 +
    <person country='USA' name='Jack'/>
 +
    <person country='Germany' name='Johann'/>
 +
  </xml>
 +
for $person in $data/person
 +
group by $country := $person/@country/string()
 +
return element persons {
 +
  attribute country { $country },
 +
  $person/@name ! element name { data() }
 +
}
 +
</syntaxhighlight>
 +
 
 +
'''Result:'''
 +
<syntaxhighlight lang="xml">
 +
<persons country="USA">
 +
  <name>John</name>
 +
  <name>Jack</name>
 +
</persons>
 +
<persons country="Germany">
 +
  <name>Johann</name>
 +
</persons>
 +
</syntaxhighlight>
 +
 
 +
==count==
 +
 
 +
The {{Code|count}} clause enhances the FLWOR expression with a variable that enumerates the iterated tuples.
 +
 
 +
<syntaxhighlight lang="xquery">
 +
for $n in (1 to 10)[. mod 2 = 1]
 +
count $c
 +
return <number count="{ $c }" number="{ $n }"/>
 +
</syntaxhighlight>
 +
 
 +
==allowing empty==
 +
 
 +
The {{Code|allowing empty}} provides functionality similar to outer joins in SQL:
 +
 
 +
<syntaxhighlight lang="xquery">
 +
for $n allowing empty in ()
 +
return 'empty? ' || empty($n)
 +
</syntaxhighlight>
 +
 
 +
==window==
 +
 
 +
Window clauses provide a rich set of variable declarations to process sub-sequences of iterated tuples. An example:
 +
 
 +
<syntaxhighlight lang="xquery">
 +
for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)
 +
    start at $s when fn:true()
 +
    only end at $e when $e - $s eq 2
 +
return <window>{ $w }</window>
 +
</syntaxhighlight>
 +
 
 +
More information on window clauses, and all other enhancements, can be found in the [https://www.w3.org/TR/xquery-30/#id-windows specification].
 +
 
 +
=Function Items=
 +
 
 +
One of the most distinguishing features added in ''XQuery 3.0'' are ''function items'', also known as ''lambdas'' or ''lambda functions''. They make it possible to abstract over functions and thus write more modular code.
 +
 
 +
'''Examples:'''
 +
 
 +
Function items can be obtained in three different ways:
 +
 
 +
<ul>
 +
<li>Declaring a new ''inline function'':
 +
<syntaxhighlight lang="xquery">let $f := function($x, $y) { $x + $y }
 +
return $f(17, 25)</syntaxhighlight>
 +
'''Result:''' <code>42</code>
 +
</li>
 +
<li>Getting the function item of an existing (built-in or user-defined) XQuery function. The arity (number of arguments) has to be specified as there can be more than one function with the same name:
 +
<syntaxhighlight lang="xquery">let $f := math:pow#2
 +
return $f(5, 2)</syntaxhighlight>
 +
'''Result:''' <code>25</code>
 +
</li>
 +
<li>''Partially applying'' another function or function item. This is done by supplying only some of the required arguments, writing the placeholder <code>?</code> in the positions of the arguments left out. The produced function item has one argument for every placeholder.
 +
<syntaxhighlight lang="xquery">let $f := fn:substring(?, 1, 3)
 +
return (
 +
  $f('foo123'),
 +
  $f('bar456')
 +
)</syntaxhighlight>
 +
'''Result:''' <code>foo bar</code>
 +
</li>
 +
</ul>
 +
 
 +
Function items can also be passed as arguments to and returned as results from functions. These so-called [[Higher-Order Functions]] like <code>fn:map</code> and <code>fn:fold-left</code> are discussed in more depth on their own Wiki page.
  
==Try/Catch==
+
=Simple Map Operator=
  
The [http://www.w3.org/TR/xquery-30/#id-try-catch try/catch] construct can be used to handle errors at runtime:
+
The [https://www.w3.org/TR/xquery-30/#id-map-operator simple map] operator {{Code|!}} provides a compact notation for applying the results of a first to a second expression: the resulting items of the first expression are bound to the context item one by one, and the second expression is evaluated for each item. The map operator may be used as replacement for FLWOR expressions:
  
 
'''Example:'''  
 
'''Example:'''  
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 +
(: Simple map notation :)
 +
(1 to 10) ! element node { . },
 +
(: FLWOR notation :)
 +
for $i in 1 to 10
 +
return element node { $i }
 +
</syntaxhighlight>
 +
 
 +
In contrast to path expressions, the results of the map operator will not be made duplicate-free and returned in document order.
 +
 
 +
=Try/Catch=
 +
 
 +
The [https://www.w3.org/TR/xquery-30/#id-try-catch try/catch] construct can be used to handle errors at runtime:
 +
 
 +
'''Example:'''
 +
<syntaxhighlight lang="xquery">
 
try {
 
try {
 
   1 + '2'
 
   1 + '2'
Line 125: Line 185:
 
   'Error [' || $err:code || ']: ' || $err:description
 
   'Error [' || $err:code || ']: ' || $err:description
 
}
 
}
</pre>
+
</syntaxhighlight>
 
'''Result:''' <code>Typing error: '+' operator: number expected, xs:string found.</code>
 
'''Result:''' <code>Typing error: '+' operator: number expected, xs:string found.</code>
  
Line 138: Line 198:
 
* {{Code|$err:additional}}: error stack trace
 
* {{Code|$err:additional}}: error stack trace
  
==Switch==
+
=Switch=
  
The [http://www.w3.org/TR/xquery-30/#id-switch switch] statement is available in many other programming languages. It chooses one of several expressions to evaluate based on its input value.
+
The [https://www.w3.org/TR/xquery-30/#id-switch switch] statement is available in many other programming languages. It chooses one of several expressions to evaluate based on its input value.
  
 
'''Example:'''  
 
'''Example:'''  
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
for $fruit in ("Apple", "Pear", "Peach")
 
for $fruit in ("Apple", "Pear", "Peach")
 
return switch ($fruit)
 
return switch ($fruit)
Line 150: Line 210:
 
   case "Peach" return "pink"
 
   case "Peach" return "pink"
 
   default      return "unknown"
 
   default      return "unknown"
</pre>  
+
</syntaxhighlight>  
 
'''Result:''' <code>red green pink</code>
 
'''Result:''' <code>red green pink</code>
  
==Function Items==
+
The expression to evaluate can correspond to multiple input values.
  
One of the most distinguishing features added in ''XQuery 3.0'' are ''function items'', also known as ''lambdas'' or ''lambda functions''. They make it possible to abstract over functions and thus write more modular code.
+
'''Example:'''
 +
<syntaxhighlight lang="xquery">
 +
for $fruit in ("Apple", "Cherry")
 +
return switch ($fruit)
 +
  case "Apple"
 +
  case "Cherry"
 +
    return "red"
 +
  case "Pear"
 +
    return "green"
 +
  case "Peach"
 +
    return "pink"
 +
  default
 +
    return "unknown"
 +
</syntaxhighlight>
 +
'''Result:''' <code>red red</code>
  
'''Examples:'''
+
=Expanded QNames=
  
Function items can be obtained in three different ways:
+
A ''QName'' can be prefixed with the letter "Q" and a namespace URI in the [http://www.jclark.com/xml/xmlns.htm Clark Notation].
 
 
<ul>
 
<li>Declaring a new ''inline function'':
 
<pre class="brush:xquery">let $f := function($x, $y) { $x + $y }
 
return $f(17, 25)</pre>
 
'''Result:''' <code>42</code>
 
</li>
 
<li>Getting the function item of an existing (built-in or user-defined) XQuery function. The arity (number of arguments) has to be specified as there can be more than one function with the same name:
 
<pre class="brush:xquery">let $f := math:pow#2
 
return $f(5, 2)</pre>
 
'''Result:''' <code>25</code>
 
</li>
 
<li>''Partially applying'' another function or function item. This is done by supplying only some of the required arguments, writing the placeholder <code>?</code> in the positions of the arguments left out. The produced function item has one argument for every placeholder.
 
<pre class="brush:xquery">let $f := fn:substring(?, 1, 3)
 
return (
 
  $f('foo123'),
 
  $f('bar456')
 
)</pre>
 
'''Result:''' <code>foo bar</code>
 
</li>
 
</ul>
 
 
 
Function items can also be passed as arguments to and returned as results from functions. These so-called [[Higher-Order Functions]] like <code>fn:map</code> and <code>fn:fold-left</code> are discussed in more depth on their own Wiki page.
 
 
 
==Expanded QNames==
 
 
 
A ''QName'' can now be directly prefixed with the letter "Q" and a namespace URI in the [http://www.jclark.com/xml/xmlns.htm Clark Notation].
 
  
 
'''Examples:'''
 
'''Examples:'''
Line 192: Line 239:
 
* <code>Q{java:java.io.FileOutputStream}new("output.txt")</code> creates a new Java file output stream
 
* <code>Q{java:java.io.FileOutputStream}new("output.txt")</code> creates a new Java file output stream
  
The syntax differed in older versions of the XQuery 3.0 specification, in which the prefixed namespace URI was quoted:
+
=Namespace Constructors=
 
 
* <code><nowiki>"http://www.w3.org/2005/xpath-functions/math":pi()</nowiki></code>
 
* <code>"java:java.io.FileOutputStream":new("output")</code>
 
 
 
==Namespace Constructors==
 
  
New namespaces can now be created via so-called 'Computed Namespace Constructors'.
+
New namespaces can be created via so-called 'Computed Namespace Constructors'.
  
<pre class="brush:xquery">  
+
<syntaxhighlight lang="xquery">  
 
element node { namespace pref { 'http://url.org/' } }
 
element node { namespace pref { 'http://url.org/' } }
</pre>
+
</syntaxhighlight>
  
==String Concatenations==
+
=String Concatenations=
  
Two vertical bars <code>||</code> (also names ''pipe characters'') can be used to concatenate strings. This operator is a shortcut for the {{Code|fn:concat()}} function.
+
Two vertical bars <code>||</code> (also named ''pipe characters'') can be used to concatenate strings. This operator is a shortcut for the {{Code|fn:concat()}} function.
  
<pre class="brush:xquery">  
+
<syntaxhighlight lang="xquery">  
 
'Hello' || ' ' || 'Universe'
 
'Hello' || ' ' || 'Universe'
</pre>
+
</syntaxhighlight>
  
==External Variables==
+
=External Variables=
  
Default values can now be attached to external variable declarations. This way, an expression can also be evaluated if its external variables have not been bound to a new value.
+
Default values can be attached to external variable declarations. This way, an expression can also be evaluated if its external variables have not been bound to a new value.
  
<pre class="brush:xquery">  
+
<syntaxhighlight lang="xquery">  
 
declare variable $user external := "admin";
 
declare variable $user external := "admin";
 
"User:", $user
 
"User:", $user
</pre>
+
</syntaxhighlight>
  
==Serialization==
+
=Serialization=
  
[[Serialization|Serialization ]]parameters can now be defined within XQuery expressions. Parameters are placed in the query prolog and need to be specified as option declarations, using the <code>output</code> prefix.
+
[[Serialization|Serialization ]]parameters can be defined within XQuery expressions. Parameters are placed in the query prolog and need to be specified as option declarations, using the <code>output</code> prefix.
  
 
'''Example:'''  
 
'''Example:'''  
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
 
declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
 
declare option output:omit-xml-declaration "no";
 
declare option output:omit-xml-declaration "no";
 
declare option output:method "xhtml";
 
declare option output:method "xhtml";
&lt;html/&gt;
+
<html/>
</pre>  
+
</syntaxhighlight>  
 
'''Result:''' <code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;&lt;html&gt;&lt;/html&gt;</code>
 
'''Result:''' <code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;&lt;html&gt;&lt;/html&gt;</code>
  
 
In BaseX, the {{Code|output}} prefix is statically bound and can thus be omitted. Note that all namespaces need to be specified when using external APIs, such as [http://xqj.net/basex/ XQJ].
 
In BaseX, the {{Code|output}} prefix is statically bound and can thus be omitted. Note that all namespaces need to be specified when using external APIs, such as [http://xqj.net/basex/ XQJ].
  
==Context Item==
+
=Context Item=
  
The context item can now be specified in the prolog of an XQuery expressions:
+
The context item can be specified in the prolog of an XQuery expression:
  
 
'''Example:'''  
 
'''Example:'''  
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
declare context item := document {
 
declare context item := document {
 
   <xml>
 
   <xml>
Line 252: Line 294:
 
for $t in .//text()
 
for $t in .//text()
 
return string-length($t)
 
return string-length($t)
</pre>  
+
</syntaxhighlight>  
 
'''Result:''' <code>5 5</code>
 
'''Result:''' <code>5 5</code>
  
==Annotations==
+
=Annotations=
  
 
XQuery 3.0 introduces annotations to declare properties associated with functions and variables. For instance, a function may be declared %public, %private, or %updating.
 
XQuery 3.0 introduces annotations to declare properties associated with functions and variables. For instance, a function may be declared %public, %private, or %updating.
  
 
'''Example:'''  
 
'''Example:'''  
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
declare %private function local:max($x1, $x2) {
 
declare %private function local:max($x1, $x2) {
 
   if($x1 > $x2) then $x1 else $x2
 
   if($x1 > $x2) then $x1 else $x2
Line 266: Line 308:
  
 
local:max(2, 3)
 
local:max(2, 3)
</pre>
+
</syntaxhighlight>
  
==Functions==
+
=Functions=
  
BaseX supports all functions that have been added in Version 3.0 of the [http://www.w3.org/TR/xpath-functions-30/ XQuery Functions and Operators] Working Draft. The new functions are listed below:
+
The following functions have been added in the [https://www.w3.org/TR/xpath-functions-31/ XQuery 3.0 Functions and Operators] Specification:
  
* <code>math:pi()</code>, <code>math:sin()</code>, and many others (see [[Math Module]])
+
<code>fn:analyze-string</code>* <code>fn:available-environment-variables</code>, <code>fn:element-with-id</code>, <code>fn:environment-variable</code>, <code>fn:filter</code>, <code>fn:fold-left</code>, <code>fn:fold-right</code>, <code>fn:for-each</code>, <code>fn:for-each-pair</code>, <code>fn:format-date</code>, <code>fn:format-dateTime</code>, <code>fn:format-integer</code>, <code>fn:format-number</code>, <code>fn:format-time</code>, <code>fn:function-arity</code>, <code>fn:function-lookup</code>, <code>fn:function-name</code>, <code>fn:generate-id</code>, <code>fn:has-children</code>, <code>fn:head</code>, <code>fn:innermost</code>, <code>fn:outermost</code>, <code>fn:parse-xml</code>, <code>fn:parse-xml-fragment</code>, <code>fn:path</code>, <code>fn:serialize</code>, <code>fn:tail</code>, <code>fn:unparsed-text</code>, <code>fn:unparsed-text-available</code>, <code>fn:unparsed-text-lines</code>, <code>fn:uri-collection</code>
* <code>fn:analyze-string()</code>
 
* <code>fn:available-environment-variables()</code>
 
* <code>fn:element-with-id()</code>
 
* <code>fn:environment-variable()</code>
 
* <code>fn:filter()</code>
 
* <code>fn:fold-left()</code>
 
* <code>fn:fold-right()</code>
 
* <code>fn:format-date()</code>
 
* <code>fn:format-dateTime()</code>
 
* <code>fn:format-integer()</code>
 
* <code>fn:format-number()</code>
 
* <code>fn:format-time()</code>
 
* <code>fn:function-arity()</code>
 
* <code>fn:function-lookup()</code>
 
* <code>fn:function-name()</code>
 
* <code>fn:generate-id()</code>
 
* <code>fn:has-children()</code>
 
* <code>fn:head()</code>
 
* <code>fn:innermost()</code>
 
* <code>fn:map()</code>
 
* <code>fn:map-pairs()</code>
 
* <code>fn:outermost()</code>
 
* <code>fn:parse-xml()</code>
 
* <code>fn:parse-xml-fragment()</code>
 
* <code>fn:path()</code>
 
* <code>fn:serialize()</code>
 
* <code>fn:tail()</code>
 
* <code>fn:unparsed-text()</code>
 
* <code>fn:unparsed-text-available()</code>
 
* <code>fn:unparsed-text-lines()</code>
 
* <code>fn:uri-collection()</code>
 
  
 
New signatures have been added for the following functions:
 
New signatures have been added for the following functions:
  
* <code>fn:document-uri()</code> with 0 arguments
+
<code>fn:document-uri</code>, <code>fn:string-join</code>, <code>fn:node-name</code>, <code>fn:round</code>, <code>fn:data</code>
* <code>fn:string-join()</code> with 1 argument
 
* <code>fn:node-name()</code> with 0 arguments
 
* <code>fn:round()</code> with 2 arguments
 
* <code>fn:data()</code> with 0 arguments
 
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 8.4
 +
 +
* Added: %non-deterministic
 +
 +
;Version 8.0
 +
 +
* Added: %basex:inline, %basex:lazy
  
 
;Version 7.7
 
;Version 7.7

Revision as of 09:50, 29 July 2020

This article is part of the XQuery Portal. It provides a summary of the most important features of the XQuery 3.0 Recommendation.

Enhanced FLWOR Expressions

Most clauses of FLWOR expressions can be specified in an arbitrary order: additional let and for clauses can be put after a where clause, and multiple where, order by and group by statements can be used. This means that many nested loops can now be rewritten to a single FLWOR expression.

Example: <syntaxhighlight lang="xquery"> for $country in db:open('factbook')//country where $country/@population > 100000000 for $city in $country//city[population > 1000000] group by $name := $country/name[1] count $id return <country id='{ $id }' name='{ $name }'>{ $city/name }</country> </syntaxhighlight>

group by

FLWOR expressions have been extended to include the group by clause, which is well-established in SQL. group by can be used to apply value-based partitioning to query results:

XQuery: <syntaxhighlight lang="xquery"> for $ppl in doc('xmark')//people/person let $ic := $ppl/profile/@income let $income := if($ic < 30000) then

                  "challenge" 
               else if($ic >= 30000 and $ic < 100000) then 
                  "standard" 
               else if($ic >= 100000) then 
                  "preferred" 
               else 
                  "na"  

group by $income order by $income return element { $income } { count($ppl) } </syntaxhighlight>

This query is a rewrite of Query #20 contained in the XMark Benchmark Suite to use group by. The query partitions the customers based on their income.

Result: <syntaxhighlight lang="xml"> <challenge>4731</challenge> <na>12677</na> <preferred>314</preferred> <standard>7778</standard> </syntaxhighlight>

In contrast to the relational GROUP BY statement, the XQuery counterpart concatenates the values of all non-grouping variables that belong to a specific group. In the context of our example, all nodes in //people/person that belong to the preferred partition are concatenated in $ppl after grouping has finished. You can see this effect by changing the return statement to:

<syntaxhighlight lang="xquery"> ... return element { $income } { $ppl } </syntaxhighlight>

Result: <syntaxhighlight lang="xml"> <challenge>

 <person id="person0">
   <name>Kasidit Treweek</name>
   …
 <person id="personX">
   …

</challenge> </syntaxhighlight>

Moreover, a value can be assigned to the grouping variable. This is shown in the following example:

XQuery: <syntaxhighlight lang="xquery"> let $data :=

 <xml>
   <person country='USA' name='John'/>
   <person country='USA' name='Jack'/>
   <person country='Germany' name='Johann'/>
 </xml>

for $person in $data/person group by $country := $person/@country/string() return element persons {

 attribute country { $country },
 $person/@name ! element name { data() }

} </syntaxhighlight>

Result: <syntaxhighlight lang="xml"> <persons country="USA">

 <name>John</name>
 <name>Jack</name>

</persons> <persons country="Germany">

 <name>Johann</name>

</persons> </syntaxhighlight>

count

The count clause enhances the FLWOR expression with a variable that enumerates the iterated tuples.

<syntaxhighlight lang="xquery"> for $n in (1 to 10)[. mod 2 = 1] count $c return <number count="{ $c }" number="{ $n }"/> </syntaxhighlight>

allowing empty

The allowing empty provides functionality similar to outer joins in SQL:

<syntaxhighlight lang="xquery"> for $n allowing empty in () return 'empty? ' || empty($n) </syntaxhighlight>

window

Window clauses provide a rich set of variable declarations to process sub-sequences of iterated tuples. An example:

<syntaxhighlight lang="xquery"> for tumbling window $w in (2, 4, 6, 8, 10, 12, 14)

   start at $s when fn:true()
   only end at $e when $e - $s eq 2

return <window>{ $w }</window> </syntaxhighlight>

More information on window clauses, and all other enhancements, can be found in the specification.

Function Items

One of the most distinguishing features added in XQuery 3.0 are function items, also known as lambdas or lambda functions. They make it possible to abstract over functions and thus write more modular code.

Examples:

Function items can be obtained in three different ways:

  • Declaring a new inline function: <syntaxhighlight lang="xquery">let $f := function($x, $y) { $x + $y } return $f(17, 25)</syntaxhighlight> Result: 42
  • Getting the function item of an existing (built-in or user-defined) XQuery function. The arity (number of arguments) has to be specified as there can be more than one function with the same name: <syntaxhighlight lang="xquery">let $f := math:pow#2 return $f(5, 2)</syntaxhighlight> Result: 25
  • Partially applying another function or function item. This is done by supplying only some of the required arguments, writing the placeholder ? in the positions of the arguments left out. The produced function item has one argument for every placeholder. <syntaxhighlight lang="xquery">let $f := fn:substring(?, 1, 3) return ( $f('foo123'), $f('bar456') )</syntaxhighlight> Result: foo bar

Function items can also be passed as arguments to and returned as results from functions. These so-called Higher-Order Functions like fn:map and fn:fold-left are discussed in more depth on their own Wiki page.

Simple Map Operator

The simple map operator ! provides a compact notation for applying the results of a first to a second expression: the resulting items of the first expression are bound to the context item one by one, and the second expression is evaluated for each item. The map operator may be used as replacement for FLWOR expressions:

Example: <syntaxhighlight lang="xquery"> (: Simple map notation :) (1 to 10) ! element node { . }, (: FLWOR notation :) for $i in 1 to 10 return element node { $i } </syntaxhighlight>

In contrast to path expressions, the results of the map operator will not be made duplicate-free and returned in document order.

Try/Catch

The try/catch construct can be used to handle errors at runtime:

Example: <syntaxhighlight lang="xquery"> try {

 1 + '2'

} catch err:XPTY0004 {

 'Typing error: ' || $err:description

} catch * {

 'Error [' || $err:code || ']: ' || $err:description

} </syntaxhighlight> Result: Typing error: '+' operator: number expected, xs:string found.

Within the scope of the catch clause, a number of variables are implicitly declared, giving information about the error that occurred:

  • $err:code error code
  • $err:description: error message
  • $err:value: value associated with the error (optional)
  • $err:module: URI of the module where the error occurred
  • $err:line-number: line number where the error occurred
  • $err:column-number: column number where the error occurred
  • $err:additional: error stack trace

Switch

The switch statement is available in many other programming languages. It chooses one of several expressions to evaluate based on its input value.

Example: <syntaxhighlight lang="xquery"> for $fruit in ("Apple", "Pear", "Peach") return switch ($fruit)

 case "Apple" return "red"
 case "Pear"  return "green"
 case "Peach" return "pink"
 default      return "unknown"

</syntaxhighlight> Result: red green pink

The expression to evaluate can correspond to multiple input values.

Example: <syntaxhighlight lang="xquery"> for $fruit in ("Apple", "Cherry") return switch ($fruit)

 case "Apple"
 case "Cherry"
    return "red"
 case "Pear"
    return "green"
 case "Peach"
    return "pink"
 default
    return "unknown"

</syntaxhighlight> Result: red red

Expanded QNames

A QName can be prefixed with the letter "Q" and a namespace URI in the Clark Notation.

Examples:

  • Q{http://www.w3.org/2005/xpath-functions/math}pi() returns the number π
  • Q{java:java.io.FileOutputStream}new("output.txt") creates a new Java file output stream

Namespace Constructors

New namespaces can be created via so-called 'Computed Namespace Constructors'.

<syntaxhighlight lang="xquery"> element node { namespace pref { 'http://url.org/' } } </syntaxhighlight>

String Concatenations

Two vertical bars || (also named pipe characters) can be used to concatenate strings. This operator is a shortcut for the fn:concat() function.

<syntaxhighlight lang="xquery"> 'Hello' || ' ' || 'Universe' </syntaxhighlight>

External Variables

Default values can be attached to external variable declarations. This way, an expression can also be evaluated if its external variables have not been bound to a new value.

<syntaxhighlight lang="xquery"> declare variable $user external := "admin"; "User:", $user </syntaxhighlight>

Serialization

Serialization parameters can be defined within XQuery expressions. Parameters are placed in the query prolog and need to be specified as option declarations, using the output prefix.

Example: <syntaxhighlight lang="xquery"> declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization"; declare option output:omit-xml-declaration "no"; declare option output:method "xhtml"; <html/> </syntaxhighlight> Result: <?xml version="1.0" encoding="UTF-8"?><html></html>

In BaseX, the output prefix is statically bound and can thus be omitted. Note that all namespaces need to be specified when using external APIs, such as XQJ.

Context Item

The context item can be specified in the prolog of an XQuery expression:

Example: <syntaxhighlight lang="xquery"> declare context item := document {

 <xml>
   <text>Hello</text>
   <text>World</text>
 </xml>

};

for $t in .//text() return string-length($t) </syntaxhighlight> Result: 5 5

Annotations

XQuery 3.0 introduces annotations to declare properties associated with functions and variables. For instance, a function may be declared %public, %private, or %updating.

Example: <syntaxhighlight lang="xquery"> declare %private function local:max($x1, $x2) {

 if($x1 > $x2) then $x1 else $x2

};

local:max(2, 3) </syntaxhighlight>

Functions

The following functions have been added in the XQuery 3.0 Functions and Operators Specification:

fn:analyze-string* fn:available-environment-variables, fn:element-with-id, fn:environment-variable, fn:filter, fn:fold-left, fn:fold-right, fn:for-each, fn:for-each-pair, fn:format-date, fn:format-dateTime, fn:format-integer, fn:format-number, fn:format-time, fn:function-arity, fn:function-lookup, fn:function-name, fn:generate-id, fn:has-children, fn:head, fn:innermost, fn:outermost, fn:parse-xml, fn:parse-xml-fragment, fn:path, fn:serialize, fn:tail, fn:unparsed-text, fn:unparsed-text-available, fn:unparsed-text-lines, fn:uri-collection

New signatures have been added for the following functions:

fn:document-uri, fn:string-join, fn:node-name, fn:round, fn:data

Changelog

Version 8.4
  • Added: %non-deterministic
Version 8.0
  • Added: %basex:inline, %basex:lazy
Version 7.7
Version 7.3
Version 7.2
Version 7.1
Version 7.0