Difference between revisions of "XQuery Module"
Jump to navigation
Jump to search
Line 16: | Line 16: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Evaluates {{Code|$query}} as XQuery expression | + | |Evaluates the supplied {{Code|$query}} string as XQuery expression and returns the resulting items.<br/>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.<br />Variables and context items can be declared via {{Code|$bindings}}. The specified keys must be QNames or strings: |
* If a key is a QName, it will be directly adopted as variable name. | * If a key is a QName, it will be directly adopted as variable name. | ||
* It a key is a string, it may be prefixed with a dollar sign. Namespace can be specified using the [http://www.jclark.com/xml/xmlns.htm Clark Notation]. | * It a key is a string, it may be prefixed with a dollar sign. Namespace can be specified using the [http://www.jclark.com/xml/xmlns.htm Clark Notation]. | ||
Line 87: | Line 87: | ||
| '''Errors''' | | '''Errors''' | ||
|{{Error|BXXQ0002|#Errors}} the query contains no [[XQuery Update#Updating Expressions|updating expressions]].<br/>{{Error|BXXQ0003|#Errors}} insufficient permissions for evaluating the query.<br/>{{Error|BXXQ0004|#Errors}} query execution exceeded timeout or memory constraints.<br/>{{Error|FOTY0013|#Errors}} the expression yields function items. | |{{Error|BXXQ0002|#Errors}} the query contains no [[XQuery Update#Updating Expressions|updating expressions]].<br/>{{Error|BXXQ0003|#Errors}} insufficient permissions for evaluating the query.<br/>{{Error|BXXQ0004|#Errors}} query execution exceeded timeout or memory constraints.<br/>{{Error|FOTY0013|#Errors}} the expression yields function items. | ||
+ | |} | ||
+ | |||
+ | ==xquery:parse== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|xquery:parse|$query as xs:string|item()*}}<br />{{Func|xquery:eval|$query as xs:string, $options as item()|item()}}<br /> | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Parses the specified {{Code|$query}} string as XQuery module and returns information on the resulting query plan (please note that the naming of the expressions in the query plan may change over time). The {{Code|$options}} parameters can be specified in two ways: | ||
+ | * as children of an {{Code|<xquery:options/>}} element: | ||
+ | <pre class="brush:xml"> | ||
+ | <xquery:options> | ||
+ | <xquery:compile value="true"/> | ||
+ | </xquery:options> | ||
+ | </pre> | ||
+ | * as map, which contains all key/value pairs: | ||
+ | <pre class="brush:xml"> | ||
+ | map { "compile": true() } | ||
+ | </pre> | ||
+ | The following options are available: | ||
+ | * {{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}}. | ||
+ | |- | ||
+ | | '''Errors''' | ||
+ | |{{Error|BXXQ0003|#Errors}} insufficient permissions for evaluating the query. | ||
+ | |- | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | * {{Code|xquery:parse("1 + 3")}} returns: | ||
+ | <pre class='brush:xml'> | ||
+ | <MainModule updating="false"> | ||
+ | <QueryPlan compiled="false"> | ||
+ | <Arith op="+"> | ||
+ | <Int value="1" type="xs:integer"/> | ||
+ | <Int value="3" type="xs:integer"/> | ||
+ | </Arith> | ||
+ | </QueryPlan> | ||
+ | </MainModule> | ||
+ | </pre> | ||
|} | |} | ||
Line 136: | Line 177: | ||
;Version 8.0 | ;Version 8.0 | ||
− | * Added: [[#xquery:update|xquery:update]] | + | * Added: [[#xquery:update|xquery:update]], [[#xquery:parse|xquery:parse]] |
* Deleted: [[#xquery:evaluate|xquery:evaluate]] (opened databases will now be closed by main query) | * Deleted: [[#xquery:evaluate|xquery:evaluate]] (opened databases will now be closed by main query) | ||
Revision as of 20:14, 23 December 2014
This XQuery Module contains functions for evaluating XQuery strings and modules at runtime.
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
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 the supplied $query string as XQuery expression 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
<xquery:options> <xquery:permission value="none"/> </xquery:options>
map { "permission": "none" } The following options are available:
|
Errors | BXXQ0001 : the query contains updating expressions.BXXQ0003 : insufficient permissions for evaluating the query.BXXQ0004 : query execution exceeded timeout or memory constraints.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:update
Signatures | xquery:update($query as xs:string) as item()* xquery:update($query as xs:string, $bindings as map(*)) as item()* xquery:update($query as xs:string, $bindings as map(*), $options as item()) as item() |
Summary | Evaluates $query as updating XQuery expression at runtime.All updates will be added to the Pending Update List of the main query and performed after the evaluation of the main query. |
Errors | BXXQ0002 : the query contains no updating expressions.BXXQ0003 : insufficient permissions for evaluating the query.BXXQ0004 : query execution exceeded timeout or memory constraints.FOTY0013 : the expression yields function items.
|
xquery:parse
Signatures | xquery:parse($query as xs:string) as item()* xquery:eval($query as xs:string, $options as item()) as item() |
Summary | Parses the specified $query string as XQuery module and returns information on the resulting query plan (please note that the naming of the expressions in the query plan may change over time). The $options parameters can be specified in two ways:
<xquery:options> <xquery:compile value="true"/> </xquery:options>
map { "compile": true() } The following options are available:
|
Errors | BXXQ0003 : insufficient permissions for evaluating the query.
|
Examples |
<MainModule updating="false"> <QueryPlan compiled="false"> <Arith op="+"> <Int value="1" type="xs:integer"/> <Int value="3" type="xs:integer"/> </Arith> </QueryPlan> </MainModule> |
xquery:invoke
Signatures | xquery:invoke($uri as xs:string) as item()* xquery:invoke($uri as xs:string, $bindings as map(*)) as item()* xquery:invoke($uri as xs:string, $bindings as map(*), $options as item()) 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.BXXQ0003 : insufficient permissions for evaluating the query.BXXQ0004 : query execution exceeded timeout.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
|
The specified query contains updating expressions. |
BXXQ0002
|
The specified query contains no updating expressions. |
BXXQ0003
|
Insufficient permissions for evaluating the query. |
BXXQ0004
|
Query execution exceeded timeout. |
Changelog
- Version 8.0
- Added: xquery:update, xquery:parse
- Deleted: xquery:evaluate (opened databases will now be closed by main query)
- Version 7.8.2
- Added:
$options
argument
- 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.