Loading TOC...

cts.elementAttributeRangeQuery

cts.elementAttributeRangeQuery(
   element-name as xs.QName[],
   attribute-name as xs.QName[],
   operator as String,
   value as (String | Number | Boolean | null | Array | Object)[],
   [options as String[]],
   [weight as Number?]
) as cts.elementAttributeRangeQuery

Summary

Constructs a query that matches element-attributes by name with a range-index entry equal to a given value. An element attribute range index on the specified QName(s) must exist when you use this query in a search; if no such range index exists, the search throws an exception.

Parameters
element-name One or more element QNames to match. When multiple QNames are specified, the query matches if any QName matches.
attribute-name One or more attribute QNames to match. When multiple QNames are specified, the query matches if any QName matches.
operator A comparison operator.

Operators include:

"<"
Match range index values less than $value.
"<="
Match range index values less than or equal to $value.
">"
Match range index values greater than $value.
">="
Match range index values greater than or equal to $value.
"="
Match range index values equal to $value.
"!="
Match range index values not equal to $value.
value Some values to match. When multiple values are specified, the query matches if any value matches.
options Options to this query. The default is ().

Options include:

"collation=URI"
Use the range index with the collation specified by URI. If not specified, then the default collation from the query is used. If a range index with the specified collation does not exist, an error is thrown.
"cached"
Cache the results of this query in the list cache.
"uncached"
Do not cache the results of this query in the list cache.
"cached-incremental"
When querying on a short date or dateTime range, break the query into sub-queries on smaller ranges, and then cache the results of each. See the Usage Notes for details.
"min-occurs=number"
Specifies the minimum number of occurrences required. If fewer that this number of words occur, the fragment does not match. The default is 1.
"max-occurs=number"
Specifies the maximum number of occurrences required. If more than this number of words occur, the fragment does not match. The default is unbounded.
"score-function=function"
Use the selected scoring function. The score function may be:
linear
Use a linear function of the difference between the specified query value and the matching value in the index to calculate a score for this range query.
reciprocal
Use a reciprocal function of the difference between the specified query value and the matching value in the index to calculate a score for this range query.
zero
This range query does not contribute to the score. This is the default.
"slope-factor=number"
Apply the given number as a scaling factor to the slope of the scoring function. The default is 1.0.
"synonym"
Specifies that all of the terms in the $value parameter are considered synonyms for scoring purposes. The result is that occurrences of more than one of the synonyms are scored as if there are more occurrences of the same term (as opposed to having a separate term that contributes to score).
weight A weight for this query. The default is 1.0.

Usage Notes

To constrain on a range of values, combine multiple element attribute range queries together using cts.andQuery or another composable query constructor.

If neither "cached" nor "uncached" is present, it specifies "cached".

The "cached-incremental" option can improve performance if you repeatedly perform range queries on date or dateTime values over a short range that does not vary widely over short period of time. To benefit, the operator should remain the same "direction" (<,<=, or >,>=) across calls, the bounding date or dateTime changes slightly across calls, and the query runs very frequently (multiple times per minute). Note that using this options creates significantly more cached queries than the "cached" option.

The "cached-incremental" option has the following restrictions and interactions: The "min-occurs" and "max-occurs" options will be ignored if you use "cached-incremental" in unfiltered search. You can only use "score-function=zero" with "cached-incremental". The "cached-incremental" option behaves like "cached" if you are not querying date or dateTime values.

Negative "min-occurs" or "max-occurs" values will be treated as 0 and non-integral values will be rounded down. An error will be raised if the "min-occurs" value is greater than the "max-occurs" value.

"score-function=linear" means that values that are further away from the bounds will score higher. "score-function=reciprocal" means that values that are closer to the bounds will score higher. The functions are scaled appropriately for different types, so that in general the default slope factor will provide useful results. Using a slope factor greater than 1 gives distinct scores over a smaller range of values, and produces generally higher scores. Using a slope factor less than 1 gives distinct scores over a wider range of values, and produces generally lower scores.

For queries against a dateTime index, when $value is an xs:dayTimeDuration or xs:yearMonthDuration, the query is executed as an age query. $value is subtracted from fn:current-dateTime() to create an xs:dateTime used in the query. If there is more than one item in $value, they must all be the same type.

Example

// Insert some test data of the following form:
//  <entry sku="N"/>
declareUpdate();
xdmp.documentInsert('/attribute1.xml',
  (new NodeBuilder())
    .startElement('entry')
      .addAttribute('sku','100')
    .endElement()
    .toNode()) ;
xdmp.documentInsert('/attribute2.xml',
  (new NodeBuilder())
    .startElement('entry')
      .addAttribute('sku','200')
    .endElement()
    .toNode()) ;
xdmp.documentInsert('/attribute3.xml',
  (new NodeBuilder())
    .startElement('entry')
      .addAttribute('sku','1000')
    .endElement()
    .toNode()) ;

// *************************************************
// In a separate query, search the test data. This search
// requires an attribute (range) index of type xs:int on the
// "sku" attribute of the "entry" element

cts.search(
  cts.elementAttributeRangeQuery(
      xs.QName("entry"), xs.QName("sku"), ">=",
      500));

// Returns the following document (with URI "/attribute3.xml"):
// <?xml version="1.0" encoding="UTF-8"?>
// <entry sku="1000"></entry>

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.