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

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",
  { xs:QName('xml'): 'XML' }
),

let $query := "declare namespace pref='URI';
               declare variable $pref:xml external;
               $pref:xml"
let $vars := { xs:QName('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>

Parallelized Execution

Parallel query execution is recommendable if you have various calls that require a lot of time, but that cannot be sped up by rewriting the code. This is e. g. the case 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:fork-join

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

Errors

Changelog

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