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.

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

xquery:eval("1+3")

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

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

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

Parsing

xquery:parse

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

xquery:parse("1 + 3")

<MainModule updating="false">
  <QueryPlan compiled="false" updating="false">
    <Arith op=" " type="xs:anyAtomicType?">
      <Int type="xs:integer" size="1">1</Int>
      <Int type="xs:integer" size="1">3</Int>
    </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()*,
  $options  as map(*)?                := {}
) as item()*

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()*

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()*

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(item()*, item()) as item()*,
  $combine  as fn(item()*, item()*) as item()*,
  $options  as map(*)?                          := {}
) as item()*

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: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.
• Deleted: xquery:parse-uri (merged with xquery:parse)

• Deleted: 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
• Deleted: xquery:type (moved to Profiling Functions)

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

• Added: xquery:update, xquery:parse
• Deleted: 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.