http://zorba.io/modules/store/static/indexes/dml

View as XML or JSON.

This module defines a set of functions to probe and refresh indexes which are declared in the prolog of a module.

This module is part of Zorba's XQuery Data Definition Facility. All the indexes managed by this module have to be pre-declared in the prolog of a library module. Please refer to the general documentation for more information and examples.

Function Summary

keys ($name as xs:QName) as node()* external

Gets a sequence of all keys contained in the index with the given name.

probe-index-point-general ($name as xs:QName, $key as xs:anyAtomicType*) as node()* external

Gets from an index the domain nodes associated by general equality with a given search sequence .

probe-index-point-value-skip ($name as xs:QName, $skip as xs:integer, $key_i as xs:anyAtomicType?) as node()* external

This is an extension of the probe-index-point-value() function in that it allows index items to be skipped.

probe-index-point-value ($name as xs:QName, $key_i as xs:anyAtomicType?) as node()* external

Gets the domain nodes from an index associated by value equality with a given search tuple .

probe-index-range-general ($name as xs:QName, $lowerBound as xs:anyAtomicType*, $upperBound as xs:anyAtomicType*, $haveLowerBound as xs:boolean, $haveUpperBound as xs:boolean, $lowerBoundIncluded as xs:boolean, $upperBoundIncluded as xs:boolean) as node()* external

Gets the domain nodes associated by general order-comparison (operators <= , < , >= , > ) with one or two search sequences .

probe-index-range-value-skip ($name as xs:QName, $skip as xs:integer, $lowerBound-i as xs:anyAtomicType?, $upperBound-i as xs:anyAtomicType?, $haveLowerBound-i as xs:boolean, $haveUpperBound-i as xs:boolean, $lowerBoundIncluded-i as xs:boolean, $upperBoundIncluded-i as xs:boolean) as node()* external

This function is an extension of the probe-index-range-value() function that index items to be skipped.

probe-index-range-value ($name as xs:QName, $lowerBound-i as xs:anyAtomicType?, $upperBound-i as xs:anyAtomicType?, $haveLowerBound-i as xs:boolean, $haveUpperBound-i as xs:boolean, $lowerBoundIncluded-i as xs:boolean, $upperBoundIncluded-i as xs:boolean) as node()* external

Gets the domain nodes associated by value order-comparison (operators le , lt , ge , gt ) with a given search box .

refresh-index ($name as xs:QName) external

Updates the index with the given name.

Functions

keys#1

declare  function idml:keys($name as xs:QName) as node()* external
Gets a sequence of all keys contained in the index with the given name. Each element has the following structure:
   <key xmlns="http://zorba.io/modules/store/static/indexes/dml">
     <attribute value="key1_value"/>
     <attribute value="key2_value"/>
     <attribute value="key3_value"/>
   </key>
  
Note that the order of the attribute elements reflects the order of the keys in the index specification. Also note that the values in these attributes have the type that is declared in the corresponding index specification.

Parameters

name as xs:QName
The name of the index to get the keys for.

Returns

node()*
A sequence of elements comprising the keys in the index.

probe-index-point-general#2

declare  function idml:probe-index-point-general($name as xs:QName, $key as xs:anyAtomicType*) as node()* external
Gets from an index the domain nodes associated by general equality with a given search sequence . The search sequence consists of an arbitrary number of search keys where each search key is an atomic item. The function is supported by general indexes only.

Parameters

name as xs:QName
The name of the index to probe.
key as xs:anyAtomicType
The search sequence.

Returns

node()*
The set of domain nodes for which the following XQuery expression returns true:
 $keys = $node/keyExpr 
where keyExpr is the expression specified in the keyspec of the index (remember that for general indexes, there can be only one keyspec).

probe-index-point-value-skip#3

declare  %an:variadic function idml:probe-index-point-value-skip($name as xs:QName, $skip as xs:integer, $key_i as xs:anyAtomicType?) as node()* external
This is an extension of the probe-index-point-value() function in that it allows index items to be skipped.

Parameters

name as xs:QName
The name of the index to probe.
skip as xs:integer
The number of index items to skip.
key_i as xs:anyAtomicType
The search keys used to probe the index with. The i-th search key corresponds to the i-th key expression in the index declaration.

Returns

node()*
The set of domain nodes that satisfy the search condition.

probe-index-point-value#2

declare  %an:variadic function idml:probe-index-point-value($name as xs:QName, $key_i as xs:anyAtomicType?) as node()* external
Gets the domain nodes from an index associated by value equality with a given search tuple.

The search tuple consists of a number of search keys where each search key is either an atomic item or the empty sequence. The number of search keys given must be equal to the number of keys declared for the index. Since the number of keys differs from one index to another, this function is variadic.

Parameters

name as xs:QName
The of the index to probe.
key_i as xs:anyAtomicType
A search key used to probe the index with. The i-th search key corresponds to the i-th key expression in the index declaration.

Returns

node()*
The set of domain nodes for which the following XQuery expression returns true:
 $key1 eq $node/keyExpr1 and ... and $keyM eq $node/keyExprM 
where keyExpri is the expression specified in the i-th keyspec of the index.

probe-index-range-general#7

declare  function idml:probe-index-range-general($name as xs:QName, $lowerBound as xs:anyAtomicType*, $upperBound as xs:anyAtomicType*, $haveLowerBound as xs:boolean, $haveUpperBound as xs:boolean, $lowerBoundIncluded as xs:boolean, $upperBoundIncluded as xs:boolean) as node()* external
Gets the domain nodes associated by general order-comparison (operators <=, <, >=, >) with one or two search sequences.

Each search sequence consists of an arbitrary number of search keys where each search key is an atomic item. This method is supported by general range indexes only. Its result is either an error or the set of domain nodes for which the following XQuery expression returns true:

    if ( $haveLowerBound and $haveUpperBound ) then
      $lowerBoundKeys lop $node/keyExpr and $node/keyExpr uop $upperBoundKeys
    else if ( $haveLowerBound ) then
      $lowerBoundKeys lop $node/keyExpr
    else if ( $haveUpperBound ) then
      $node/keyExpr uop $upperBoundKeys
    else
      fn:true()
  
where keyExpr is the expression specified in the keyspec of the index, lop is either the <= or the < operator depending on whether $lowerBoundsIncluded is true or false, and uop is either the <= or the < operator depending on whether $upperBoundsIncluded is true or false.

Parameters

name as xs:QName
The of the index to probe.
lowerBound as xs:anyAtomicType
The lower bound search sequence.
upperBound as xs:anyAtomicType
The upper bound search sequence.
haveLowerBound as xs:boolean
Whether a lower bound search sequence exists or not.
haveUpperBound as xs:boolean
Whether an upper bound search sequence exists or not.
lowerBoundIncluded as xs:boolean
Whether to use the <= or the < operator when comparing a search key from $lowerBound with an index key.
upperBoundIncluded as xs:boolean
Whether to use the <= or the < operator when comparing an index key with a search key from $upperBound.

Returns

node()*
The set of domain nodes that satisfy the search condition.

probe-index-range-value-skip#8

declare  %an:variadic function idml:probe-index-range-value-skip($name as xs:QName, $skip as xs:integer, $lowerBound-i as xs:anyAtomicType?, $upperBound-i as xs:anyAtomicType?, $haveLowerBound-i as xs:boolean, $haveUpperBound-i as xs:boolean, $lowerBoundIncluded-i as xs:boolean, $upperBoundIncluded-i as xs:boolean) as node()* external
This function is an extension of the probe-index-range-value() function that index items to be skipped.

Parameters

name as xs:QName
The QName of the index to probe
skip as xs:integer
The number of index items to skip.
lowerBound-i as xs:anyAtomicType
The lower bound in a range of key values.
upperBound-i as xs:anyAtomicType
The upper bound in a range of key values.
haveLowerBound-i as xs:boolean
If false, then there is no lower bound, or equivalently, the lower bound is -INFINITY. Otherwise, the lower bound is the one given by the $lowerBound-i value.
haveUpperBound-i as xs:boolean
If false, then there is no upper bound, or equivalently, the upper bound is +INFINITY. Otherwise, the upper bound is the one given by the $upperBound-i value.
lowerBoundIncluded-i as xs:boolean
If false, then the range is open from below, i.e., the lowerBound-i value is not considered part of the range. Otherwise, the range is closed from below, i.e., the $lowerBound-i value is part of the range.
upperBoundIncluded-i as xs:boolean
If false, then the range is open from above, i.e., the upperBound-i value is not considered part of the range. Otherwise, the range is closed from above, i.e., the $upperBound-i value is part of the range.

Returns

node()*
The set of domain nodes that satisfy the search condition.

probe-index-range-value#7

declare  %an:variadic function idml:probe-index-range-value($name as xs:QName, $lowerBound-i as xs:anyAtomicType?, $upperBound-i as xs:anyAtomicType?, $haveLowerBound-i as xs:boolean, $haveUpperBound-i as xs:boolean, $lowerBoundIncluded-i as xs:boolean, $upperBoundIncluded-i as xs:boolean) as node()* external
Gets the domain nodes associated by value order-comparison (operators le, lt, ge, gt) with a given search box.

The search box is specified as a number M of rangespecs where each rangespec consists of six values. The number M must be greater than 0 and less than or equal to the number N of keyspecs found in the index declaration. If M < N, then the "missing" rangespecs are assumed to have the following value: [(), (), false, false, false, false]. As a result, we can assume that M = N. Remember that for general indexes, there can be only one IndexKeySpec and, as a result for general indexes, M = N = 1. Since the number of keys differs from one index to another, this function is variadic.

The ith rangespec corresponds to the ith keyspec, and specifies a search condition on the key values that are produced by evaluating that keyspec for every domain node. Specifically, we define the ith rangespec result as the set of domain nodes for which the following XQuery expression returns true:

    if ( $haveLowerBound-i and $haveUpperBound-i ) then
      $lowerBound-i lop $node/keyExpr-i and $node/keyExpr-i uop $upperBound-i
    else if ( $haveLowerBound-i ) then
      $lowerBound-i lop $node/keyExpr-i
    else if ( $haveUpperBound-i ) then
      $node/keyExpr-i uop $upperBound-i
    else
      fn:true()
  
where keyExpr-i is the expression specified by the ith keyspec of the index, lop is either the le or the lt operator depending on whether $lowerBoundsIncluded-i is true or false, and uop is either the le or the lt operator depending on whether $upperBoundsIncluded-i is true or false.

Parameters

name as xs:QName
The name of the index to probe.
lowerBound-i as xs:anyAtomicType
The lower bound in a range of key values.
upperBound-i as xs:anyAtomicType
The upper bound in a range of key values.
haveLowerBound-i as xs:boolean
If false, then there is no lower bound, or equivalently, the lower bound is -INFINITY. Otherwise, the lower bound is the one given by the $lowerBound-i value.
haveUpperBound-i as xs:boolean
If false, then there is no upper bound, or equivalently, the upper bound is +INFINITY. Otherwise, the upper bound is the one given by the $upperBound-i value.
lowerBoundIncluded-i as xs:boolean
If false, then the range is open from below, i.e., the $lowerBound-i value is not considered part of the range. Otherwise, the range is closed from below, i.e., the $lowerBound-i value is part of the range.
upperBoundIncluded-i as xs:boolean
If false, then the range is open from above, i.e., the $upperBound-i value is not considered part of the range. Otherwise, the range is closed from above, i.e., the $upperBound-i value is part of the range.

Returns

node()*
The intersection of all the rangespec results.

refresh-index#1

declare  function idml:refresh-index($name as xs:QName) external
Updates the index with the given name. Note that if the maintenance property of the index is automatic, this function does nothing.

Parameters

name as xs:QName
The name of the index to refresh.

Returns

An empty XDM instance and a pending update list that, when applied, refreshes the contents of the index.