Difference between revisions of "XQuery Module"

From BaseX Documentation
Jump to navigation Jump to search
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|Introduced with Version 7.8:}}
+
{{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}} parameter is the same as for [[#xquery:eval|xquery:eval]].
+
|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 23: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.

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:
  • variables specified as QNames will be directly interpreted as variable name.
  • variables specified as xs:string may be prefixed with a dollar sign. Namespace can be specified using the Clark Notation.
  • If the specified string is empty, the value will be bound to the context item.

The $options parameter contains evaluation options, which can either be specified

  • as children of an <xquery:options/> element:
<xquery:options>
  <xquery:permission value="none"/>
</xquery:options>
  • as map, which contains all key/value pairs:
map { "permission" := "none" }

The following options are available:

  • permission: the query will be evaluated with the specified permissions (see [User Management]).
  • timeout: query execution will be interrupted after the specified number of seconds.
Errors BXXQ0001: the query contains updating expressions.
FOTY0013: the expression yields function items.
Examples
  • xquery:eval("1+3") returns 4.
  • You can bind the context and e.g. operate on a certain database only:
xquery:eval("//country", map { '' := db:open('factbook') })
  • The following expressions use strings as keys. All of them return 'XML':
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' }
)
  • The following expressions use QNames as keys. All of them return '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:
  • All items will be directly returned and not duplicated. This way, queries will be evaluated faster, and database nodes will retain their node identity.
  • In exchange, it is not possible to open new databases.
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.

Retrieved from "https://old.docs.basex.org/index.php?title=XQuery_Module&oldid=10475"