<?xml version="1.0" encoding="UTF-8"?><api:function-page xml:base="/apidoc/8.0/cts.valueRanges.xml" generated="2015-10-07T16:36:00.016766-07:00" mode="javascript" xmlns:api="http://marklogic.com/rundmc/api"><api:function-name>cts.valueRanges</api:function-name><api:suggest>cts.valueranges</api:suggest><api:suggest>cts</api:suggest><api:suggest>valueranges</api:suggest><api:function-link mode="xquery" fullname="cts:value-ranges">/apidoc/8.0/cts:value-ranges.xml</api:function-link><api:function mode="javascript" name="valueRanges" type="builtin" lib="cts" category="SearchBuiltins" subcategory="Lexicon" hidden="false" bucket="MarkLogic Built-In Functions" prefix="cts" namespace="http://marklogic.com/cts" fullname="cts.valueRanges"><api:summary>
  <p xmlns="http://www.w3.org/1999/xhtml">Returns value ranges from the specified path value lexicon(s).
  Value lexicons are implemented using range indexes; consequently this
  function requires a path range index for each element specified
  in the function.  If there is not a range index configured for each
  of the specified paths, an exception is thrown.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">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.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">If you have string values and you pass a $bounds parameter
   as in the following call:</p>
  
  <pre class="javascript" xmlns="http://www.w3.org/1999/xhtml">cts.valueRanges(cts.pathReference("/name/fname"), ["f", "m"])</pre>
  <p xmlns="http://www.w3.org/1999/xhtml">The first bucket contains string values that are less than the
  string <code>f</code>, the second bucket contains string values greater than
  or equal to <code>f</code> but less than <code>m</code>, and the third bucket
  contains string values that are greater than or equal to <code>m</code>.</p>
  
  <p class="javascript" xmlns="http://www.w3.org/1999/xhtml">For each non-empty bucket, an ObjectNode is returned.
  Each ObjectNode has a <code>minimum</code> property and a <code>maximum</code>
  property.  If a bucket is bounded, its ObjectNode will also have a
  <code>lowerBound</code> property if it is bounded from below, and
  a <code>upperBound</code> property if it is bounded from above.
  Empty buckets return nothing unless the "empties" option is specified.</p>
</api:summary><api:params><api:param name="range-indexes" type="cts:reference*"><api:param-description>
    A sequence of references to range indexes.
  </api:param-description><api:param-name>range-indexes</api:param-name><api:param-type>cts.reference[]</api:param-type></api:param><api:param name="bounds" type="xs:anyAtomicType*" optional="true"><api:param-description>
    A sequence of range bounds.
    The types must match the lexicon type.
    The values must be in strictly ascending order, otherwise an exception
    is thrown.
  </api:param-description><api:param-name>bounds</api:param-name><api:param-type>(String | Number | Boolean | null)[]</api:param-type></api:param><api:param name="options" type="xs:string*" optional="true"><api:param-description>
    Options.  The default is ().
    <p xmlns="http://www.w3.org/1999/xhtml">
      Options include:</p>
      <blockquote xmlns="http://www.w3.org/1999/xhtml"><dl>
        <dt>"ascending"</dt>
        <dd>Ranges should be returned in ascending order.</dd>
        <dt>"descending"</dt>
        <dd>Ranges should be returned in descending order.</dd>
        <dt>"empties"</dt>
        <dd>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).</dd>
        <dt>"any"</dt>
        <dd>Values from any fragment should be included.</dd>
        <dt>"document"</dt>
        <dd>Values from document fragments should be included.</dd>
        <dt>"properties"</dt>
        <dd>Values from properties fragments should be included.</dd>
        <dt>"locks"</dt>
        <dd>Values from locks fragments should be included.</dd>
        <dt>"frequency-order"</dt>
        <dd>Ranges should be returned ordered by frequency.</dd>
        <dt>"item-order"</dt>
        <dd>Ranges should be returned ordered by item.</dd>
        <dt>"fragment-frequency"</dt>
        <dd>Frequency should be the number of fragments with
        an included value.
        This option is used with <code>cts:frequency</code>.</dd>
        <dt>"item-frequency"</dt>
        <dd>Frequency should be the number of occurences of
        an included value.
        This option is used with <code>cts:frequency</code>.</dd>
        <dt>"timezone=<em>TZ</em>"</dt>
        <dd>Return timezone sensitive values (dateTime, time, date,
        gYearMonth, gYear, gMonth, and gDay) adjusted to the timezone
        specified by <em>TZ</em>.
        Example timezones: Z, -08:00, +01:00.</dd>
        <dt>"limit=<em>N</em>"</dt>
        <dd>Return no more than <em>N</em> ranges.</dd>
        <dt>"skip=<em>N</em>"</dt>
        <dd>Skip over fragments selected by the <code>cts:query</code>
        to treat the <em>Nth</em> fragment as the first fragment.
        Values from skipped fragments are not included.
        This option affects the number of fragments selected
        by the <code>cts:query</code> to calculate frequencies.
        Only applies when a <code>$query</code> parameter is specified.</dd>
        <dt>"sample=<em>N</em>"</dt>
        <dd>Return only ranges for buckets with at least one value from
        the first <em>N</em> fragments after skip selected by the
        <code>cts:query</code>.
        This option does not affect the number of fragments selected
        by the <code>cts:query</code> to calculate frequencies.
        Only applies when a <code>$query</code> parameter is specified.</dd>
        <dt>"truncate=<em>N</em>"</dt>
        <dd>Include only values from the first <em>N</em> fragments
        after skip selected by the <code>cts:query</code>.
        This option also affects the number of fragments selected
        by the <code>cts:query</code> to calculate frequencies.
        Only applies when a <code>$query</code> parameter is specified.</dd>
        <dt>"score-logtfidf"</dt>
        <dd>Compute scores using the logtfidf method.</dd>
        <dt>"score-logtf"</dt>
        <dd>Compute scores using the logtf method.</dd>
        <dt>"score-simple"</dt>
        <dd>Compute scores using the simple method.</dd>
        <dt>"score-random"</dt>
        <dd>Compute scores using the random method.</dd>
        <dt>"score-zero"</dt>
        <dd>Compute all scores as zero.</dd>
        <dt>"checked"</dt>
        <dd>Word positions should be checked when resolving the query.</dd>
        <dt>"unchecked"</dt>
        <dd>Word positions should not be checked when resolving the query.</dd>
        <dt>"too-many-positions-error"</dt>
        <dd>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.</dd>
        <dt>"eager"</dt>
        <dd>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.</dd>
        <dt>"lazy"</dt>
        <dd>Perform only some the work concurrently before returning 
        the first item from the indexes, and most of the work
        sequentially while iterating through the rest of the items.
        This usually takes the shortest time for a small item-order 
        partial result.</dd>
        <dt>"concurrent"</dt>
        <dd>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).</dd>
     </dl></blockquote>
  </api:param-description><api:param-name>options</api:param-name><api:param-type>String[]</api:param-type></api:param><api:param name="query" type="cts:query?" optional="true"><api:param-description>
    Only include values in fragments selected by the <code xmlns="http://www.w3.org/1999/xhtml">cts:query</code>,
    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 <a href="#unfiltered" xmlns="http://www.w3.org/1999/xhtml">
    "unfiltered" <code>cts:search</code></a> operations.  If a string
   is entered, the string is treated as a <code xmlns="http://www.w3.org/1999/xhtml">cts:word-query</code> of the
   specified string.
  </api:param-description><api:param-name>query</api:param-name><api:param-type>cts.query?</api:param-type></api:param><api:param name="quality-weight" type="xs:double?" optional="true"><api:param-description>
    A document quality weight to use when computing scores.
    The default is 1.0.
  </api:param-description><api:param-name>quality-weight</api:param-name><api:param-type>Number?</api:param-type></api:param><api:param name="forest-ids" type="xs:unsignedLong*" optional="true"><api:param-description>
    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 ().
  </api:param-description><api:param-name>forest-ids</api:param-name><api:param-type>String[]</api:param-type></api:param></api:params><api:return>ValueIterator</api:return><api:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">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".</p>
  <p xmlns="http://www.w3.org/1999/xhtml">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".</p>
  <p xmlns="http://www.w3.org/1999/xhtml">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.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">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".</p>
  <p xmlns="http://www.w3.org/1999/xhtml">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".</p>
  <p xmlns="http://www.w3.org/1999/xhtml">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".</p>
  <p xmlns="http://www.w3.org/1999/xhtml">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".</p>
  <p xmlns="http://www.w3.org/1999/xhtml">If "collation=<em>URI</em>" is not specified in the options parameter,
  then the default collation is used. If a lexicon with that collation
  does not exist, an error is thrown.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">If "sample=<em>N</em>" is not specfied in the options parameter,
  then ranges with all included values may be returned. If a
  <code>$query</code> parameter is not present, then "sample=<em>N</em>"
  has no effect.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">If "truncate=<em>N</em>" is not specfied in the options parameter,
  then values from all fragments selected by the <code>$query</code> parameter
  are included.  If a <code>$query</code> parameter is not present, then
  "truncate=<em>N</em>" has no effect.</p>
</api:usage><api:example class="javascript"><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
//  Run the following to load data for this example.
//  Make sure you have a string path range index on path: 
//     /name/fname 

declareUpdate();
xdmp.documentInsert("/aname1.json",
 {name:{fname:"John", mname:"Rob", lname:"Goldings"}});  
xdmp.documentInsert("/aname2.json",
 {name:{fname:"Jim", mname:"Ken", lname:"Kurla"}});
xdmp.documentInsert("/aname3.json",
 {name:{fname:"Ooi", mname:"Ben", lname:"Fu"}});
xdmp.documentInsert("/aname4.json",
 {name:{fname:"James", mname:"Rick", lname:"Tod"}});
xdmp.documentInsert("/aname5.json",
 {name:{fname:"Anthony", mname:"Rob", lname:"Flemings"}});
xdmp.documentInsert("/aname6.json",
 {name:{fname:"Charles", mname:"Ken", lname:"Winter"}});
xdmp.documentInsert("/aname7.json",
 {name:{fname:"Nancy", mname:"Ben", lname:"Schmidt"}});
xdmp.documentInsert("/aname8.json",
 {name:{fname:"Robert", mname:"Rick", lname:"Hanson"}});

*******
// The following is based on the above setup 

cts.valueRanges(cts.pathReference("/name/fname"),["A","J","O"]);
=&gt;
{"minimum":"Anthony", "maximum":"Charles", "lowerBound":"A", "upperBound":"J"}
{"minimum":"James", "maximum":"Nancy", "lowerBound":"J", "upperBound":"O"}
{"minimum":"Ooi", "maximum":"Robert", "lowerBound":"O"}

</pre></api:example></api:function></api:function-page>