Difference between revisions of "XQuery Module"
Line 11: | Line 11: | ||
==xquery:eval== | ==xquery:eval== | ||
+ | |||
+ | {{Mark|Updated with Version 7.8.2:}} {{Code|$options}} argument added. | ||
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|xquery:eval|$query as xs:string|item()*}}<br />{{Func|xquery:eval|$query as xs:string, $bindings as map(*)|item()*}}<br /> | + | |{{Func|xquery:eval|$query as xs:string|item()*}}<br />{{Func|xquery:eval|$query as xs:string, $bindings as map(*)|item()*}}<br />{{Func|xquery:eval|$query as xs:string, $bindings as map(*), $options as item()|item()}}<br /> |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 21: | Line 24: | ||
* variables specified as xs:string may be prefixed with a dollar sign. Namespace can be specified using the [http://www.jclark.com/xml/xmlns.htm Clark Notation]. | * variables specified as xs:string may be prefixed with a dollar sign. Namespace can be specified using the [http://www.jclark.com/xml/xmlns.htm Clark Notation]. | ||
* If the specified string is empty, the value will be bound to the context item. | * If the specified string is empty, the value will be bound to the context item. | ||
+ | The {{Code|$options}} parameter contains evaluation options, which can either be specified | ||
+ | * as children of an {{Code|<xquery:options/>}} element: | ||
+ | <pre class="brush:xml"> | ||
+ | <xquery:options> | ||
+ | <xquery:permission value="none"/> | ||
+ | </xquery:options> | ||
+ | </pre> | ||
+ | * as map, which contains all key/value pairs: | ||
+ | <pre class="brush:xml"> | ||
+ | map { "permission" := "none" } | ||
+ | </pre> | ||
+ | The following options are available: | ||
+ | * {{Code|permission}}: the query will be evaluated with the specified permissions (see [User Management]). | ||
+ | * {{Code|timeout}}: query execution will be interrupted after the specified number of seconds. | ||
|- | |- | ||
| '''Errors''' | | '''Errors''' | ||
Line 61: | Line 78: | ||
==xquery:evaluate== | ==xquery:evaluate== | ||
− | {{Mark| | + | {{Mark|Updated with Version 7.8.2:}} {{Code|$options}} argument added. |
{| width='100%' | {| width='100%' | ||
Line 78: | Line 95: | ||
==xquery:invoke== | ==xquery:invoke== | ||
+ | |||
+ | {{Mark|Updated with Version 7.8.2:}} {{Code|$options}} argument added. | ||
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
Line 84: | Line 104: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Opens {{Code|$uri}} as file, evaluates it as XQuery expression at runtime, and returns the resulting items. Database nodes in the result will be copied and returned instead.<br />The semantics of the {{Code|$bindings}} | + | |Opens {{Code|$uri}} as file, evaluates it as XQuery expression at runtime, and returns the resulting items. Database nodes in the result will be copied and returned instead.<br />The semantics of the {{Code|$bindings}} and {{Code|$options}} parameters is the same as for [[#xquery:eval|xquery:eval]]. |
|- | |- | ||
| '''Errors''' | | '''Errors''' | ||
Line 117: | Line 137: | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 7.8.2 | ||
+ | * {{Code|$options}} argument added to functions. | ||
;Version 7.8 | ;Version 7.8 |
Revision as of 22:19, 6 March 2014
This XQuery Module contains functions for evaluating XQuery strings and modules at runtime.
Since Template:Mark, used variables must be explicitly declared in the query string via the declare variable
statement.
Contents
Conventions
All functions in this module are assigned to the http://basex.org/modules/xquery
namespace, which is statically bound to the xquery
prefix.
All errors are assigned to the http://basex.org/errors
namespace, which is statically bound to the bxerr
prefix.
Functions
xquery:eval
Template:Mark $options
argument added.
Signatures | xquery:eval($query as xs:string) as item()* xquery:eval($query as xs:string, $bindings as map(*)) as item()* xquery:eval($query as xs:string, $bindings as map(*), $options as item()) as item() |
Summary | Evaluates $query as XQuery expression at runtime and returns the resulting items.The evaluated query has its own query context. If a returned node is stored in a database, a main-memory copy will be returned as result, because the referenced database is closed after query execution and will not be accessible anymore. Variables and context items can be declared via $bindings . The specified keys must be QNames or strings, the values can be arbitrary item sequences:
The
<xquery:options> <xquery:permission value="none"/> </xquery:options>
map { "permission" := "none" } The following options are available:
|
Errors | BXXQ0001 : the query contains updating expressions.FOTY0013 : the expression yields function items.
|
Examples |
xquery:eval("//country", map { '' := db:open('factbook') })
xquery:eval(".", map { '': 'XML' }), xquery:eval("declare variable $xml external; $xml", map { 'xml' := 'XML' }), xquery:eval( "declare namespace pref='URI'; declare variable $pref:xml external; $pref:xml", map { '{URI}xml': 'XML' } )
declare namespace pref = 'URI'; xquery:eval("declare variable $xml external; $xml", map { xs:QName('xml'): 'XML' }), let $query := "declare namespace pref='URI'; declare variable $pref:xml external; $pref:xml" let $vars := map { xs:QName('pref:xml'): 'XML' } return xquery:eval($query, $vars) |
xquery:evaluate
Template:Mark $options
argument added.
Signatures | xquery:evaluate($query as xs:string) as item()* xquery:evaluate($query as xs:string, $bindings as map(*)) as item()* |
Summary | Evaluates $query as XQuery expression at runtime and returns the resulting items.The function differs from xquery:eval in two ways:
|
Errors | BXXQ0001 : the query contains updating expressions.BXXQ0002 : the addressed database cannot be opened.FOTY0013 : the expression yields function items.
|
xquery:invoke
Template:Mark $options
argument added.
Signatures | xquery:invoke($uri as xs:string) as item()* xquery:invoke($uri as xs:string, $bindings as map(*)) as item()* |
Summary | Opens $uri as file, evaluates it as XQuery expression at runtime, and returns the resulting items. Database nodes in the result will be copied and returned instead.The semantics of the $bindings and $options parameters is the same as for xquery:eval.
|
Errors | BXXQ0001 : the expression contains updating expressions.FOTY0013 : the expression yields function items.
|
xquery:type
Signatures | xquery:type($expr as item()*) as item()*
|
Summary | Similar to fn:trace($expr, $msg) , but instead of a user-defined message, it emits the compile-time type and estimated result size of its argument.
|
Errors
Code | Description |
---|---|
BXXQ0001
|
A dynamically evaluated query must not contain updating expressions. |
BXXQ0002
|
The addressed database cannot be opened. |
Changelog
Changelog
- Version 7.8.2
$options
argument added to functions.
- Version 7.8
- Added: 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.