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 in this module are assigned to the http://basex.org/modules/xquery namespace, which is statically bound to the xquery prefix.

Evaluation

xquery:eval

Updated: Allow decimal places for timeout value.

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

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: a basex:transfer error is raised if its body invokes Java code or accesses an already opened database. Captured values, the captured query focus and supplied arguments are copied; function items occurring in them are checked as well.

• Accepted: let $n := db:get('db')/a return xquery:eval(fn() { name($n) }), as the captured node is copied
• Accepted: declare variable $v := random:integer(); xquery:eval(fn() { $v })
• Rejected: xquery:eval(fn() { . }), as the context value is not part of the function signature
• Rejected: xquery:eval(fn() { Q{java:java.lang.Math}abs(-1) })

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:fork-any: New function returning the first available result.
• Added: xquery:reduce: New function for parallel aggregation.
• Updated: xquery:fork-join: report and timeout options added.
• Updated: xquery:eval: Allow decimal places for timeout value.
• Updated: xquery:eval, xquery:eval-update: a function item can be invoked instead of a query.

• 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.