Loading TOC...

cts.elementAttributeValueRanges

cts.elementAttributeValueRanges(
   $element-names as xs.QName[],
   $attribute-names as xs.QName[],
   [$bounds as (String | Number | Boolean | null | Array | Object)[]],
   [$options as String[]],
   [$query as cts.query?],
   [$quality-weight as Number?],
   [$forest-ids as String[]]
) as ValueIterator

Summary

Returns value ranges from the specified element-attribute value lexicon(s). Element-attribute value lexicons are implemented using indexes; consequently this function requires an attribute range index of for each of the element/attribute pairs specified in the function. If there is not a range index configured for each of the specified element/attribute pairs, then an exception is thrown.

The values are divided into buckets. The $bounds parameter specifies the number of buckets and the size of each bucket. All included values are bucketed, even those less than the lowest bound or greater than the highest bound. An empty sequence for $bounds specifies one bucket, a single value specifies two buckets, two values specify three buckets, and so on.

If you have string values and you pass a $bounds parameter as in the following call:

cts.elementValueRanges(xs.QName("myElement"), ["f", "m"])

The first bucket contains string values that are less than the string f, the second bucket contains string values greater than or equal to f but less than m, and the third bucket contains string values that are greater than or equal to m.

For each non-empty bucket, an ObjectNode is returned. Each ObjectNode has a minimum property and a maximum property. If a bucket is bounded, its ObjectNode will also have a lowerBound property if it is bounded from below, and a upperBound property if it is bounded from above. Empty buckets return nothing unless the "empties" option is specified.

Parameters
$element-names One or more element QNames.
$attribute-names One or more attribute QNames.
$bounds A sequence of range bounds. The types must match the lexicon type. The values must be in strictly ascending order.
$options Options. The default is ().

Options include:

"ascending"
Ranges should be returned in ascending order.
"descending"
Ranges should be returned in descending order.
"empties"
Include fully-bounded ranges whose frequency is 0. These ranges will have no minimum or maximum value. Only empty ranges that have both their upper and lower bounds specified in the $bounds options are returned; any empty ranges that are less than the first bound or greater than the last bound are not returned. For example, if you specify 4 bounds and there are no results for any of the bounds, 3 elements are returned (not 5 elements).
"any"
Values from any fragment should be included.
"document"
Values from document fragments should be included.
"properties"
Values from properties fragments should be included.
"locks"
Values from locks fragments should be included.
"frequency-order"
Ranges should be returned ordered by frequency.
"item-order"
Ranges should be returned ordered by item.
"fragment-frequency"
Frequency should be the number of fragments with an included value. This option is used with cts:frequency.
"item-frequency"
Frequency should be the number of occurences of an included value. This option is used with cts:frequency.
"type=type"
Use the lexicon with the type specified by type (int, unsignedInt, long, unsignedLong, float, double, decimal, dateTime, time, date, gYearMonth, gYear, gMonth, gDay, yearMonthDuration, dayTimeDuration, string, or anyURI)
"collation=URI"
Use the range index with the collation specified by URI.
"timezone=TZ"
Return timezone sensitive values (dateTime, time, date, gYearMonth, gYear, gMonth, and gDay) adjusted to the timezone specified by TZ. Example timezones: Z, -08:00, +01:00.
"limit=N"
Return no more than N ranges.
"skip=N"
Skip over fragments selected by the cts:query to treat the Nth fragment as the first fragment. Values from skipped fragments are not included. This option affects the number of fragments selected by the cts:query to calculate frequencies. Only applies when a $query parameter is specified.
"sample=N"
Return only ranges for buckets with at least one value from the first N fragments after skip selected by the cts:query. This option does not affect the number of fragments selected by the cts:query to calculate frequencies. Only applies when a $query parameter is specified.
"truncate=N"
Include only values from the first N fragments after skip selected by the cts:query. This option also affects the number of fragments selected by the cts:query to calculate frequencies. Only applies when a $query parameter is specified.
"score-logtfidf"
Compute scores using the logtfidf method. Only applies when a $query parameter is specified.
"score-logtf"
Compute scores using the logtf method. Only applies when a $query parameter is specified.
"score-simple"
Compute scores using the simple method. Only applies when a $query parameter is specified.
"score-random"
Compute scores using the random method. Only applies when a $query parameter is specified.
"score-zero"
Compute all scores as zero. Only applies when a $query parameter is specified.
"checked"
Word positions should be checked when resolving the query.
"unchecked"
Word positions should not be checked when resolving the query.
"too-many-positions-error"
If too much memory is needed to perform positions calculations to check whether a document matches a query, return an XDMP-TOOMANYPOSITIONS error, instead of accepting the document as a match.
"eager"
Perform most of the work concurrently before returning the first item from the indexes, and only some of the work sequentially while iterating through the rest of the items. This usually takes the shortest time for a complete item-order result or for any frequency-order result.
"lazy"
Perform only some the work concurrently before returning the first item from the indexes, and most of the work sequentiallya while iterating through the rest of the items. This usually takes the shortest time for a small item-order partial result.
"concurrent"
Perform the work concurrently in another thread. This is a hint to the query optimizer to help parallelize the lexicon work, allowing the calling query to continue performing other work while the lexicon processing occurs. This is especially useful in cases where multiple lexicon calls occur in the same query (for example, resolving many facets in a single query).
$query Only include values in fragments selected by the cts:query, and compute frequencies from this set of included values. The values do not need to match the query, but they must occur in fragments selected by the query. The fragments are not filtered to ensure they match the query, but instead selected in the same manner as "unfiltered" cts.search operations. If a string is entered, the string is treated as a cts:word-query of the specified string.
$quality-weight A document quality weight to use when computing scores. The default is 1.0.
$forest-ids A sequence of IDs of forests to which the search will be constrained. An empty sequence means to search all forests in the database. The default is ().

Usage Notes

Only one of "frequency-order" or "item-order" may be specified in the options parameter. If neither "frequency-order" nor "item-order" is specified, then the default is "item-order".

Only one of "fragment-frequency" or "item-frequency" may be specified in the options parameter. If neither "fragment-frequency" nor "item-frequency" is specified, then the default is "fragment-frequency".

Only one of "ascending" or "descending" may be specified in the options parameter. If neither "ascending" nor "descending" is specified, then the default is "ascending" if "item-order" is specified, and "descending" if "frequency-order" is specified.

Only one of "eager" or "lazy" may be specified in the options parameter. If neither "eager" nor "lazy" is specified, then the default is "eager" if "frequency-order" or "empties" is specified, otherwise "lazy".

Only one of "any", "document", "properties", or "locks" may be specified in the options parameter. If none of "any", "document", "properties", or "locks" are specified and there is a $query parameter, then the default is "document". If there is no $query parameter then the default is "any".

Only one of the "score-logtfidf", "score-logtf", "score-simple", "score-random", or "score-zero" options may be specified in the options parameter. If none of "score-logtfidf", "score-logtf", "score-simple", "score-random", or "score-zero" are specified, then the default is "score-logtfidf".

Only one of the "checked" or "unchecked" options may be specified in the options parameter. If neither "checked" nor "unchecked" are specified, then the default is "checked".

If "collation=URI" is not specified in the options parameter, then the default collation is used. If a range index with that collation does not exist, an error is thrown.

If "sample=N" is not specfied in the options parameter, then ranges with all included values may be returned. If a $query parameter is not present, then "sample=N" has no effect.

If "truncate=N" is not specfied in the options parameter, then values from all fragments selected by the $query parameter are included. If a $query parameter is not present, then "truncate=N" has no effect.

When multiple element and/or attribute QNames are specified, then all possible element/attribute QName combinations are used to select the matching values.

Example

// Run the following to load data for this example.
// Make sure you have an int element attribute
// range index on my-node/@number. 

declareUpdate();
for (x=1;x<10;x++) {
xdmp.documentInsert("/doc" + x + ".xml",
 xdmp.unquote('<root><my-node number="' + x + '"/></root>').next().value) ;
};

******
// The following is based on the above setup 
cts.elementAttributeValueRanges(xs.QName("my-node"),
  xs.QName("number"), [5, 10, 15, 20], "empties");
=>
{"minimum":1, "maximum":4, "upperBound":5}
{"minimum":5, "maximum":9, "lowerBound":5, "upperBound":10}
{"lowerBound":10, "upperBound":15}
{"lowerBound":15, "upperBound":20}
{"lowerBound":20}

// you can also call cts.frequency on each item in the result
  

Comments

    Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy