Search Developer's Guide — Chapter 8

Value Constraint Example

The following query options define two value constraints: one for an element and one for an attribute.

<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-value">
    <value>
      <element ns="my-namespace" name="my-localname"/>
    </value>
  </constraint> 
  <constraint name="my-attribute-value">
    <value>
      <attribute ns="" name="my-attribute"/>
      <element ns="my-namespace" name="my-localname"/>
    </value>
  </constraint>
</options>

Using these constraints, you can use string queries such as the following to use these constraints:

my-value:"This is an element value."
my-attribute-value:123456

Both parts of the above queries would match the following document:

<my-document xmlns="my-namespace">
  <my-localname>This is an element value.</my-localname>
  <my-localname my-attribute="123456"/>
</my-document>

For more details, see value in the options reference.

Word Constraint Examples

The following query options define two word constraints: One for the <name/> element in the namespace http://authors-r-us.com and one for the field my-field. one for a cts:element-word-query and one for a cts:field-word-query:

<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="name">
    <word>
      <element ns="http://authors-r-us.com" name="name"/>
    </word>
  </constraint>
  <constraint name="description">
    <word>
        <field name="my-field"/>
    </word>
  </constraint>
</options>

You can create string and structured queries that use these constraints. For example, the following string query uses the name constraint.

name:raymond

When parsed, it becomes a cts:element-word-query:

<cts:element-word-query>
  <cts:element xmlns:_1="http://authors-r-us.com">
    _1:name
  </cts:element>
  <cts:text>raymond</cts:text>
</cts:element-word-query>

This query matches the following document (because a cts:word-query("raymond") would match):

<my-document xmlns="http://authors-r-us.com">
  <name>Raymond Carver</name>
</my-document>

Similarly, the following string query using the description constraint parses into a cts:field-word-query:

description:author

This query matches the above document if the name element is included in the definition of the field named my-field. For details on fields, see Fields Database Settings in the Administrator's Guide.

For more details, see word in the query options reference.

Word constraints can also be used in structured queries. For example, the following structured query is equivalent to the name:raymond string query:

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:word-constraint-query>
    <search:constraint-name>name</search:constraint-name>
    <search:text>raymond</search:text>
  </search:word-constraint-query>
</search:query>

For details, see Searching Using Structured Queries.

Collection Constraint Example

The following query options define a collection constraint, which allows you to constrain your search to documents that are in a specified collection.

You must enable the collection lexicon in the database to use collection constraints. If the collection lexicon is not enabled, an exception is thrown when you use a query with a collection constraint.

If you include a prefix attribute in the definition of a collection constraint, then the collection name is derived from the prefix concatenated with the constraint value.

One use for a collection constraint is to allow faceted navigation based on collections. For example, if you have collections based on subjects (for example, one called history, one called math, and so on), then you can use a collection constraint to narrow the search to one of the subjects.

<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="subject">
    <collection prefix="/my-collections/"/>
  </constraint>
</options>

Assuming that all documents in your database have collection URIs that begin with the string /my-collections/ like the following:

/my-collections/math
/my-collections/economics
/my-collections/zoology

Then the following query text examples will match documents in the corresponding collections:

subject:math
subject:economics
subject:zoology

If the database contains no documents in the specified collection, then the search returns no matches. For information on collections, see Collections.

You can also use collection constraints in a structured query, using collection-constraint-query. For details, see Searching Using Structured Queries.

Bucketed Range Constraint Example

Range constraints operate on typed element, element attribute, JSON property, field, or path values that have a corresponding range index in the database. Without the correct range index, queries using range constraints throw a runtime exception.

Range constraints can match on either all of the individual values in the constrained scope (element, property, field, etc.), or on ranges of values defined as buckets. You can define two types of buckets in a range constraint specification.

• Use the bucket portion of a range constraint to define a value range in terms of fixed values.
• Use the computed-bucket portion of a range constraint to define a value range in terms of a dynamic time that is computed at runtime. For more information about computed-bucket range constraints, see Computed Buckets Example.

The following example uses search:parse with query options that define a bucket range constraint. The constraint definition is based on the JSON data from Preparing to Run the Examples, but you can create a similar constraint on XML data.

xquery version "1.0-ml";
import module namespace search = 
  "http://marklogic.com/appservices/search"
  at "/MarkLogic/appservices/search/search.xqy";

search:parse('price:under10', 
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="price">
    <range type="xs:float" facet="true">
      <bucket lt="10" name="under10">under $10</bucket>
      <bucket ge="10" lt="21" name="10to20">$10 to $20</bucket>
      <bucket ge="21" name="20+">$20+</bucket>
      <facet-option>limit=10</facet-option>
      <json-property>/edition/price</json-property>
    </range>
  </constraint>
</options>)

With the given constraint definition, the query text price:under10 parses into the following cts:query:

<cts:and-query xmlns:cts="http://marklogic.com/cts">
  <cts:json-property-range-query operator="&gt;=">
    <cts:property>/edition/price</cts:property>
    <cts:value xsi:type="xs:float"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      10
    </cts:value>
  </cts:json-property-range-query>
  <cts:json-property-range-query operator="&lt;">
    <cts:property>/edition/price</cts:property>
    <cts:value xsi:type="xs:float"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      21
    </cts:value>
  </cts:json-property-range-query>
</cts:and-query>

For other range constraint examples, see Buckets Example and Computed Buckets Example, and the following example.

For syntax details, see bucket of the query options appendix.

Exact Match (Unbucketed) Range Constraint Example

The following example shows an exact match year range constraint. It returns results that match the xs:gYear value 1964 when it is the value of an XML element named nominee, in the namespace http://marklogic.com/wikipedia. The database configuration must include a range index matching the constraint definition.

xquery version "1.0-ml";

import module namespace search = 
  "http://marklogic.com/appservices/search"
  at "/MarkLogic/appservices/search/search.xqy";

let $options :=
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="year">
   <range type="xs:gYear" facet="true">
   <facet-option>limit=10</facet-option>
   <attribute ns="" name="year"/>
   <element ns="http://marklogic.com/wikipedia" 
            name="nominee"/>
   </range>
  </constraint>
</options>
return 
search:search("year:1964", $options)

You can also try out these query options with the Java and REST APIs. For details, see Apply Dynamic Query Options to Document Searches in the Java Application Developer's Guide or Specifying Dynamic Query Options with Combined Query in the REST Application Developer's Guide.

Geospatial Constraint Example

The following example shows how to use a geospatial constraint to generate geospatial facets in the form of boxes. For details on these options, see Appendix: Query Options Reference. For details on the concept of geospatial facets, see Creating Geospatial Facets.

Suppose the database contains documents of the following form, describing earthquake events:

<event xmlns="http://quakeml.org/xmlns/bed/1.2">
  <time>2015-03-24T09:39:15.500Z</time>
  <latitude>36.5305</latitude>
  <longitude>-98.8456</longitude>
  <depth>8.72</depth>
  <mag>3.4</mag>
  <magType>mb_lg</magType>
  <id>us10001q5d</id>
  <place>33km ENE of Mooreland, Oklahoma</place>
  <type>earthquake</type>
</event>

If you define a geospatial element pair range index on the /event/latitude and /event/longitude elements, then you can use query options to define an associated constraint that can be used to generate geospatial facets by including a heatmap element in the constraint definition.

The heatmap element defines a region over which to generate facets, along with the number of latitude and longitude divisions to use in sub-divisions the region into boxes. When you perform a search with the constraint in scope, the search response includes a set of search:box elements that give you the frequency of matches in each sub-division. You can use this box data for faceting or heatmap generation.

For example, the following constraint includes a heat map that corresponds very roughly to the continental United States, and divides the region into a set of 20 boxes (5 latitude divisions and 4 longitude divisions):

<constraint name="qgeo">
  <geo-elem-pair facet="true"> 
    <parent ns="http://quakeml.org/xmlns/bed/1.2" name="event"/> 
    <lat ns="http://quakeml.org/xmlns/bed/1.2" name="latitude"/> 
    <lon ns="http://quakeml.org/xmlns/bed/1.2" name="longitude"/>
    <heatmap s="24.0" n="49.0" e="-67.0" w="-125.0" 
             latdivs="5" londivs="4" />
    <facet-option>gridded</facet-option>
  </geo-elem-pair>
</constraint>

If you also define an element range index on /event/mag, then the following search finds earthquakes with a magnitude (mag) greater than 4.0 within the continental US.

xquery version "1.0-ml";
import module namespace search = "http://marklogic.com/appservices/search" at "/MarkLogic/appservices/search/search.xqy";

let $options :=
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="qgeo">
    <geo-elem-pair> 
      <parent ns="http://quakeml.org/xmlns/bed/1.2" name="event"/> 
      <lat ns="http://quakeml.org/xmlns/bed/1.2" name="latitude"/> 
      <lon ns="http://quakeml.org/xmlns/bed/1.2" name="longitude"/>
      <heatmap s="24.0" n="49.0" e="-67.0" w="-125.0" 
               latdivs="5" londivs="4" />
      <facet-option>gridded</facet-option>
    </geo-elem-pair>
  </constraint>
  <constraint name="mag">
    <range type="xs:float" facet="false">
      <element ns="http://quakeml.org/xmlns/bed/1.2" name="mag"/>
    </range>
  </constraint>
  <return-facets>true</return-facets>
</options>
return search:search("mag GT 4", $options)

The search response includes the following frequency count per geographic region, based on the geo constraint in the options:

<search:boxes name="qgeo">
  <search:box count="3" s="-18.9346" w="-178.4936" 
              n="-17.8151" e="-174.9279"/>
  <search:box count="2" s="-48.36" w="-87.3529" 
              n="7.6115" e="-81.8738"/>
  <search:box count="8" s="-20.7243" w="-73.0949" 
              n="6.8852" e="151.9563"/>
  <search:box count="2" s="36.2665" w="70.65" 
              n="36.4086" e="140.0085"/>
  <search:box count="3" s="53.6477" w="160.0923" 
              n="53.8233" e="161.7353"/>
</search:boxes>

By default, the returned boxes are the smallest box within each grid box that encompasses all the matched documents. To return boxes corresponding to the grid divisions instead, add <facet-option>gridded</facet-option> to the geo constraint definition. In this example it results in the following boxes:

<search:boxes name="qgeo">
  <search:box count="3" s="-90" w="-180" n="24" e="-125"/>
  <search:box count="2" s="-90" w="-96" n="24" e="-81.5"/>
  <search:box count="8" s="-90" w="-81.5" n="24" e="180"/>
  <search:box count="2" s="34" w="-81.5" n="39" e="180"/>
  <search:box count="3" s="44" w="-81.5" n="90" e="180"/>
</search:boxes>

For an example of expression a geospatial constraint in JSON, see geo-attr-pair and heatmap.

Note that the generated facets will bucket all matched points, even if they're outside the extent of the box defined in the heatmap. If you want to facet only within bounds of the heatmap, then your search results must be similarly constrained.

For example, you could add an additional-query option that constrains the search to the same box as defined by the heatmap using a cts:element-pair-geospatial-query.

Specifying transform-results Options

By default, the Search API has its own code to take search result matches and transform them into snippets used in the search results. By default, the Search API uses the apply="snippet" attribute on the transform-results option. Snippets tend to be very application specific, and the built-in apply="snippet" option has several parameters that you can control with a transform-results options node.

The following is the default transform-results options node:

<transform-results apply="snippet">
    <per-match-tokens>30</per-match-tokens>
    <max-matches>4</max-matches>
    <max-snippet-chars>200</max-snippet-chars>
    <preferred-matches/>
</transform-results>

The following table describes the transform-results options when apply="snippet", each of which is configurable at search runtime by specifying your own values for the options. For more details, see transform-results in the query options appendix.

per-match-tokens

max-matches

max-snippet-chars

preferred-matches

<transform-results apply="snippet">
  <preferred-matches>
    <element ns="" name="TITLE"/>
  </preferred-matches>
</transform-results>

<transform-results apply="snippet">
  <preferred-matches>
    <json-property>title</json-property>
  </preferred-matches>
</transform-results>

There are also three other built-in snippetting options, which are exposed as attributes on the transform-results options node:

• apply="raw"
• apply="empty-snippet"
• apply="metadata-snippet"

  The apply attribute for the transform-results element is only applicable to the search:search and search:resolve functions; search:snippet always uses the default snippetting option of snippet and ignores anything specified in the apply attribute.

The apply="raw" snippetting option looks as follows:

<transform-results apply="raw" />

The apply="raw" option returns the whole node (with no highlighting) in the search:response output. You can then take the node and do your own transformation on it, or just return it as-is, or whatever else makes sense for your application.

The apply="empty-snippet" snippetting option is as follows:

<transform-results apply="empty-snippet" />

The apply="empty-snippet" option returns no result node, but does return an empty search:snippet element for each search:result. The search:result wrapper element does have the information (for example, the URI and path to the node) needed to access the node and perform your own transformation on the matching search node(s), so you can write your own code outside of the Search API to process the results.

The apply="metadata-snippet" snippeting option is as follows:

<transform-results apply="metadata-snippet">
  <preferred-matches>
    <!-- Specify namespace and local name for elements that exist 
         in properties documents -->
    <element ns="http://my.namespace" name="my-local-name"/>
  </preferred-matches>
</transform-results>

The apply="metadata-snippet" option returns the specified preferred elements from the properties documents. If no <preferred-matches> element is specified, then the metadata-snippet option returns the prop:last-modified element for its snippet, and if the prop:last-modified element does not exist, it returns an empty snippet.

Specifying Your Own Code in transform-results

If the default snippet code does not meet your application requirements, you can use your own snippet code to use for a given search.

To specify your own snippet code, use the design pattern described in Search Customization Via Options and Extensions. The function you implement must have a signature compatible with the following signature:

declare function search:snippet(
   $result as node(),
   $ctsquery as schema-element(cts:query),
   $options as element(search:transform-results)?
) as element(search:snippet)

The Search API will pass the function the result node and the cts:query XML representation and your custom function can transform it any way you see fit. An options node that specifies a custom transformation looks as follows:

<options xmlns="http://marklogic.com/appservices/search">
  <transform-results apply="my-snippet" ns="my-namespace"
      at="/my-snippet.xqy">
  </transform-results>
</options>

You must generate an XML <search:snippet/> element, even when producing snippets for JSON documents. You can embed JSON in your generated snippet as text. If you include a format="json" attribute in your snippet, the REST, Java, and Node.js client APIs will treat the embedded text as JSON and unquote when returning search results as JSON. For example:

declare function my:snippeter(
   $result as node(),
   $ctsquery as schema-element(cts:query),
   $options as element(search:transform-results)?
) as element(search:snippet) {
    element search:snippet {
        attribute format { "json" },
        text {'{"MY":"CUSTOM SNIPPET"}'}
    }
};

You can optionally pass additional information into your custom snippeting function by adding extra children to the transform-results option. The Search API passes the transform-results element into your function, and if you want to use any part of the option, you can write code to parse the option and extract whatever you need from it.

Understanding Search Result Decorators

When you perform a query, MarkLogic Server returns a <search:response/> containing a <search:result> for each document or fragment that satisfies your query. You can use a search result decorator to add additional information to the each <search:result/>, without changing the basic structure or default contents.

For example, the MarkLogic REST API uses an internal result decorator to add href, mimetype, and format attributes to search results. The following output shows the extended information added by the REST API default decorator:

<search:response snippet-format="snippet" total="1" ...>
  <search:result ...
      href="/v1/documents?uri=/docs/example.xml" 
      mimetype="text/xml" format="xml">
  ...
  </search:result>
</search:response>

Applications using the XQuery Search API can use custom result decorators to similarly add attributes and elements to a <search:result/>.

Users of the REST API, Java, or Node.js Client API should use search result transformations to modify search results, rather than result decorators. It is possible to override the builtin REST API result decorator, but it is not recommended. If you use a custom result decorator in a Client API context, it completely replaces the default decorator that adds href, mimetype, and format data to results. Also, any data added by a decorator is returned as serialized XML, even when the client requests results in JSON.

To create and use a search result decorator, do the following:

1. Write an XQuery function that conforms to the decorator interface.
2. Install your function in the modules database or modules directory associated with your App Server.
3. Instruct MarkLogic Server to use your function by specifying it in a result-decorator query option that you supply with your search.

The rest of this section covers these steps in detail.

Writing a Custom Search Result Decorator

To create a custom decorator, implement an XQuery function that conforms to the following interface:

declare function your-name($uri as xs:string) as node()*

The $uri input parameter is the URI of a document containing search matches. The nodes returned by your function become attributes or child nodes of the search:result element on whose behalf it is called.

Your result decorator should always produce XML, even when working with JSON documents or producing output for a client expecting JSON search results.

The following example is a custom decorator function that returns the same information as the default REST API decorator (href, mimetype, and format), with the attribute names changed so you can see them in use. The example also adds a <my-elem/> element to the search results.

xquery version "1.0-ml";

module namespace my-lib = "http://marklogic.com/example/my-lib";

declare function my-lib:decorator($uri as xs:string) as node()*
{
  let $format   := xdmp:uri-format($uri)
  let $mimetype := xdmp:uri-content-type($uri)
  return (
    attribute my-href { concat("/documents/are/here?uri=", $uri) },
 
    if (empty($mimetype)) then ()
    else attribute my-mimetype {$mimetype},
 
    if (empty($format)) then ()
    else attribute my-format { $format }

    element my-elem { "Extra Goodness" }
  )
};

To use your function, install it as a module in your App Server, and then specify it in a result-decorator query option. For details, see Installing a Custom Search Result Decorator and Using a Custom Search Result Decorator.

Installing a Custom Search Result Decorator

Install the XQuery library module containing your decorator function in the modules database or under the filesystem root associated with your App Server.

For example, running the following query in Query Console loads an XQuery module into the modules database with the URI /my.domain/decorator.xqy, assuming you select the modules database as the Content Source in Query Console:

xquery version "1.0-ml";
xdmp:document-load(
  "/space/rest/decorator.xqy",
  <options xmlns="xdmp:document-load">
    <uri>/my.domain/decorator.xqy</uri>
  </options>)

If you use the REST API or Java API, install the module in the modules database associated with your REST API instace.

Using a Custom Search Result Decorator

To use a custom search result decorator, specify it in a result-decorator query option that is included with your query.

For example, if you install the custom decorator from Writing a Custom Search Result Decorator as /my.domain/decorator.xqy, then you can reference it in query options as follows:

<options xmlns="http://marklogic.com/appservices/search">
  <result-decorator apply="decorator"
      ns="http://marklogic.com/example/my-lib"
      at="/my.domain/decorator.xqy"/>
</options>

The following example uses the above query options in a search:

xquery version "1.0-ml";
import module namespace search =
  "http://marklogic.com/appservices/search"
     at "/MarkLogic/appservices/search/search.xqy";

search:search(
  "cat AND dog",
  <options xmlns="http://marklogic.com/appservices/search">
    <result-decorator apply="decorator"
        ns="http://marklogic.com/example/my-lib"
        at="/my.domain/decorator.xqy" />
  </options>
)

The decorator adds the my-href, my-mimetype, and my-format attributes and the my-elem element to the search results, similar to the following:

<search:response ...>
  <search:result index="1" uri="/docs/example.xml" 
       path="fn:doc(&quot;/docs/example.xml&quot;)" ...
       my-href="/documents/are/here?uri=/docs/example.xml" 
       my-mimetype="text/xml" my-format="xml">
    <my-elem>Extra Goodness!</my-elem>
    ...
  </search:result>
</search:response>

Example: Values and Tuples Query Options

This examples demonstrates how to create and use a values or tuples query option. For more details, see values and tuples in the query options appendix.

This example sets up the following configurations:

• A values tuple /v1/values/pop, which gets the values from the element range index from xs:QName("popularity") (in no namespace), and is typed as an xs:int.
• A values tuple /v1/values/score, which gets the values from the element range index from a QName with namespace "http://test.aggr.com" and local name "score", typed as an xs:decimal.
• A tuple /v1/values/pop-rate-tups, which combines the range index from from xs:QName("popularity") (in no namespace), and typed as an xs:int, and the range index from a QName with namespace "http://test.aggr.com" and local name "score", typed as an xs:decimal.

<search:options
  xmlns:search="http://marklogic.com/appservices/search">
  <search:values name="pop-aggr">
    <search:range type="xs:int">
      <search:element ns="" name="popularity"/> 
    </search:range> 
  </search:values> 
  <search:values name="score-aggr"> 
    <search:range type="xs:decimal"> 
      <search:element ns="http://test.aggr.com" name="score"/>
    </search:range> 
  </search:values> 
  <search:tuples name="pop-rate-tups"> 
    <search:range type="xs:int"> 
      <search:element ns="" name="popularity"/> 
    </search:range> 
    <search:range type="xs:int"> 
      <search:element ns="http://test.tups.com" name="rate"/>
    </search:range> 
  </search:tuples> 
</search:options>

{ "options": {
    "values": [ {
      "name": "pop-aggr",
      "range": {
        "type": "xs:int",
        "element": {
           "ns": "",
           "name": "popularity"
        }
      }
    },
    {
      "name": "score-aggr",
      "range": {
        "type": "xs:decimal",
        "element": {
          "ns": "http://test.aggr.com",
          "name": "score"
        }
      }
    } ],
    "tuples": [ {
      "name": "pop-rate-tups",
      "range": [
         {
           "type": "xs:int",
           "element": {
             "ns": "",
             "name": "popularity"
           }
         },
         {
           "type": "xs:int",
           "element": {
             "ns": "http://test.tups.com",
             "name": "rate"
           }
         }
       ]
    } ]
} }

Example: Field Constraint Query Options

This example constructs a simple options node that sets up just one constraint, based on the field named "bbqtext". It creates a word constraint, therefore when you search for

summary:"hot dog"

It constrains the search to documents that have the phrase "hot dog" in the field called "bbqtext".

<search:options
    xmlns:search="http://marklogic.com/appservices/search">
    <search:constraint name="summary">
      <search:word>
        <search:field name="bbqtext"/>
      </search:word>
    </search:constraint>
</search:options>

{ "options": {
    "constraint": [ {
      "name": "summary",
      "word": {
        "field": { "name": "bbqtext" }
      }
    } ]
} }

For more details, see constraint in the query options appendix.

Example: Collection Constraint Query Options

The query options in this example do the following:

• Sets flags that modify the search results (return-metrics and return-qtext).
• Specifies a builtin transform-results function that will return raw document search results.
• Defines a collection constraint that uses the collection URIs.

The collection constraint named "coll" uses the collection URIs with "http://test.com" stripped off.

<search:options
    xmlns:search="http://marklogic.com/appservices/search">
  <search:debug>true</search:debug>
  <search:constraint name="coll">
    <search:collection prefix="http://test.com"/> 
  </search:constraint>
  <search:return-metrics>false</search:return-metrics>
  <search:return-qtext>false</search:return-qtext>
  <search:transform-results apply="raw">
    <search:preferred-matches/>
  </search:transform-results>
</search:options>

{ "options": {
    "debug": true,
    "constraint": [ {
      "name": "coll",
      "collection": { "prefix": "http://test.com" }
    } ],
    "return-metrics": false,
    "return-qtext": false,
    "transform-results": {
      "apply": "raw",
      "preferred-matches": ""
    }
} }

For more details, see collection in the query options appendix.

Example: Path Range Index Constraint Query Options

This example shows how to configure a constraint with a path range index. With this in place, searching for:

pindex:low

Searches for values less than 5 from the nodes at /Employee/fn (in no namespace). It is a string range index, faceted, scoped to documents, with a nice looking unicode label. The facet values are returned with any search.

<search:options
    xmlns:search="http://marklogic.com/appservices/search">
  <search:constraint name="pindex">
    <search:range type="xs:string" facet="true" 
       collation="http://marklogic.com/collation/">
      <search:path-index>/Employee/fn</search:path-index>
      <search:fragment-scope>documents</search:fragment-scope>
      <search:bucket name="low" ge="5">0 to 5</search:bucket>
      <search:bucket name="medium" lt="10" ge="5"
         >5 to 10</search:bucket>
      <search:bucket name="high" lt="15" ge="10"
         >10 to 15</search:bucket>
    </search:range>
  </search:constraint>
</search:options>

{ "options": {
    "constraint": [ {
      "name": "pindex",
      "range": {
        "type": "xs:string",
        "facet": true,
        "collation": "http://marklogic.com/collation/",
        "path-index": { "text": "/Employee/fn" },
        "fragment-scope": "documents",
        "bucket": [
          {
            "name": "low",
            "lt": "5",
            "label": "0 to 5"
          },
          {
            "name": "medium",
            "lt": "10",
            "ge": "5",
            "label": "5 to 10"
          },
          {
            "name": "high",
            "lt": "15",
            "ge": "10",
            "label": "10 to 15"
          }
        ]
      }
  } ]
} }

Example: Element Attribute Range Constraint Query Options

This example shows an element attribute range index, with computed buckets. When you search, the facets will be filled out depending on the values of {http://example.com}entry/@date.

<search:options
    xmlns:search="http://marklogic.com/appservices/search">
  <search:constraint name="date">
    <search:range type="xs:dateTime" facet="true"> 
      <search:attribute ns="" name="date"/> 
      <search:element ns="http://example.com" name="entry"/>
      <search:fragment-scope>documents</search:fragment-scope>
      <search:computed-bucket name="older" lt="-P1Y" 
        anchor="start-of-year">Older</search:computed-bucket>
      <search:computed-bucket name="year" lt="P1Y" ge="P0Y" 
        anchor="start-of-year">This Year</search:computed-bucket>
      <search:computed-bucket name="month" lt="P0M" ge="P1M" 
        anchor="start-of-month">This Month</search:computed-bucket>
      <search:computed-bucket name="today" lt="P0D" ge="P1D" 
        anchor="start-of-day">Today</search:computed-bucket>
      <search:computed-bucket name="future" ge="P0D" 
        anchor="now">Future</search:computed-bucket>
    </search:range>
  </search:constraint>
</search:options>

{ "options": {
    "constraint": [ {
      "name": "date",
      "range": {
        "type": "xs:dateTime",
        "facet": true,
        "attribute": {
          "ns": "",
          "name": "date"
        },
        "element": {
          "ns": "http://example.com",
          "name": "entry"
        },
        "fragment-scope": "documents",
        "computed-bucket": [
          {
            "name": "older",
            "lt": "-P1Y",
            "anchor": "start-of-year",
            "label": "Older"
          },
          {
            "name": "year",
            "lt": "P1Y",
            "ge": "P0Y",
            "anchor": "start-of-year",
            "label": "This Year"
          },
          {
            "name": "month",
            "lt": "P0M",
            "ge": "P1M",
            "anchor": "start-of-month",
            "label": "This Month"
          },
          {
            "name": "today",
            "lt": "P0D",
            "ge": "P1D",
            "anchor": "start-of-day",
            "label": "Today"
          },
          {
            "name": "future",
            "ge": "P0D",
            "anchor": "now",
            "label": "Future"
          }
        ]
}}]}}

Example: Geospatial Constraint Query Options

This example shows geospatial constraint query options. In addition to having a search results configuration setting (page-length), this sets up three geospatial constraints and three element constraints.

<search:options
    xmlns:search="http://marklogic.com/appservices/search">
  <search:debug>true</search:debug>
  <search:return-metrics>false</search:return-metrics>
  <search:page-length>25</search:page-length>
  <search:constraint name="geo-elem">
    <search:geo-elem>
      <search:element ns="" name="g-elem-point"/> 
    </search:geo-elem> 
    </search:constraint> 
    <search:constraint name="geo-elem-pair"> 
      <search:geo-elem-pair> 
        <search:lat ns="" name="lat"/> 
        <search:lon ns="" name="long"/> 
        <search:parent ns="" name="g-elem-pair"/>
    </search:geo-elem-pair> 
  </search:constraint> 
  <search:constraint name="geo-attr-pair"> 
    <search:geo-attr-pair> 
      <search:lat ns="" name="lat"/> 
      <search:lon ns="" name="long"/> 
      <search:parent ns="" name="g-attr-pair"/> 
    </search:geo-attr-pair> 
  </search:constraint>
</search:options>

{ "options": {
    "debug": true,
    "return-metrics": false,
    "page-length": 25,
    "constraint": [
      { "name": "geo-elem",
        "geo-elem": {
          "element": {
            "ns": "",
            "name": "g-elem-point"
          }
        }
      },
      { "name": "geo-elem-pair",
        "geo-elem-pair": {
          "lat": {
            "ns": "",
            "name": "lat"
          },
          "lon": {
            "ns": "",
            "name": "long"
          },
          "parent": {
            "ns": "",
            "name": "g-elem-pair"
          }
        }
      },
      { "name": "geo-attr-pair",
        "geo-attr-pair": {
          "lat": {
            "ns": "",
            "name": "lat"
          },
          "lon": {
            "ns": "",
            "name": "long"
          },
          "parent": {
            "ns": "",
            "name": "g-attr-pair"
          }
        }
      }
    ]
} }