http://zorba.io/modules/zorba-query

View as XML or JSON.

This module contains functions to compile and evaluate queries written in either JSONiq or XQuery. Also, it contains function that allow to parameterize the static or dynamic evaluation phase.

Function Summary

bind-context-item ($query-key as xs:anyURI, $dot as item()) as empty-sequence() external

This function binds the context-item of the prepared query identified by the given key to the $dot argument.

bind-variable ($query-key as xs:anyURI, $var as xs:QName, $value as item()*) as empty-sequence() external

This function binds the variable with name $name of the prepared query identified by $query-key to the given sequence.

delete-query ($query-key as xs:anyURI) as empty-sequence() external

Deletes the prepared query associated with the given identifier.

evaluate-sequential ($query-key as xs:string) as item()* external

Evaluates the given prepared query and returns the result of the evaluation.

evaluate-updating ($query-key as xs:anyURI) external

Evaluates the given prepared query and applies the updates computed by this query.

evaluate ($query-key as xs:anyURI) as item()* external

Evaluates the given prepared query and returns the result of the evaluation.

external-variables ($query-key as xs:anyURI) as xs:QName* external

The function returns the names of the external variables that are declared in the given query (either in the main module or in any of the imported library modules).

is-bound-context-item ($query-key as xs:anyURI) as xs:boolean external

The function tests if the context-item is bound for the execution of the query referred to by the given query identifier.

is-bound-variable ($query-key as xs:anyURI, $var-name as xs:QName) as xs:boolean external

The function tests if the given variable is bound for the execution of the query referred to by the given query identifier.

is-sequential ($query-key as xs:anyURI) as xs:boolean external

The function tests if the query identified by the given key is sequential query.

is-updating ($query-key as xs:anyURI) as xs:boolean external

The function tests if the query identified by the given key is an updating query.

load-from-query-plan ($plan as xs:base64Binary) as xs:anyURI external

The function loads a given query for execution from a xs:base64Binary query plan, obtained through the zq:query-plan function.

load-from-query-plan ($plan as xs:base64Binary, $resolver as item()?, $mapper as item()?) as xs:anyURI external

The function loads a given query for execution from a xs:base64Binary query plan, obtained through the zq:query-plan function.

prepare-library-module ($library-module-text as xs:string) as empty-sequence() external

This function compiles a given XQuery or JSONiq library module.

prepare-main-module ($main-module-text as xs:string) as xs:anyURI external

The function prepares a given a query for execution.

prepare-main-module ($main-module-text as xs:string, $resolver as function (xs:string, xs:string) as item()??, $mapper as function (xs:string, xs:string) as xs:string*?) as xs:anyURI external

The function prepares a given query for execution.

query-plan ($query-key as xs:anyURI) as xs:base64Binary external

Returns the compiled query identified by the given query-key as binary data.

variable-value ($query-key as xs:anyURI, $var-name as xs:QName) as item()* external

This function returns the value of a variable that is bound in the given query.

Functions

bind-context-item#2

declare  %an:sequential function zq:bind-context-item($query-key as xs:anyURI, $dot as item()) as empty-sequence() external

This function binds the context-item of the prepared query identified by the given key to the $dot argument.

Parameters

query-key as xs:anyURI
the identifier for a compiled query
dot as item()
the context item to bind

Returns

empty-sequence()
the function has side effects and returns the empty sequence.

bind-variable#3

declare  %an:sequential function zq:bind-variable($query-key as xs:anyURI, $var as xs:QName, $value as item()*) as empty-sequence() external

This function binds the variable with name $name of the prepared query identified by $query-key to the given sequence.

Parameters

query-key as xs:anyURI
the identifier for a compiled query
var as xs:QName
value as item()
the sequence to which the external variable $name should be bound

Returns

empty-sequence()
the function has side effects and returns the empty sequence.

delete-query#1

declare  %an:sequential function zq:delete-query($query-key as xs:anyURI) as empty-sequence() external

Deletes the prepared query associated with the given identifier.

After the query is deleted, the corresponding identifier should not be used as argument to any of the functions of this module.

Parameters

query-key as xs:anyURI
the identifier for a compiled query

Returns

empty-sequence()
the function has side effects and returns the empty sequence.

evaluate-sequential#1

declare  %an:sequential function zq:evaluate-sequential($query-key as xs:string) as item()* external

Evaluates the given prepared query and returns the result of the evaluation. The query must be sequential.

Parameters

query-key as xs:string
the identifier for a compiled query

Returns

item()*
the result of evaluating the query.

evaluate-updating#1

declare  function zq:evaluate-updating($query-key as xs:anyURI) external

Evaluates the given prepared query and applies the updates computed by this query. The query must be an updating query.

Parameters

query-key as xs:anyURI
the identifier for a compiled query

Returns

the function has side effects because it applies the updates of the query. It returns the empty sequence.

evaluate#1

declare  function zq:evaluate($query-key as xs:anyURI) as item()* external

Evaluates the given prepared query and returns the result of the evaluation. The query must not be sequential or updating.

Parameters

query-key as xs:anyURI
the identifier for a compiled query

Returns

item()*
the result of evaluating the given query

external-variables#1

declare  function zq:external-variables($query-key as xs:anyURI) as xs:QName* external

The function returns the names of the external variables that are declared in the given query (either in the main module or in any of the imported library modules).

Parameters

query-key as xs:anyURI
the identifier for a compiled query

Returns

xs:QName*
the sequence of names of the said external variables.

is-bound-context-item#1

declare  function zq:is-bound-context-item($query-key as xs:anyURI) as xs:boolean external

The function tests if the context-item is bound for the execution of the query referred to by the given query identifier.

Parameters

query-key as xs:anyURI
the identifier for a compiled query

Returns

xs:boolean
true if the context-item is bound, false otherwise.

is-bound-variable#2

declare  function zq:is-bound-variable($query-key as xs:anyURI, $var-name as xs:QName) as xs:boolean external

The function tests if the given variable is bound for the execution of the query referred to by the given query identifier.

Parameters

query-key as xs:anyURI
the identifier for a compiled query
var-name as xs:QName
the name of the variable

Returns

xs:boolean
true if the variable is bound, false otherwise.

is-sequential#1

declare  function zq:is-sequential($query-key as xs:anyURI) as xs:boolean external

The function tests if the query identified by the given key is sequential query.

Parameters

query-key as xs:anyURI
the identifier for a compiled query

Returns

xs:boolean
true if the query is a sequential, false otherwise.

is-updating#1

declare  function zq:is-updating($query-key as xs:anyURI) as xs:boolean external

The function tests if the query identified by the given key is an updating query.

Parameters

query-key as xs:anyURI
the identifier for a compiled query

Returns

xs:boolean
true if the query is an updating query, false otherwise.

load-from-query-plan#1

declare  function zq:load-from-query-plan($plan as xs:base64Binary) as xs:anyURI external

The function loads a given query for execution from a xs:base64Binary query plan, obtained through the zq:query-plan function.

If the query was successfully loaded, the function returns an identifier as xs:anyURI. This URI can be passed to other functions of this module (e.g. to actually evaluate the query). The URI is opaque and its lifetime is bound by the lifetime of the query that invoked this function. Further reference or uses of the identifier lead to unexpected results.

Successfully prepared queries need to be deleted by passing the resulting identifier to the zq:delete-query function of this module.

Parameters

plan as xs:base64Binary
the binary query plan.

Returns

xs:anyURI
an identifier for the compiled query that can be passed as arguments to other functions of this module.

load-from-query-plan#3

declare  function zq:load-from-query-plan($plan as xs:base64Binary, $resolver as item()?, $mapper as item()?) as xs:anyURI external

The function loads a given query for execution from a xs:base64Binary query plan, obtained through the zq:query-plan function.

If the query was successfully loaded, the function returns an identifier as xs:anyURI. This URI can be passed to other functions of this module (e.g. to actually evaluate the query). The URI is opaque and its lilfetime is bound by the lifetime of the query that invoked this function. Further reference or uses of the identifier lead to unexpected results.

For important notes regarding the second and third parameters of the function, review the comments in zq:prepare-main-module#3.

Successfully prepared queries need to be deleted by passing the resulting identifier to the zq:delete-query function of this module.

Parameters

plan as xs:base64Binary
the binary query plan.
resolver as item()
the URL resolver function.
mapper as item()
the URI mapper function.

Returns

xs:anyURI
an identifier for the compiled query that can be passed as arguments to other functions of this module.

prepare-library-module#1

declare  %an:sequential function zq:prepare-library-module($library-module-text as xs:string) as empty-sequence() external

This function compiles a given XQuery or JSONiq library module. It can be used to compile-check a module.

Parameters

library-module-text as xs:string
the library module that should be prepared.

Returns

empty-sequence()
the empty-sequence.

prepare-main-module#1

declare  %an:sequential function zq:prepare-main-module($main-module-text as xs:string) as xs:anyURI external

The function prepares a given a query for execution.

If the query was successfully compiled, the function returns an identifier as xs:anyURI. This URI can be passed to other functions of this module (e.g. to actually evaluate the query). The URI is opaque and its lifetime is bound by the lifetime of the query that invoked this function. Further reference or uses of the identifier lead to unexpected results.

Successfully prepared queries need to be deleted by passing the resulting identifier to the zq:delete-query function of this module.

Parameters

main-module-text as xs:string
the query that should be prepared. The query needs to be a XQuery or JSONiq main module.

Returns

xs:anyURI
an identifier for the compiled query that can be passed as arguments to other functions of this module.

prepare-main-module#3

declare  %an:sequential function zq:prepare-main-module($main-module-text as xs:string, $resolver as function (xs:string, xs:string) as item()??, $mapper as function (xs:string, xs:string) as xs:string*?) as xs:anyURI external

The function prepares a given query for execution.

If the query was successfully compiled, the function returns an identifier as xs:anyURI. This URI can be passed to other functions of this module (e.g. to actually evaluate the query). The URI is opaque and its lifetime is bound by the lifetime of the query that invoked this function. Further reference or uses of the identifier lead to unexpected results.

Important notes regarding the second and third parameters of the function:

--------------------------------------------------------------------------

These parameters allow you to specify a URL resolver and a URI mapper for Zorba to use when executing this query. See here

    The second parameter is a function item for a URL resolver. The URL resolver function must recive 2 parameters:
  • A $namespace as xs:string that will contain the url to be resolved.
  • A $entity as xs:string that will contain the type of resolving needed. This can be one of two values: "module" or "schema".

The function must return the empty sequence when the specified $namespace or $entity are not the ones to be resolved.

Example:

declare function mymod:url-resolver($namespace as xs:string, $entity as xs:string) as item()?
 {
  if($namespace = 'http://test.xq')
  then "module namespace test = 'http://test'; declare function test:foo(){'foo'};"
  else ()
 };

The URL resolver function's namespace, name, and parameter naming are not restricted by ZQ.

The URL resolver function's return type is not restricted, it could be a string, a sequence, a node, etc. All the outputs types are to be serialized as a string.

The third parameter is a function item for a URI mapper.

    The URI mapper function, just like the URL resolver, receives 2 parameters:
  • A $namespace as xs:string that will contain the URI to be mapped.
  • A $entity as xs:string that will contain the type of resolving needed. This can be one of two values: "module" or "schema".

The URI mapper must return an empty sequence when the specified $namesapce or $entity are not to be mapped. Unlike the URL resolver this function must return a sequence of strings.

Example:

declare function mymod:uri-mapper($namespace as xs:string, $entity as xs:string)
 {
  if($namespace = 'http://test')
  then ("http://zorba.io/test", "http://foo.com/schema/test")
  else ()
 };

The URI mapper function's namespace, name, and parameter naming are not restricted by ZQ.

In order to pass the above URL resolver and URI mapper to this function, use the following syntax:

variable $queryID := zq:prepare-main-module("..query text..",
      mymod:url-resolver#2, mymod:uri-mapper#2);

That is, the QName of the function followed by "#2". This is XQuery "higher-order function" syntax, meaning the function with the specified QName which takes two arguments. Since URL resolvers and URI mappers must take two arguments, both will always be specified with "#2".

Both the URL resolver and URI mapper functions are optional, meaning you may pass the empty-sequence () for either.

Successfully prepared queries need to be deleted by passing the resulting identifier to the zq:delete-query function of this module.

Parameters

main-module-text as xs:string
the query that should be prepared. The query needs to be a XQuery or JSONiq main module.
resolver as function (xs:string, xs:string) as item()?
the URL resolver function.
mapper as function (xs:string, xs:string) as xs:string*
the URI mapper function.

Returns

xs:anyURI
an identifier for the compiled query that can be passed as arguments to other functions of this module.

query-plan#1

declare  function zq:query-plan($query-key as xs:anyURI) as xs:base64Binary external

Returns the compiled query identified by the given query-key as binary data.

Parameters

query-key as xs:anyURI
the identifier of a compiled query.

Returns

xs:base64Binary
the query as xs:base64Binary.

variable-value#2

declare  function zq:variable-value($query-key as xs:anyURI, $var-name as xs:QName) as item()* external

This function returns the value of a variable that is bound in the given query.

Parameters

query-key as xs:anyURI
the identifier of a compiled query.
var-name as xs:QName
the name of the variable whose value should be returned.

Returns

item()*
the value bound to the given variable.