Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
==Enhanced FLWOR Expressions==
let $name := $country/name[1]
A new {{Code|count}} clause enhances the FLWOR expression with a variable that enumerates the iterated tuples.==group by==
<pre class="brush:xquery">for $n in (1 FLWOR expressions have been extended to 10)[. mod 2 = 1]count $creturn <number count="{ $c }" number="{ $n }"/></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 2return <window>{ $w }</window></pre> More information on window clauses, and all other enhancements, can be found in include the [httphttps://www.w3.org/TR/xquery-30/#id-windows specification]. ==Simple Map Operator== The [http://www.w3.org/TR/xquerygroup-30/#id-map-operator simple mapby group by] 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 oneclause, and the second expression which is evaluated for each itemwell-established in SQL. The map operator may be used as replacement for FLWOR expressions: '''Example:''' <pre class="brush:xquery"code>(: Simple map notation :)(1 to 10) ! element node { . },(: FLWOR notation :)for $i in 1 to 10return element node { $i }group by</precode>can be used to apply value-based partitioning to query results:
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. ==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: '''ExampleXQuery:''' <pre classsyntaxhighlight lang="brush:xquery">
</pre> This query is a rewrite of [httphttps://www.ins.cwi.nl/projects/xmark/Assets/xmlquery.txt Query #20] contained in the [httphttps://www.insprojects.cwi.nl/projectsxmark/xmark XMark Benchmark Suite] to use <code>group by</code>.
==Switch==
==Function Items==The expression to evaluate can correspond to multiple input values.
One of the most distinguishing features added in ''XQuery 3.0'Example:' are ''function items''<syntaxhighlight lang="xquery">for $fruit in ("Apple", also known as "Cherry")return switch ($fruit) case "Apple" case "Cherry" return "red" case "Pear" return "green" case "Peach" return "pink" default return "unknown"</syntaxhighlight>''lambdas'Result:' or ''lambda functions''. They make it possible to abstract over functions and thus write more modular <code>red red</code.>
'''Examples:'''=Expanded QNames=
Function items can be obtained in three different ways: <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#2return $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].
The syntax differed in older versions of the XQuery 3.0 specification, in which the prefixed namespace URI was quoted: * <code><nowiki>"http://www.w3.org/2005/xpath-functions/math":pi()</nowiki></code>* <code>"java:java.io.FileOutputStream":new("output")</code> ==Namespace Constructors==
==String Concatenations==
==External Variables==
==Serialization==
<<html/>></presyntaxhighlight>
==Context Item==
==Annotations==
==Functions==
BaseX supports all The following functions that have been added in Version 3.0 of the [httphttps://www.w3.org/TR/xpath-functions-3031/ XQuery 3.0 Functions and Operators] Working Draft. The new functions are listed belowSpecification:
* <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: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>
* <code>fn:document-uri()</code> with 0 arguments* , <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
→window
This article is part of the [[XQuery|XQuery Portal]].It summarizes provides a summary of the most interesting important features of the[httphttps://www.w3.org/TR/xquery-30/ XQuery 3.0] Recommendations.XQuery 3.0 is fully supported by BaseXRecommendation.
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.
'''Example:'''
<pre classsyntaxhighlight lang="brush: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 $idreturn <<country id='{ $id }' name='{ $name }'>>{ $city/name }<</country>></presyntaxhighlight>
for $ppl in doc('xmark')//people/person
let $ic := $ppl/profile/@income
order by $income
return element { $income } { count($ppl) }
</syntaxhighlight>
The query partitions the customers based on their income.
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml">
<challenge>4731</challenge>
<na>12677</na>
<preferedpreferred>314</preferedpreferred>
<standard>7778</standard>
</presyntaxhighlight>
In contrast to the relational GROUP BY statement, the XQuery counterpartconcatenates 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 classsyntaxhighlight lang="brush:xquery">
...
return element { $income } { $ppl }
</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml">
<challenge>
<person id="person0">
…
</challenge>
</presyntaxhighlight> 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/persongroup 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 $creturn <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 2return <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#2return $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 [httphttps://www.w3.org/TR/xquery-30/#id-trymap-catch try/catchoperator simple map] construct can 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 to handle errors at runtimeas replacement for FLWOR expressions:
'''Example:'''
<pre classsyntaxhighlight lang="brushxquery">(: Simple map notation :)(1 to 10) ! element node { . },(: FLWOR notation :)for $i in 1 to 10return 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 {
1 + '2'
'Error [' || $err:code || ']: ' || $err:description
}
</presyntaxhighlight>
'''Result:''' <code>Typing error: '+' operator: number expected, xs:string found.</code>
* {{Code|$err:additional}}: error stack trace
The [httphttps://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:'''
<pre classsyntaxhighlight lang="brush:xquery">
for $fruit in ("Apple", "Pear", "Peach")
return switch ($fruit)
case "Peach" return "pink"
default return "unknown"
</presyntaxhighlight>
'''Result:''' <code>red green pink</code>
'''Examples:'''
* <code>Q{java:java.io.FileOutputStream}new("output.txt")</code> creates a new Java file output stream
New namespaces can now be created via so-called 'Computed Namespace Constructors'.
<pre classsyntaxhighlight lang="brush:xquery">
element node { namespace pref { 'http://url.org/' } }
</presyntaxhighlight>
Two vertical bars <code>||</code> (also names named ''pipe characters'') can be used to concatenate strings. This operator is a shortcut for the {{Code|fn:concat()}} function.
<pre classsyntaxhighlight lang="brush:xquery">
'Hello' || ' ' || 'Universe'
</presyntaxhighlight>
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.
<pre classsyntaxhighlight lang="brush:xquery">
declare variable $user external := "admin";
"User:", $user
</presyntaxhighlight>
[[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.
'''Example:'''
<pre classsyntaxhighlight lang="brush:xquery">
declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
declare option output:omit-xml-declaration "no";
declare option output:method "xhtml";
'''Result:''' <code><?xml version="1.0" encoding="UTF-8"?><html></html></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].
The context item can now be specified in the prolog of an XQuery expressionsexpression:
'''Example:'''
<pre classsyntaxhighlight lang="brush:xquery">
declare context item := document {
<xml>
for $t in .//text()
return string-length($t)
</presyntaxhighlight>
'''Result:''' <code>5 5</code>
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:'''
<pre classsyntaxhighlight lang="brush:xquery">
declare %private function local:max($x1, $x2) {
if($x1 > $x2) then $x1 else $x2
local:max(2, 3)
</presyntaxhighlight>
New signatures have been added for the following functions:
=Changelog=
;Version 8.4
* Added: %non-deterministic
;Version 8.0
* Added: %basex:inline, %basex:lazy
;Version 7.7
