XQuery Functions

This module contains functions for parsing and evaluating XQuery strings at runtime, and to run code in parallel.

The Job Functions can be used to register and run queries as separate jobs.

Conventions

All functions and errors are in the http://basex.org/modules/xquery namespace, to which the xquery prefix is statically bound.

Evaluation

xquery:eval

Updated: A function item can be invoked instead of a query. Allow decimal places for timeout value. The permission option also applies to returned function items.

xquery:eval(  $query     as (xs:string|xs:anyURI|fn(*)),  $bindings  as (map((xs:string|xs:QName), item()*)|array(*))?  := {},  $options   as map(*)?  := {}) as item()*

xquery:eval("1+3")

xquery:eval(fn($name) { 'Hello ' || $name }, [ 'World' ])

xquery:eval(xs:anyURI('cleanup.xq'))

xquery:eval("//country", { '': db:get('factbook') })

xquery:eval(".", { '': 'XML' }),

xquery:eval(
  "declare variable $xml external; $xml",
  { 'xml': 'XML' }
),

xquery:eval(
  "declare namespace pref='URI';
   declare variable $pref:xml external;
   $pref:xml",
  { '{URI}xml': 'XML' }
)

declare namespace pref = 'URI';

xquery:eval(
  "declare variable $xml external; $xml",
  { #xml: 'XML' }
),

let $query := "declare namespace pref='URI';
               declare variable $pref:xml external;
               $pref:xml"
let $vars := { #pref:xml: 'XML' }
return xquery:eval($query, $vars)

xquery:eval-update

Updated: A function item can be invoked instead of a query.

xquery:eval-update(  $query     as (xs:string|xs:anyURI|fn(*)),  $bindings  as (map((xs:string|xs:QName), item()*)|array(*))?  := (),  $options   as map(*)?  := ()) as empty-sequence()

xquery:eval-update("
  delete node db:get('tmp')/*,
  update:output('TEMPORARY DATABASE WAS CLEANED UP')
")

Function Items

Instead of a query, a function item can be supplied to xquery:eval, xquery:eval-update, job:eval, job:execute and ws:eval. It is invoked with the arguments of the $bindings array, which must match its arity, as with fn:apply. Maps and arrays are function items as well, but they are rejected with a type error.

A function item carries the compiled code and the static context of the query that created it, and must therefore be independent of that query. Captured values, the captured query focus and supplied arguments are copied; function items occurring in them are checked as well. Databases can be accessed in the function body: they are opened and locked by the nested query. Some accepted queries:

declare function local:f() { count(db:get('db')//a) };
declare variable $v := random:integer();

xquery:eval(fn() { $v })
xquery:eval(local:f#0)

(: the captured node is copied :)
let $n := db:get('db')/a
return xquery:eval(fn() { name($n) })

xquery:eval(fn() { count(db:get('db')//a) })

A basex:eval error is raised if the function depends on the calling query:

(: nodes of static variables are not copied :)
declare variable $v := db:get('db');
xquery:eval(fn() { count($v//a) })

(: the context value is not part of the function signature: :)
xquery:eval(fn() { . })

(: the context value is not part of the function signature :)
xquery:eval(fn() { . })

(: static variables with Java objects :)
xquery:eval(fn() { Q{java:java.lang.Math}abs(-1) })

(: the function body is rewritten for index access :)
let $x := db:get('db')//a[1]/string()
let $f := fn() { db:get('db')//a[text() = $x] }
return ($f(), xquery:eval($f))

The code is compiled by the calling query. Functions annotated with %basex:eval are compiled without accessing the dynamic context of the calling query: databases are not opened, and fn:current-dateTime returns the time of the nested query. Inline functions that are directly supplied as function or bindings argument are annotated automatically. Functions that are referenced via variables or function calls must be annotated explicitly. Other functions may be optimized with the dynamic context of the calling query: their bodies may be rewritten for index access, which results in the error shown above, and fn:current-dateTime may return the time of the calling query.

As no query text is parsed, the options that address it have no effect: the function keeps the base-uri of the query that created it, and there is no query location that could be reported with pass. The permission option constrains the code that is compiled in the nested context; it does not apply to code that was already compiled by the calling query, because the permissions of a function are checked when it is compiled, not when it is invoked.

Parsing

xquery:parse

xquery:parse(  $query    as (xs:string|xs:anyURI),  $options  as map(*)?  := {}) as element()create

xquery:parse("1 + 3")

<MainModule updating="false">
  <QueryPlan compiled="false" updating="false">
    <Arith op="+" type="xs:anyAtomicType?">
      <Itr type="xs:integer" size="1">1</Itr>
      <Itr type="xs:integer" size="1">3</Itr>
    </Arith>
  </QueryPlan>
</MainModule>

Parallel Execution

Parallel query execution is recommended if you have various calls that require a lot of time, but that cannot be sped up by rewriting the code. This is the case, for example, if external URLs are called. If you are parallelizing local data reads (such as the access to a database), single-threaded queries will usually be faster, because parallelized access to disk data often results in randomized access patterns, which will rarely be optimized by the caching strategies of HDDs, SSDs, or the operating system.

xquery:for-each

Added: New function.

xquery:for-each(  $input    as item()*,  $action   as fn($item as item(), $pos as xs:integer) as item()*,  $options  as map(*)?  := {}) as item()*admin

xquery:for-each(
  1 to 100,
  fn($segment) { http:send-request((), 'http://url.com/path/' || $segment) },
  { 'parallel': 8 }
)

xquery:for-each(1 to 5, fn($n) { $n * $n })

xquery:fork-join

Updated: report and timeout options added.

xquery:fork-join(  $functions  as fn(*)*,  $options    as map(*)?  := {}) as item()*admin

xquery:fork-join(
  for $segment in 1 to 100
  let $url := 'http://url.com/path/' || $segment
  return fn() { http:send-request((), $url) },
  { 'parallel': 8 }
)

let $f := fn() { prof:sleep(1000) }
return xquery:fork-join(($f, $f))

xquery:fork-join(
  (true#0, error#0, false#0),
  { 'report': true() }
)

xquery:fork-any

Added: New function.

xquery:fork-any(  $functions  as fn(*)*,  $options    as map(*)?  := {}) as item()*admin

xquery:fork-any(
  for $url in ('https://mirror1.example/data', 'https://mirror2.example/data')
  return fn() { http:send-request((), $url) }
)

xquery:reduce

Added: New function.

xquery:reduce(  $input    as item()*,  $init     as item()*,  $action   as fn($acc as item()*, $item as item()) as item()*,  $combine  as fn($acc1 as item()*, $acc2 as item()*) as item()*,  $options  as map(*)?  := {}) as item()*admin

xquery:reduce(1 to 1000000, 0, op('+'), op('+'))

Errors

Changelog

• Added: xquery:for-each: New function for parallel iteration.
• Added: xquery:reduce: New function for parallel aggregation.
• Added: xquery:fork-any: New function returning the first available result.
• Updated: xquery:eval: A function item can be invoked instead of a query. Allow decimal places for timeout value. The permission option also applies to returned function items.
• Updated: xquery:eval-update: A function item can be invoked instead of a query.
• Updated: xquery:fork-join: report and timeout options added.
• Updated: xquery:parse: optimize option added.

• Updated: xquery:fork-join: Options added.
• Updated: The Clark notation was replaced with the Expanded QNames notation.

• Updated: xquery:parse: $query can additionally be of type xs:anyURI.
• Removed: xquery:parse-uri (merged with xquery:parse)

• Removed: xquery:invoke, xquery:invoke-update (merged with xquery:eval and xquery:eval-update)

• Added: xquery:invoke-update
• Updated: xquery:eval: pass option added
• Updated: xquery:parse, xquery:parse-uri: base-uri option added
• Updated: xquery:update renamed to xquery:eval-update
• Updated: error codes updated; errors now use the module namespace

• Added: xquery:fork-join
• Updated: xquery:eval: base-uri option added
• Updated: Relative URIs will always be resolved against the static base URI of the query
• Removed: xquery:type (moved to Profiling Functions)

• Added: xquery:parse-uri
• Updated: xquery:parse: pass option added

• Added: xquery:update, xquery:parse
• Removed: xquery:evaluate (opened databases will now be closed by main query)

• Added: $options argument

• Added: xquery:evaluate
• Updated: used variables must be explicitly declared in the query string.

• Added: New module added. Functions have been adopted from the obsolete Utility Module.