Main Page » XQuery » XQuery Extensions

XQuery Extensions

This article lists extensions and optimizations that are specific to the BaseX XQuery processor.

In XQuery 3.1, both branches of the if expression need to be specified. In many cases, only one branch is required, so the else branch was made optional in BaseX. If the second branch is omitted, an empty sequence will be returned if the effective boolean value of the test expression is false. Some examples:

if (doc-available($doc)) then doc($doc),
if (file:exists($file)) then file:delete($file),
if (permissions:valid($user)) then <html>Welcome!</html>

If conditions are nested, a trailing else branch will be associated with the innermost if:

if ($a) then if ($b) then '$a and $b is true' else 'only $a is true'

In general, if you have multiple or nested if expressions, additional parentheses can improve the readibility of your code:

if ($a) then (
  if ($b) then '$a and $b is true' else 'only $a is true'
)

Error Handling

With $err:additional, the stack trace can be retrieved in a try/catch clause. The returned trace is a sequence of strings that refer to the position in the code that failed and the function call that led to the error. Every string consists of the module path and a line and column number.

Note that the executed code is an optimized version of the source code. As a consequence, the trace does not necessarily contain all function calls of the original code. For example, the following returns contains a single string test.xq, 1/30, because $f will be inlined by the compiler:

(: test.xq :)
let $f := fn() { error() }
return try { $f() } catch * { $err:additional }

You can disable function inlining by setting INLINELIMIT to 0, either globally or locally:

let $f := %basex:inline(0) fn() { error() }
return try { $f() } catch * { $err:additional }

…returns…

test.xq, 1/47
test.xq, 2/16

Functions

Regular Expressions

You can specify the flag j to revert to Java’s default regex parser. For example, this allows you to use the word boundary option \b, which has not been included in the XQuery grammar for regular expressions:

Example:

(: yields "!Hi! !there!" :)
replace('Hi there', '\b', '!', 'j')

Serialization

basex is used as the default serialization method: Nodes are serialized as XML, atomic values are serialized as strings, and binary items are output in their native byte representation. Function items (including maps and arrays) are output as with the Adaptive Serialization method.
With csv, you can output XML nodes as CSV data (see the CSV Functions for more details).
With json, items are output as JSON as described in the official specification. If the root node is of type element(json), items are serialized as described for JSON Functions and the direct format.

For more information and some additional BaseX-specific parameters, see the article on Serialization.

Option Declarations

Database Options

Local database options can be set in the prolog of an XQuery main module. In the option declaration, options need to be bound to the Database Functions namespace. All values will be reset after the evaluation of a query:

declare option db:catalog 'etc/w3-catalog.xml';
doc('doc.xml')

XQuery Locks

If locks are declared in the query prolog of a module via the basex:lock option, access to functions of this module locks will be controlled by the central transaction management. See Transaction Management for further details.

Pragmas

BaseX Pragmas

Many optimizations in BaseX will only be performed if an expression is deterministic (i.e., if it always yields the same output and does not have side effects). By flagging an expression as nondeterministic, optimizations and query rewritings can be suppressed:

sum( (# basex:nondeterministic #) {
  1 to 100000000
})

This pragma can be helpful when debugging your code.

In analogy with option declarations and function annotations, XQuery locks can also set via pragmas. See Transaction Management for details and examples.

(# basex:write-lock CONFIGLOCK #) {
  file:write('config.xml', <config/>)
}

Database Pragmas

Local database options can also be assigned via pragmas:

Index access rewritings can be enforced. This is helpful if the name of a database is not static (see Enforce Rewritings for more details):
```
(# db:enforceindex #) {
  for $db in ('persons1', 'persons2', 'persons3')
  return db:get($db)//name[text() = 'John']
}
```
Node copying in node constructors can be disabled (see COPYNODE for more details). The following query will consume much less memory than without pragma as the database nodes will not be fully duplicated, but only attached to the xml parent element:
```
file:write(
  'wrapped-db-nodes.xml',
  (# db:copynode false #) {
    <xml>{ db:get('huge') }</xml>
  }
)
```
An XML catalog can be specified for URI rewritings. See the Catalog Resolver section for an example.

Annotations

Function Inlining

%basex:inline([limit]) controls if functions will be inlined.

If XQuery functions are inlined, the function call will be replaced by a FLWOR expression, in which the function variables are bound to let clauses, and in which the function body is returned. This optimization triggers further query rewritings that will speed up your query. An example:

Query:

declare function local:square($a) { $a * $a };
for $i in 1 to 3
return local:square($i)

Query after function inlining:

for $i in 1 to 3
return
  let $a := $i
  return $a * $a

Query after further optimizations:

for $i in 1 to 3
return $i * $i

By default, XQuery functions will be inlined if the query body is not too large and does not exceed a fixed number of expressions, which can be adjusted via the INLINELIMIT option.

The annotation can be used to overwrite this global limit: Function inlining can be enforced if no argument is specified. Inlining will be disabled if 0 is specified.

Example:

(: disable function inlining; the full stack trace will be shown... :)
declare %basex:inline(0) function local:e() { error() };
local:e()

Result:

Stopped at query.xq, 1/53:
[FOER0000] Halted on error().

Stack Trace:
- query.xq, 2/9

Lazy Evaluation

%basex:lazy enforces lazy evaluation of a global variable.

Example:

declare %basex:lazy variable $january := doc('does-not-exist.xml');
if (month-from-date(current-date()) = 1) then $january else ()

The annotation ensures that an error is only raised if the condition yields true. Without the annotation, the error is always raised if the referenced document is not found.

XQuery Locks

In analogy with option declarations and pragmas, locks can also set via annotations. See Transaction Management for details and examples.

Namespaces

In XQuery, some namespaces are statically bound to prefixes. The following query requires no additional namespaces declarations in the query prolog:

<xml:abc xmlns:prefix='uri' local:fn='x'/>,
fn:exists(1)

In BaseX, various other namespaces are predefined. Apart from the namespaces that are listed on the Functions page, the following namespaces are statically bound:

Description	Prefix	Namespace URI
BaseX Annotations, Pragmas, …	`basex`	`http://basex.org`
RESTXQ: Input Options	`input`	`http://basex.org/modules/input`
EXPath Packages	`pkg`	`http://expath.org/ns/pkg`
XQuery Errors	`err`	`http://www.w3.org/2005/xqt-errors`
Serialization	`output`	`http://www.w3.org/2010/xslt-xquery-serialization`

Suffixes

In BaseX, files with the suffixes .xq, .xqm, .xqy, .xql, .xqu and .xquery are treated as XQuery files. In XQuery, there are main and library modules:

Main modules have an expression as query body. Here is a minimum example:
```
'Hello World!'
```

Library modules start with a module namespace declaration and have no query body:

module namespace hello = 'http://basex.org/examples/hello';

declare function hello:world() {
  'Hello World!'
};

We recommend .xq as suffix for for main modules, and .xqm for library modules. However, the actual module type will dynamically be detected when a file is opened and parsed.

Miscellaneous

Various other extensions are described in the articles on XQuery Full Text and XQuery Update.

Changelog

Version 11

Updated: Renamed from non-deterministic to nondeterministic.
Removed: Elvis operator ?:, in favor of the new otherwise expression.
Removed: Ternary if A ?? B !! C: in favor of the new deep lookup operator.

Version 9.1

Added: New Expressions: Ternary if, elvis Operator, if without else
Added: XQuery Locks via pragmas and function annotations.
Added: Regular Expressions, j flag for using Java’s default regex parser.

⚡Generated with XQuery