All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/xquery</nowiki></code> namespace, which is statically bound to the {{Code|xquery}} prefix.<br/>
=Dynamic Evaluation=
==xquery:eval==
{{Mark|Updated with 9.2}}: First argument can be a URI (xquery:invoke was removed).
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|xquery:eval|$query as xs:anyAtomicType|item()*}}<br />{{Func|xquery:eval|$query as xs:anyAtomicType, $bindings as map(*)?|item()*}}<br />{{Func|xquery:eval|$query as xs:anyAtomicType, $bindings as map(*)?, $options as map(*)?|item()*}}<br />
|-valign="top"
| '''Summary'''
|Evaluates the supplied {{Code|$query}} and returns the resulting items. If the query is of type {{Code|xs:anyURI}}, the module located at this URI will be retrieved (a relative URI will be resolved against the static base URI). Otherwise, the input is expected to be of type {{Code|xs:string}}.
* {{Code|base-uri}}: set [https://www.w3.org/TR/xquery-31/#dt-static-base-uri base-uri property] for the query. Overwrites the base URI of the query; will be used when resolving relative URIs by functions such as {{Code|fn:doc}}.
* {{Code|pass}}: passes on the original error info (line and column number, optional file uri). By default, this option is {{Code|false}}.
|-valign="top"
| '''Errors'''
|{{Error|update|#Errors}} the query contains [[XQuery Update#Updating Expressions|updating expressions]].<br/>{{Error|permission|#Errors}} insufficient permissions for evaluating the query.<br/>{{Error|timeout|#Errors}} query execution exceeded timeout.<br/>{{Error|limit|#Errors}} query execution exceeded memory limit.<br/>{{Error|nested|#Errors}} nested query evaluation is not allowed.<br/>Any other error that may occur while evaluating the query.
|-valign="top"
| '''Examples'''
|
* {{Code|xquery:eval("1+3")}} returns {{Code|4}}.<br />
* If a URI is supplied, the query in the specified file will be evaluated:
<syntaxhighlight lang="xquery">
xquery:eval(xs:anyURI('cleanup.xq'))
</syntaxhighlight>
* You can bind the context and e.g. operate on a certain database only:<br />
<pre classsyntaxhighlight lang='brush:"xquery'">xquery:eval("//country", map { '': db:openget('factbook') })</presyntaxhighlight>
* The following expressions use strings as keys. All of them return 'XML':<br/>
<pre classsyntaxhighlight lang='brush:"xquery'">
xquery:eval(".", map { '': 'XML' }),
map { '{URI}xml': 'XML' }
)
</presyntaxhighlight>
* The following expressions use QNames as keys. All of them return 'XML':<br/>
<pre classsyntaxhighlight lang='brush:"xquery'">
declare namespace pref = 'URI';
let $vars := map { xs:QName('pref:xml'): 'XML' }
return xquery:eval($query, $vars)
</pre>* If a URI is supplied, the query in the specified file will be evaluated:<pre class='brush:xquery'>xquery:eval(xs:anyURI('cleanup.xq'))</presyntaxhighlight>
|}
==xquery:eval-update==
{{Mark|Updated with 9.2}}: First argument may be a URI (xquery:invoke-update was removed).
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|xquery:eval-update|$query as xs:anyAtomicType|item()*}}<br />{{Func|xquery:eval-update|$query as xs:anyAtomicType, $bindings as map(*)?|item()*}}<br />{{Func|xquery:eval-update|$query as xs:anyAtomicType, $bindings as map(*)?, $options as map(*)?|item()*}}<br />
|-valign="top"
| '''Summary'''
|Evaluates a query as updating expression. All updates will be added to the [[XQuery Update#Pending Update List|Pending Update List]] of the main query and performed after the evaluation of the main query.<br />The rules for all arguments are the same as for [[#xquery:eval{{Function||xquery:eval]]}}.|-valign="top"
| '''Errors'''
|{{Error|update|#Errors}} the query contains no [[XQuery Update#Updating Expressions|updating expressions]].<br/>{{Error|permission|#Errors}} insufficient permissions for evaluating the query.<br/>{{Error|timeout|#Errors}} query execution exceeded timeout.<br/>{{Error|limit|#Errors}} query execution exceeded memory limit.<br/>{{Error|nested|#Errors}} nested query evaluation is not allowed.<br/>Any other error that may occur while evaluating the query.
|-valign="top"
| '''Examples'''
|
* Removes entries from a temporary databases and returns an info string:
<pre classsyntaxhighlight lang="brush:xquery">
xquery:eval-update("
delete node db:openget('tmp')/*,
update:output('TEMPORARY DATABASE WAS CLEANED UP')
")
</presyntaxhighlight>
|}
=XQuery Parsing=
==xquery:parse==
{{Announce|Updated with Version 10:}} {{Code|$query}} can additionally be of type {{Code|xs:anyURI}}.
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|xquery:parse|$query as xs:stringanyAtomicType|item()?}}<br />{{Func|xquery:parse|$query as xs:stringanyAtomicType, $options as map(*)?|item()?}}<br />|-valign="top"
| '''Summary'''
|Parses the specified {{Code|$query}} string as XQuery module and returns the resulting query plan. If the query is of type {{Code|xs:anyURI}}, the module located at this URI will be retrieved (a relative URI will be resolved against the static base URI). Otherwise, the input is expected to be of type {{Code|xs:string}}. The {{Code|$options}} parameter influences the output:
* {{Code|compile}}: additionally compiles the query after parsing it. By default, this option is {{Code|false}}.
* {{Code|plan}}: returns an XML representation of the internal query plan. By default, this option is {{Code|true}}. The naming of the expressions in the query plan may change over time
* {{Code|pass}}: passes on by default, the original option is {{Code|false}}. If an error info (is raised, the line and /column number, and the optional file uri)will refer to the location of the function call. By default, this If the option is {{Code|false}}enabled, the line/column and file uri will be adopted from the raised error.
* {{Code|base-uri}}: set [https://www.w3.org/TR/xquery-31/#dt-static-base-uri base-uri property] for the query. This URI will be used when resolving relative URIs by functions such as {{Code|fn:doc}}.
|-valign="top"
| '''Errors'''
|Any error that may occur while parsing the query.
|-valign="top"
| '''Examples'''
|
* {{Code|xquery:parse("1 + 3")}} returns:
<pre classsyntaxhighlight lang='brush:"xml'">
<MainModule updating="false">
<QueryPlan compiled="false">
</QueryPlan>
</MainModule>
</presyntaxhighlight>|} ==xquery:parse-uri== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|xquery:parse-uri|$uri as xs:string|item()?}}<br />{{Func|xquery:parse-uri|$uri as xs:string, $options as map(*)?|item()?}}<br />|-| '''Summary'''|Parses the XQuery module located at {{Code|$uri}} and returns the resulting query plan. A relative URI will be resolved against the static base URI of the query. The rules for the {{Code|$options}} parameter are the same as for [[#xquery:parse|xquery:parse]].|-| '''Errors'''|Any error that may occur while parsing the query.
|}
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|xquery:fork-join|$functions as function(*)*|item()*}}
|-valign="top"
|'''Summary'''
|This function executes the supplied (non-updating) functions in parallel.
|-valign="top"
| '''Examples'''
|
* The following function sleeps in parallel; it will be finished in 1 second if your system has at least 2 cores:
<pre classsyntaxhighlight lang='brush:"xquery'">
let $f := function() { prof:sleep(1000) }
return xquery:fork-join(($f, $f))
</presyntaxhighlight>
* In the following query, up to four URLs will be requested in parallel:
<pre classsyntaxhighlight lang='brush:"xquery'">
xquery:fork-join(
for $segment in 1 to 4
return function() { http:send-request((), $url) }
)
</presyntaxhighlight>|-valign="top"
|'''Errors'''
|{{Error|error|#Errors}} an unexpected error occurred.
! width="110"|Code
|Description
|-valign="top"
|{{Code|permission}}
|Insufficient permissions for evaluating the query.
|-valign="top"
|{{Code|update}}
|[[XQuery Update#Updating Expressions|updating expression]] found or expected.
|-valign="top"
|{{Code|timeout}}
|Query execution exceeded timeout.
|-valign="top"
|{{Code|memory}}
|Query execution exceeded memory limit.
|-valign="top"
|{{Code|nested}}
|Nested query evaluation is not allowed.
|-valign="top"
|{{Code|error}}
|An unexpected error occurred.
=Changelog=
;Version 10
* Deleted: xquery:parse-uri (merged with {{Function||xquery:parse}})
* Updated: {{Function||xquery:parse}}: {{$query}} can additionally be of type {{Code|xs:anyURI}}.
;Version 9.2
* Deleted: xquery:invoke, xquery:invoke-update (merged with [[#xquery:eval{{Function||xquery:eval]] }} and [[#xquery:eval-update{{Function||xquery:eval-update]]}})
;Version 9.0
* Added: [[#xquery:invoke-update{{Function||xquery:invoke-update]]}}* Updated: [[#xquery:eval{{Function||xquery:eval]]}}: {{Code|pass}} option added* Updated: [[#xquery:parse{{Function||xquery:parse]]}}, [[#xquery:parse-uri{{Function||xquery:parse-uri]]}}: {{Code|base-uri}} option added* Updated: xquery:update renamed to [[#xquery:eval-update{{Function||xquery:eval-update]]}}
* Updated: error codes updated; errors now use the module namespace
;Version 8.5
* Added: [[#xquery:fork-join{{Function||xquery:fork-join]]}}* Updated: [[#xquery:eval{{Function||xquery:eval]]}}: {{Code|base-uri}} option added
* Updated: Relative URIs will always be resolved against the static base URI of the query
* Deleted: xquery:type (moved to [[Profiling Module]])
;Version 8.4
* Added: [[#xquery:parse-uri{{Function||xquery:parse-uri]]}}* Updated: [[#xquery:parse{{Function||xquery:parse]]}}: {{Code|pass}} option added
;Version 8.0
* Added: xquery:update, [[#xquery:parse{{Function||xquery:parse]]}}
* Deleted: xquery:evaluate (opened databases will now be closed by main query)
;Version 7.8
* Added: [[#xquery:evaluate{{Function||xquery:evaluate]]}}
* Updated: used variables must be explicitly declared in the query string.
This module was introduced with Version 7.3. Functions have been adopted from the obsolete Utility Module.