XQuery Extensions

From BaseX Documentation

Jump to: navigation, search

This article is part of the XQuery Portal. It lists extensions and optimizations that are specific to the BaseX XQuery processor.

Contents

[edit] Expressions

Introduced with Version 9.1: ternary if, elvis operator, if without else

Some of the extensions that have been added to BaseX may also be made available in other XQuery processors in the near future.

[edit] Ternary If

The ternary if operator provides a short syntax for conditions. It is also called conditional operator or ternary operator. In most languages, the syntax is a ? b : c. As ? and : have already been taken in XQuery, the syntax of Perl 6 is used:

$test ?? 'ok' !! 'fails'

The expression returns ok if the effective boolean value of $test is true, and it returns fails otherwise.

[edit] Elvis Operator

The Elvis operator is also available in other languages. It is sometimes called null-coalescing operator. In XQuery, the value of the first operand will be returned if it is a non-empty sequence. Otherwise, the value of the second operand will be returned.

let $number := 123
return (
  (: if/then/else :)
  if (exists($number)) then $number else 0,
  (: elvis operator :)
  $number ?: 0
)

The behavior of the operator is equivalent to the util:or function.

[edit] If Without Else

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 $b 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 $b is true'
)

The behavior of the if expression is equivalent to the util:if function.

[edit] Functions

[edit] Regular Expressions

Introduced with Version 9.1:

In analogy with Saxon, 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')

[edit] Serialization

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

[edit] Option Declarations

[edit] 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 Module namespace. All values will be reset after the evaluation of a query:

declare option db:chop 'false';
doc('doc.xml')

[edit] XQuery Locks

If XQuery Locks are defined in the query prolog of a module, access to functions of this module locks will be controlled by the central transaction management.

If the following XQuery code is called by two clients in parallel, the queries will be evaluated one after another:

declare option basex:write-lock 'CONFIGLOCK';
file:write('config.xml', <config/>)

[edit] Pragmas

[edit] 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 non-deterministic, optimizations and query rewritings can be suppressed:

sum( (# basex:non-deterministic #) {
  1 to 100000000
})

This pragma can be helpful when debugging your code.

Introduced with Version 9.1:

In analogy with option declarations and function annotations, XQuery Locks can also set via pragmas:

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

[edit] Database Pragmas

All local options can be assigned via pragmas. Some examples:

(# db:enforceindex #) {
  for $db in ('persons1', 'persons2', 'persons3')
  return db:open($db)//name[text() = 'John']
}
file:write(
  'wrapped-db-nodes.xml',
  (# db:copynode false #) {
    <xml>{ db:open('huge') }</xml>
  }
)

[edit] Annotations

[edit] 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

[edit] Lazy Evaluation

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

Example:

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

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

[edit] XQuery Locks

Introduced with Version 9.1:

In analogy with option declarations and pragmas, XQuery Locks can also set via annotations:

declare %basex:write-lock('CONFIGLOCK') function local:write() {
  file:write('config.xml', <config/>)
};

[edit] Non-Determinism

In XQuery, deterministic functions are “guaranteed to produce ·identical· results from repeated calls within a single ·execution scope· if the explicit and implicit arguments are identical”. In BaseX, many extension functions are non-deterministic or side-effecting. If an expression is internally flagged as non-deterministic, various optimizations that might change their execution order will not be applied.

(: QUERY A... :)
let $n := 456
for $i in 1 to 2
return $n

(: ...will be optimized to :)
for $i in 1 to 2
return 456

(: QUERY B will not be rewritten :)
let $n := random:integer()
for $i in 1 to 2
return $n

In some cases, functions may contain non-deterministic code, but the query compiler may not be able to detect this statically. See the following example:

for $read in (file:read-text#1, file:read-binary#1)
let $ignored := non-deterministic $read('input.file')
return ()

Two non-deterministic functions will be bound to $read, and the result of the function call will be bound to $ignored. As the variable is not referenced in the subsequent code, the let clause would usually be discarded by the compiler. In the given query, however, execution will be enforced because of the BaseX-specific non-deterministic keyword.

[edit] 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:

'Hello World!'
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.

[edit] Miscellaneous

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

[edit] Changelog

Version 9.1
Personal tools
Namespaces
Variants
Actions
Navigation
Print/export