MarkLogic 12 EA 2 Product Documentation

cts:field-range-query

cts:field-range-query(
   $field-name as xs:string*,
   $operator as xs:string,
   $value as xs:anyAtomicType*,
   [$options as xs:string*],
   [$weight as xs:double?]
) as cts:field-range-query

Summary

Returns a cts:query matching fields by name with a range-index entry equal to a given value. Searches with the cts:field-range-query constructor require a field range index on the specified field name(s); if there is no range index configured, then an exception is thrown.

Usage Notes

If you want to constrain on a range of values, you can combine multiple cts:field-range-query constructors together with cts:and-query or any of the other composable cts:query constructors.

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

(: Requires a field that includes name and excludes mname :)
(: Insert few documents with test data :)
let $content1 :=
 <name><fname>John</fname><mname>Rob</mname><lname>Goldings</lname></name>
let $content2 :=
 <name><fname>Jim</fname><mname>Ken</mname><lname>Kurla</lname></name>
let $content3 :=
 <name><fname>Ooi</fname><mname>Ben</mname><lname>Fu</lname></name>
let $content4 :=
 <name><fname>James</fname><mname>Rick</mname><lname>Tod</lname></name>
return (
xdmp:document-insert("/aname1.xml",$content1),
xdmp:document-insert("/aname2.xml",$content2),
xdmp:document-insert("/aname3.xml",$content3),
xdmp:document-insert("/aname4.xml",$content4));

(:
   requires a field (range) index of
   type xs:string on field "aname"
:)

cts:search(doc(),cts:field-range-query("aname",">","Jim Kurla"));

(:
  returns the following:
<?xml version="1.0" encoding="UTF-8"?>
<name>
  <fname>John</fname>
  <mname>Rob</mname>
  <lname>Goldings</lname>
</name>
<?xml version="1.0" encoding="UTF-8"?>
<name>
  <fname>Ooi</fname>
  <mname>Ben</mname>
  <lname>Fu</lname>
</name>
:)

(:
   requires a field (range) index of
   type xs:string on "aname"
:)
cts:contains(doc(),cts:field-range-query("aname",">","Jim Kurla"))
(:
  returns "true".
:)