Loading TOC...
Search Developer's Guide (PDF)

Search Developer's Guide — Chapter 31

Appendix: Query Options Reference

This appendix is a reference guide to the query options used for search and lexicon analysis by the XQuery Search API and the MarkLogic Client APIs (REST, Java, Node.js). This appendix contains the following topics:

How to Use This Reference

This reference describes the layout of the query options structure usable with search and lexicon query interfaces of the XQuery Search API (search:search, search:values, etc.) and the Client APIs (REST, Java, Node.js). Both XML and JSON representations are shown, but not all APIs support both representations; consult the reference for the API you're using.

Some of the APIs provide builders for constructing query options, so you do not need to know the syntax. However, this appendix can still be useful with a builder because it provides details on the meaning, defaults, and limits for specific option components.

The Syntax Summary for each option shows all possible components, but not all are required and some cannot be used together. Refer to the Component Description section for details on a given option.

Option components that can be specified as repeating XML elements are usually represented by array values in JSON. In many cases, you can omit the array wrapper if there is only one element.

Options Summary

A single options node or object can contain can contain options useful for document searches, lexicon and index queries, and/or search term completion suggestions. However, not all options are used by all operations. For example, the values and tuples options only apply to lexicon query operations (search:values), default-suggestion-source only applies to search term completion suggestion operations (search:suggest), and extract-document-data only applies to document searches (search:search).

A set of query options has the following structure. You can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<options>
  anyOption...
</options>
{"options": { 
  anyOption, ...
}

Where anyOption is zero or more of the child components summarized in the following table. For more details about a given option, see the option-specific topic.

Key Description
additional-query Additional serialized cts:query's, as XML literals. This option has array value in JSON and can appear multiple times in XML.
concurrency-level The maximum number of threads used to resolve facets.
constraint Zero or more constraints that limit the scope of a search and/or define facets which can be returned as part of the search results. This option has array value in JSON and can appear multiple times in XML.
debug Whether or not to enable debugging mode. The default is false.
default-suggestion-source Defines the content to be used as the default source of suggestions (see search:suggest).
extract-document-data Specify element, attribute, or JSON property content from the search matches to return.
forest One or more forest IDs. This option has array value in JSON and can appear multiple times in XML.
fragment-scope Controls the global fragment scope over which to search.
grammar A custom search grammar definition.
operator A list of state elements, each representing a unique run-time configuration option. This option has array value in JSON and can appear multiple times in XML.
page-length The number of results to return per page. The default value is 10.
quality-weight Specifies a weighting factor to use in the query. The default value is 1.0.
return-aggregates Include the result of running a builtin or user-defined aggregate function. Applies only to queries against values or tuples.
return-constraints Include the input constraint definitions in the results. The default is false.
return-facets Include resolved facets in the results. The default is true.
return-frequencies Include frequencies in the results. The default is true.
return-metrics Include performance statistics in the results. The default is true.
return-plan Include xdmp:plan output in the results. The default is false.
return-qtext Include the original query text in the results. The default is true.
return-query Include the XML query representation in the results. The default is false.
return-results Include search results in the output. The default is true.
return-similar Include with each search result a list of URLs of similar documents in the database. The default is false.
return-values When querying a range index or values lexicon, whether or not to include the index/lexicon values in the results. Default: true.
For advanced users, one or more options to pass to the underlying query operation. This option has array value in JSON and can appear multiple times in XML.
searchable-expression An XPath expression to be searched. Whatever expression is specified is returned from the search.
sort-order Set the default sort order. The first such value is the primary sort order, the second is secondary sort order, and so on. This option has array value in JSON and can appear multiple times in XML.
suggestion-source Specify a search term completion suggestion source.
transform-results Specify a function to use to process a search result for the snippet output.
tuples Define one or more value lexicons query against, matching value co-occurrences. That is, tuples of values, each of which appear in the same fragment.
values Define one or more value lexicons to query against.

additional-query

Use this option to specify one or more additional cts queries to apply when searching documents and generating suggestions. The queries are AND'd with the input query. The query results are constrained by the additional-query(s).

Specify each additional query value as the serialized XML representation of a cts:query.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<additional-query>
  serialized-cts-query
</additional-query>
"additional-query": [ 
  "serialized-cts-query"
]

Component Description

The text value that represents each additional query is a serialized cts:query. In XML options, it is represented as XML. In JSON options, it is a string containing the serialized XML.

If your query options include multiple additional queries, they are AND'd together, as if with cts:and-query.

Examples

The following example constrains the results to the directory named /my/directory/. Whitespace and linebreaks are added for readability.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <additional-query>
    <cts:directory-query xmlns:cts="http://marklogic.com/cts">
      <cts:uri>/my/directory/</cts:uri>
    </cts:directory-query>
  </additional-query>
</options>
JSON
{"options": {
  "additional-query":[
    "<directory-query xmlns='http://marklogic.com/cts'>
      <uri>/my/directory/</uri>
    </directory-query>"
  ]
}}

See Also

For more details, see the following topics:

concurrency-level

The maximum number of threads to use when resolving facets. The default is 8, which specifies that at most 8 threads will be used concurrently to resolve facets. The value of this option should be an integer value greater than 0. The default value is 8.

The following example specifies a concurrency level of 16.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <concurrency-level>16</concurrency-level>
</options>
JSON
{"options": {
  "concurrency-level": 16
}}

constraint

This option forms the outer container for a constraint definition. Use constraints to limit the scope of a search and/or define facets that can be returned as part of the search results. Constraints can also be applicable when generating search suggestions. No constraints are defined by default.

Each constraint must include a name that is unique among the options in scope for a search. The constraint name can be used as a term qualifier in a string query; for details, see Searching Using String Queries. The name can also be used to identify the constraint in some kinds of structured queries and QBE's.

This section includes the following high level topics about the constraint option:

This section also includes detailed descriptions of each of the following constraint types and the more complex components of range and geospatial constraints, such as bucket, computed-bucket, and heatmap.

Syntax Summary

This option has the following structure. Each constraint must include a name and exactly one constraint specification. An options node can define multiple constraints. In JSON, the constraint array can be empty. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<constraint name="uniqueName">
  <annotation/>
  anyConstraintType
</constraint>
"constraint": [
  {"name": "uniqueName",
   "annotation": string,
   anyConstraintType
  }
]

Where anyConstraintType is one of the following constraint specifications:

Component Description

The components of this option have the following semantics. A constraint can contain the following child elements or properties.

Element, Attribute or Property Name Description
name Required. An identifier for the constraint. The name must be unique within the in-scope query options and may not contain whitespace.
annotation Your comments. Annotations have no effect on a query.
anyConstraintType A constraint specification. For a list of constraint types, see Syntax Summary.

Examples

The following example defines two constraints: a container constraint that limits matches to those that occur within an XML element named TITLE, and a value constraint that limits matches to the values in an XML element named COST. For more examples, refer to the individual constraint types.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="title">
    <container>
      <element ns="" name="TITLE" />
    </container>
  </constraint>
  <constraint name="cost">
    <value>
      <element ns="" name="COST" />
    </value>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "title",
      "container": {
      "element": {
        "ns": "",
        "name": "TITLE"
    }}},
    { "name": "cost",
      "value": {
        "element": {
          "ns": "",
          "name": "COST"
    }}}
  ]
}}

See Also

For more details, see the following topics and the See Also topics for individual constraint types.

range

A component of a constraint option that specifies an XML element, XML element attribute, field, JSON property, or XPath expression on which to constrain by range, as in a range query.

There must be a range index of the specified type (and collation for string range indexes) defined for the specified element, attribute, JSON property, field, or path.

For best performance of range constraints that include bucket or computed-bucket specifications, define the buckets in a consistent, sorted order (ascending or descending). If the order is not consistent, then the bucketed results are returned in the order specified, regardless of any sorting facet-option in the specification.

Syntax Summary

This option has the following structure. The definition must include exactly one of element, field, json-property, or path-index descriptor. If there is an element, an attribute descriptor may also be included. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<range type="indexedType" 
       collation="collURI"
       facet="boolean"
       nullable="boolean">
  <element ns="namespace" name="name"/>
  <attribute ns="namespace" name="name"/>
  <field name="name"/>
  <json-property>name</json-property>
  <path-index/>
  <fragment-scope>scope</fragment-scope>
  <bucket/>
  <computed-bucket/>
  <facet-option>option</facet-option>
  <range-option>option</range-option>
  <weight>double</weight>
</range>
"range": {
  "type": string,
  "collation" : string,
  "facet": boolean,

  "element": {
    "ns": "namespace",
    "name": "name"
  },
  "attribute": {
    "ns": "namespace",
    "name": "name"
  },
  "field": {"name": "name"},
  "json-property": "name",
  "path-index": [path index desc],
  "fragment-scope": "scope",
  "bucket": [bucket descriptor],
  "computed-bucket": [bucket desc],
  "facet-option" : [ "option" ],
  "range-option": [ "option" ],
  "nullable" : boolean,
  "weight": double
}
Component Description

The components of this option have the following semantics. The definition must include exactly one of element, json-property, field, or path-index. All other components are optional.

Element, Attribute or Property Name Description
type The type of the values in the associated index. The database configuration must include a range index with this type. Use collation to further disambiguate range indexes of type xs:string.
collation A collation URI. If this value is present, the database configuration should include a range index of type xs:string that uses this collation. If not specified, the default Root Collation is assumed. For details, see Collations.
facet Whether or not to include facets based on this constraint in the query results.
nullable Whether or not to allow null values in tuples when making a values query.
element

Defines an XML element to constrain by. If there is an element, there can also be an attribute. Specify the element local name in name. If the element is in a namespace, specify the namespace URI in ns.

The database configuration must include a corresponding element or element attribute range index.

attribute

Defines an XML element attribute to constrain by. There must be an accompanying element descriptor. Specify the attribute local name in name. If the attribute is in a namespace, specify the namespace URI in ns.

The database configuration must include a corresponding element attribute range index.

json-property

Defines a JSON property to constrain by.

The database configuration must include a corresponding element range index. (JSON properties are indexed using element range indexes.)

field

Defines a field to constrain by.

The database configuration must include a corresponding field range index.

path-index

Defines a path range index reference to constrain by. For details, see path-index. In XML, you can specify multiple indexes by including this component multiple times. In JSON, you can specify multiple indexes by setting the property value to an array of path index descriptors.

The database configuration must include a corresponding path range index.

fragment-scope Set a local fragment scope for this constraint. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
bucket Zero or more named ranges of static values. For details, see bucket.
computed-bucket Zero or more named ranges of dynamic values. For details, see computed-bucket.
facet-option Specify faceting options to apply when generating facets. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. For details, see Facet Options.
range-option Specify range options that influence the interpretation of the constraint. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <range-option>min-occurs=2</range-option> in XML, or "range-option": ["min-occurs=2"] in JSON. For details, see Range Options.
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
Examples

This section contains an example contains one of each type of range constraint and an example that demonstrates the use of faceting options. For more examples, see bucket and computed-bucket.

The following example includes one of each basic type of range constraint: element, element attribute, JSON property, field, and path index. The database configuration must include a range index that corresponds to each constraint.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="elem">
    <range type="xs:string">
      <element ns="myNsURI" name="anElemName"/>
    </range>
  </constraint>
  <constraint name="attr">
    <range type="xs:string">
      <element ns="myNsURI" name="anElemName"/>
      <attribute ns="myNsURI" name="anAttrName" />
    </range>
  </constraint>
  <constraint name="json-prop">
    <range type="xs:string">
      <json-property>aPropName</json-property>
    </range>
  </constraint>
  <constraint name="field">
    <range type="xs:string"
        collation="http://marklogic.com/collation/codepoint">
      <field name="aFieldName"/>
    </range>
  </constraint>
  <constraint name="path">
    <range type="xs:gYear" facet="true">
      <path-index xmlns:my="http://example.com">
        /publication/my:meta/my:year
      </path-index>
    </range>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "elem",
      "range": {
        "type": "xs:string",
        "element": { "ns": "myNsURI", "name": "anElemName" }
    }},
    { "name": "attr",
      "range": {
        "type": "xs:string",
        "element": { "ns": "myNsURI", "name": "anElemName" },
        "attribute": { "ns": "myNsURI", "name": "anAttrName" }
    }},
    { "name": "json-prop",
      "range": {
        "type": "xs:string",
        "json-property": { "name": "aPropName" }
    }},
    { "name": "field",
      "range": {
        "type": "xs:string",
        "collation": "http://marklogic.com/collation/codepoint",
        "field": { "name": "aFieldName" }
    }},
    { "name": "path",
      "range": {
        "type": "xs:gYear",
        "facet": true,
        "path-index": { 
          "namespaces": {"my": "http://example.com"}, 
          "text": "/publication/my:meta/my:year" 
        }
    }}
  ]
}}

The following example defines a constraint that is used to generate facets. The facet-option values are passed to the underlying lexicon calls.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="color">
    <range type="xs:string" facet="true">
      <element ns="myNsURI" name="bodycolor"/>
      <facet-option>frequency-order</facet-option>
      <facet-option>descending</facet-option>
    </range>
  </constraint>
  <constraint name="owner">
</options>
JSON
{"options": {
  "constraint": [
    { "name": "color",
      "range": {
        "type": "xs:string",
        "facet": true,
        "element": { "ns": "myNsURI", "name": "bodycolor" },
        "facet-option": [ "frequence-order", "descending" ]
  }}]
}}

value

A component of a constraint option that specifies a XML element, XML attribute, JSON property, or field on which to constrain, as in a value query. For JSON property constraints, you can optionally specify a node using value/@type. If present, type must be one of string (default), number, boolean, or null. You cannot create facets from a value constraint.

Syntax Summary

A value constraint definition has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<value type="jsonNodeType">
  <element ns="namespace" name="name"/>
  <attribute ns="namespace" name="name"/>
  <field name="fieldName"/>
  <json-property>name</json-property>
  <fragment-scope>scope</fragment-scope>
  <weight>double</weight>
  <term-option>option</term-option>
</value>
"value": {
  "type": "jsonNodeType"
  "element": {
    "ns": "namespace",
    "name": "name"
  },
  "attribute": {
    "ns": "namespace",
    "name": "name"
  },
  "json-property": "name",
  "field": {"name": "fieldName"},
  "weight": double,
  "fragment-scope": "scope",
  "term-option": [ "option" ]
}
Component Description

The components of this option have the following semantics. The definition must include exactly one of element, json-property, or field. If there is an element, there can also be an attribute.

Element, Attribute or Property Name Description
type A JSON node type, one of string (default), boolean, null, number. Only meaningful for JSON content. Use type to constrain the matches to values in this node type. Non-JSON documents never contain nodes of these types. Optional.
element Defines an XML element on which to constrain queries If there is an element, there can also be an attribute. Specify the element local name in name. If the element is in a namespace, specify the namespace URI in ns.
attribute Defines an XML element attribute on which to constrain queries. There must be an accompanying element descriptor. Specify the attribute local name in name. If the attribute is in a namespace, specify the namespace URI in ns.
json-property Defines a JSON property on which to constrain queries.
field Defines a field on which to constrain queries.
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
fragment-scope Set a local fragment scope for this constraint. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
term-option Specify options to apply when generating facets. In XML, specify multiple options by including the element multiple times. If the option has a value, the element or array item value is of the form option=value. For example: <term-option>lang=en</term-option> in XML, or "term-option": ["lang=en"] in JSON. Term Options.
Examples

The following example includes a value constraint of each type: element, element attribute, JSON property, and field.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-elem-value">
    <value>
      <element ns="my-namespace" name="my-localname"/>
    </value>
  </constraint> 
  <constraint name="my-attr-value">
    <value>
      <attribute ns="" name="my-attribute"/>
      <element ns="my-namespace" name="my-localname"/>
    </value>
  </constraint>
  <constraint name="my-json-value">
    <value type="number">
      <json-property>myNumericPropName</json-property>
    </value>
  </constraint>
  <constraint name="my-field-value">
    <value>
      <field name="fieldvalue"/>
      <weight>2.0</weight>
    </value>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "my-elem-value",
      "value": {
        "element": {"ns": "my-namespace","name": "my-localname"}
    }},
    { "name": "my-attr-value",
      "value": {
        "element": {"ns": "my-namespace","name": "my-localname"},
        "attribute": {"ns": "","name": "my-attribute"}
    }},
    { "name": "my-json-value",
      "value": {
        "type": "number",
        "json-property": "myNumericPropName"
    }},
    { "name": "my-field-value",
      "value": {
        "field": {"name": "fieldName"},
        "weight": 2.0
    }}
  ]
}}
See Also

For more details on using this option, see the following topics:

word

A component of a constraint option that specifies the XML element, XML element attribute, JSON property, or field on which to constrain by word. You cannot create facets from a word constraint.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<word>
  <element ns="namespace" name="name"/>
  <attribute ns="namespace" name="name"/>
  <field name="name"/>
  <json-property>name</json-property>
  <fragment-scope>scope</fragment-scope>
  <weight>double</weight>
  <term-option>option</term-option>
</word>
"word": {
  "element": {
    "ns": "namespace",
    "name": "name"
  },
  "attribute": {
    "ns": "namespace",
    "name": "name"
  },
  "json-property": "name",
  "field": {"name": "name"},
  "weight": double,
  "fragment-scope": "scope",
  "term-option": [ "option" ]
}
Component Description

The child components of this option have the following semantics:

Element, Attribute or Property Name Description
element Defines an XML element on which to constrain queries If there is an element, there can also be an attribute. Specify the element local name in name. If the element is in a namespace, specify the namespace URI in ns.
attribute Defines an XML element attribute on which to constrain queries. There must be an accompanying element descriptor. Specify the attribute local name in name. If the attribute is in a namespace, specify the namespace URI in ns.
json-property Defines a JSON property on which to constrain queries.
field Defines a field on which to constrain queries.
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
fragment-scope Set a local fragment scope for this constraint. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
term-option Specify options to apply when generating facets. In XML, specify multiple options by including the element multiple times. If the option has a value, the element or array item value is of the form option=value. For example: <term-option>lang=en</term-option> in XML, or "term-option": ["lang=en"] in JSON. For details, see Term Options.
Examples

The following example includes a word constraint of each possible type (element, element attribute, JSON property, and field). The JSON property constraint demonstrates the use of term options. The field constraint demonstrates the use of a custom weight.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-elem-value">
    <word>
      <element ns="my-namespace" name="my-localname"/>
    </word>
  </constraint> 
  <constraint name="my-attr-value">
    <word>
      <attribute ns="" name="my-attribute"/>
      <element ns="my-namespace" name="my-localname"/>
    </word>
  </constraint>
  <constraint name="my-json-value">
    <word>
      <json-property>myPropName</json-property>
      <term-option>case-sensitive</term-option>
      <term-option>unstemmed</term-option>
    </word>
  </constraint>
  <constraint name="my-field-value">
    <word>
      <field name="fieldvalue"/>
      <weight>2.0</weight>
    </word>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "my-elem-value",
      "word": {
        "element": {"ns": "my-namespace","name": "my-localname"}
    }},
    { "name": "my-attr-value",
      "word": {
        "element": {"ns": "my-namespace","name": "my-localname"},
        "attribute": {"ns": "","name": "my-attribute"}
    }},
    { "name": "my-json-value",
      "word": {
        "json-property": "myPropName",
        "term-option": ["case-sensitive", "unstemmed"]
    }},
    { "name": "my-field-value",
      "value": {
        "field": {"name": "fieldName"},
        "weight": 2.0
    }}
  ]
}}
See Also

For more details on using this option, see the following topics:

collection

A component of a constraint option that constrains results by collection, matching either documents in the specified collections or in collections with the specified collection URI prefix.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<collection prefix="URIpfx" facet="boolean">
  <facet-option>option</facet-option>
</collection>
"collection": {
  "prefix": "URIprefix",
  "facet-option": [ "option" ],
  "facet": boolean
}
Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
prefix Constrain matches to collections with collection URIs matching this prefix. Use this component to as shorthand when constraining by collections with a shared URI prefix. For details, see Examples.
facet Whether or not to generate facets from this constraint. Default: true.
facet-option Specify options to apply when generating facets. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. Facet Options.
Examples

The following example defines a constraint that limits results to matches in documents in collections with the URI prefix /my/collection/. The constraint also indicates facets should be generated using the collection (facet is true). The facet option limit specifies that at most 5 results are returned.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="mycoll" facet="true">
    <collection prefix="/my/collection/"/>
      <facet-option>limit=5</facet-option>
    </collection>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "mycoll",
      "collection": {
        "prefix": "/my/collection/",
        "facet": true,
        "facet-option": [ "limit=5" ]
    }}
  ]
}}

For example, if your database includes documents in the collections /my/collection/animals and /my/collections/edibles, then the following string query text matches documents containing the term aardvark that are also in the collection /my/collection/animals.

mycoll:animals AND aardvark

Omit the prefix to constrain on complete collection URIs. For example, if you omit prefix from the above constraint definition, then you would find the same documents with the following query text:

mycoll:/my/collection/animals AND aardvark
See Also

For more details on using this option, see the following topics:

container

A component of a constraint option that specifies a constraint that restricts a search to a specified XML element or JSON property container. You cannot create facets from a container constraint.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<container>
  <element ns="namespace" name="name"/>
  <json-property>name</json-property>
  <fragment-scope>scope</fragment-scope>
</container>
"container": {
  "element": {
    "ns": "namespace",
    "name": "name"
  },
  "json-property": "name",
  "fragment-scope": "scope"
}
Component Description

The components of this option have the following semantics. The constraint must include exactly one of element or json-property.

Element, Attribute or Property Name Description
element Defines an XML element on which to constrain queries. Specify the element local name in name. If the element is in a namespace, specify the namespace URI in ns.
json-property Defines a JSON property on which to constrain queries.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
Examples

The following example includes two container constraints, one on an XML element and one on a JSON property.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="ele-container-constraint">
    <container>
      <element name="title" ns="http://my/namespace" />
    </container>
  </constraint>
  <constraint name="json-container-constraint">
    <container>
      <json-property>author</json-property>
    </container>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "ele-container-constraint",
      "container": {
        "element": {"ns": "http://my/namespace","name": "title"}
    }},
    { "name": "json-container-constraint",
      "container": {
        "json-property": "author",
    }}
  ]
}}
See Also

For more details on using this option, see the following topics:

element-query

A component of a constraint option that specifies a constraint that restricts the search to the specified element. You cannot create facets from an element-query constraint.

This option is deprecated. Use container instead.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<element-query ns="namespace" name="name"/>
  <fragment-scope>scope</fragment-scope>
</element-query>
"element-query": {
  "ns": "namespace",
  "name": "name",
  "fragment-scope": "scope"
}
Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
ns The namespace of the element, if it is in a namespace.
name Required. The local name of the element.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
Examples

The following example demonstrates an element-query constraint on the element title in the namespace http://my/namespace. This option is deprecated; use container instead.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="elem-constraint">
    <element-query name="title" ns="http://my/namespace" />
  </constraint>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "elem-constraint",
      "element-query": {
        "ns": "http://my/namespace",
        "name": "title"
    }}
  ]
}}

properties

A component of a constraint option that limits matches to those found in document properties. To constrain by JSON property, see container.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<properties/>
{ "properties": null }
Examples

The following example limits matches to those found in document properties.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="prop-constraint">
    <properties />
  </constraint>
</options>
JSON
{"options": {
  "constraint": [{
    "name": "prop-constraint", 
    "properties": null" }
  }]
}}
See Also

For more details on using this option, see the following topics:

geo-attr-pair

A component of a constraint option that models a geospatial index with coordinates stored as XML element attributes. That is, geospatial data of the following form:

<parent lat="value" lon="value">

For similar JSON data, use geo-json-property-pair.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-attr-pair>
  <parent ns="namespace" name="elemName" />
  <lat ns="namespace" name="attrName" />
  <lon ns="namespace" name="attrName" />
  <facet-option>option</facet-option>
  <heatmap>heatmap descriptor</heatmap>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
  <weight>double</weight>
</geo-attr-pair>
"geo-attr-pair": {
  "parent": [{
    "ns": "namespace",
    "name": "elemName",
  }],
  "lat": [{
    "ns": "namespace",
    "name": "attrName",
  }],
  "lon": [{
    "ns": "namespace",
    "name": "attrName",
  }],
  "facet-option": [ option ],
  "heatmap": {heatmap desc},
  "geo-option": [ option ],
  "fragment-scope": "scope",
  "weight": double
}
Component Description

By default coordinates are stored as (latitude,longitude) points. To reverse the coordinate order, add the geo-option "long-lat-point" to the query options configuration. For more details, see cts:element-attribute-pair-geospatial-query.

The components of this option have the following semantics:

Element, Attribute or Property Name Description
parent

Required. Identifies an element that can contain the latitude and longitude attributes. Use ns and name to define the namespace (if any) and local name of the element, respectively.

If multiple parents are defined, the query matches if any one of them matches. This component can have array value in JSON.

lat

Required. Identifies the attribute of parent that contains the latitude value. Use ns and name to define the namespace (if any) and local name of the element, respectively.

If multiple elements are defined, the query matches if any one of them matches. However, only the first matching latitude attribute in any point instance is checked. This component can have array value in JSON.

lon

Required. Identifies the attribute of parent that contains the longitude value. Use ns and name to define the namespace (if any) and local name of the element, respectively.

If multiple elements are defined, the query matches if any one of them matches. However, only the first matching longitude attribute in any point instance is checked. This component can have array value in JSON.

heatmap A model of a two-dimensional grid, used to categorize data along two dimensions for geospatial faceting. For details, see heatmap.
facet-option Specify options to apply when generating facets. You can only include facet options when there is a heatmap. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. For details, see Facet Options.
geo-option Specify options that customize the constraint, such as whether or not to include boundaries. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <geo-option>score-function=linear</geo-option> in XML, or "geo-option": ["score-function=linear"] in JSON. For details, see Geospatial Point Query Options.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
Examples

The following example defines a geospatial element attribute pair constraint named my-geo-attr-pair. Facets will be generated for the constraint, using the region defined in the heatmap.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-attr-pair">
    <geo-attr-pair>
      <parent ns="ns1" name="my-elem"/>
      <lat ns="ns2" name="attr1"/>
      <lon ns="ns2" name="attr2"/>
      <facet-option>empties</facet-option>
      <heatmap s="23.2" w="-118.3" n="23.3" e="-118.2" 
               latdivs="4" londivs="4"/>
    </geo-attr-pair>
  </constraint>
</options>
JSON
{"options":{
  "constraint": [{
    "name": "my-geo-attr-pair",
    "geo-attr-pair": {
      "parent": { "ns": "ns1", "name": "my-elem" },
      "lat": { "ns": "ns2", "name": "attr1" },
      "lon": { "ns": "ns3", "name": "attr2" },
      "facet-option": [ "empties" ],
      "heatmap": {
        "s": 23.2, "w": -118.3, "n": 23.3, "e": -118.2,
        "latdivs": 4, "londivs": 4
      }
    }
  }]
}}
See Also

For more details on using this option, see the following topics:

geo-elem

A component of a constraint option that models a geospatial index with coordinates stored in a single XML element. That is, geospatial data with the following structure. The specification of a parent element is optional.

<parent>
  <elem>lat-lon-values</elem>
</parent>

For similar JSON data, use geo-json-property.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-elem>
  <parent ns="namespace" name="elemName" />
  <element ns="namespace" name="elemName" />
  <facet-option>option</facet-option>
  <heatmap>heatmap descriptor</heatmap>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
  <weight>double</weight>
</geo-elem>
"geo-attr-pair": {
  "parent": [{
    "ns": "namespace",
    "name": "elemName",
  }],
  "element": [{
    "ns": "namespace",
    "name": "elemName",
  }],
  "facet-option": [ option ],
  "heatmap": {heatmap desc},
  "geo-option": [ option ],
  "fragment-scope": "scope",
  "weight": double
}
Component Description

By default coordinates are stored as (latitude,longitude) points. To reverse the coordinate order, add the geo-option "long-lat-point" to the query options configuration. For more details, see cts:element-geospatial-query.

The components of this option have the following semantics:

Element, Attribute or Property Name Description
parent

Optional. Identifies an element that can contain the latitude and longitude elements. Use ns and name to define the namespace (if any) and local name of the element, respectively.

If multiple parents are defined, the query matches if any one of them matches. This component can have an array value in JSON, but need not if there is only one item.

element

Required. Identifies the element containing the latitude and longitude values. Use ns and name to define the namespace (if any) and local name of the element, respectively.

If multiple elements are defined, the query matches if any one of them matches. This component can have an array value in JSON, but need not if there is only one item.

heatmap A model of a two-dimensional grid, used to categorize data along two dimensions for geospatial faceting. For details, see heatmap.
facet-option Specify options to apply when generating facets. You can only include facet options when there is a heatmap. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. For details, see Facet Options.
geo-option Specify options that customize the constraint, such as whether or not to include boundaries. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <geo-option>score-function=linear</geo-option> in XML, or "geo-option": ["score-function=linear"] in JSON. For details, see Geospatial Point Query Options.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
Examples

The following example defines two geo-elem constraints, one without a parent element specification and one with a parent element specification.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-elem">
    <geo-elem> 
      <element ns="ns1" name="my-elem"/> 
      <geo-option>type=long-lat-point</geo-option>
    </geo-elem>
  </constraint>
  <constraint name="my-geo-elem-child">
    <geo-elem> 
      <parent ns="ns1" name="the-parent"/> 
      <element ns="ns1" name="the-child"/> 
      <facet-option>empties</facet-option>
      <heatmap s="23.2" w="-118.3" n="23.3" e="-118.2" 
               latdivs="4" londivs="4"/>
    </geo-elem>
  </constraint>
</options>
JSON
{"options":{
  "constraint": [
    { "name": "my-geo-elem",
      "geo-elem": {
        "element": { "ns": "ns1", "name": "my-elem" },
        "geo-option": [ "type=long-lat-point" ]
    }},
    { "name": "my-geo-elem-child",
      "geo-elem": {
        "parent": { "ns": "ns1", "name": "the-parent" },
        "element": { "ns": "ns1", "name": "the-child" },
        "facet-option": [ "empties" ],
        "heatmap": {
          "s": 23.2, "w": -118.3, "n": 23.3, "e": -118.2,
          "latdivs": 4, "londivs": 4
        }
    }}
  ]
}}
See Also

For more details on using this option, see the following topics:

geo-elem-pair

A component of a constraint option that models a geospatial index with coordinates stored in 2 XML elements that are children of the same parent element. That is, geospatial data of the following form:

<parent>
  <lat>latitudeValue</lat>
  <lon>longitudeValue</lon>
</parent>

For similar JSON data, use geo-json-property-pair.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-elem-pair>
  <parent ns="namespace" name="elemName" />
  <lat ns="namespace" name="attrName" />
  <lon ns="namespace" name="attrName" />
  <facet-option>option</facet-option>
  <heatmap>heatmap descriptor</heatmap>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
  <weight>double</weight>
</geo-elem-pair>
"geo-elem-pair": {
  "parent": [{
    "ns": "namespace",
    "name": "elemName",
  }],
  "lat": [{
    "ns": "namespace",
    "name": "attrName",
  }],
  "lon": [{
    "ns": "namespace",
    "name": "attrName",
  }],
  "facet-option": [ option ],
  "heatmap": {heatmap desc},
  "geo-option": [ option ],
  "fragment-scope": "scope",
  "weight": double
}
Component Description

By default coordinates are stored as (latitude,longitude) points. To reverse the coordinate order, add the geo-option "long-lat-points" to the query options configuration. For more details, see cts:element-pair-geospatial-query.

The components of this option have the following semantics:

Element, Attribute or Property Name Description
parent

Required. Identifies an element that can contain the latitude and longitude elements. Use ns and name to define the namespace (if any) and local name of the element, respectively.

If multiple parents are defined, the query matches if any one of them matches. This component can have an array value in JSON, but need not if there is only one item.

lat

Required. Identifies the element containing the latitude value. Use ns and name to define the namespace (if any) and local name of the element, respectively.

If multiple elements are defined, the query matches if any one of them matches. However, only the first matching child in any point instance is checked. This component can have an array value in JSON, but need not if there is only one item.

lon

Required. Identifies the element containing the longitude value. Use ns and name to define the namespace (if any) and local name of the element, respectively.

If multiple elements are defined, the query matches if any one of them matches. However, only the first matching child in any point instance is checked. This component can have an array value in JSON, but need not if there is only one item.

heatmap A model of a two-dimensional grid, used to categorize data along two dimensions for geospatial faceting. For details, see heatmap.
facet-option Specify options to apply when generating facets. You can only include facet options when there is a heatmap. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. For details, see Facet Options.
geo-option Specify options that customize the constraint, such as whether or not to include boundaries. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <geo-option>score-function=linear</geo-option> in XML, or "geo-option": ["score-function=linear"] in JSON. For details, see Geospatial Point Query Options.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
Examples

The following example defines a geospatial element pair constraint named my-geo-elem-pair.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-elem-pair">
    <geo-elem-pair> 
      <parent ns="ns1" name="the-parent"/> 
      <lat ns="ns2" name="child1"/> 
      <lon ns="ns3" name="child2"/>
      <geo-option>boundaries-excluded</geo-option>
      <facet-option>empties</facet-option>
      <heatmap s="23.2" w="-118.3" n="23.3" e="-118.2" 
               latdivs="4" londivs="4"/>
    </geo-elem-pair>
  </constraint>
</options>
JSON
{"options":{
  "constraint": [{
    "name": "my-geo-elem-pair",
    "geo-elem": {
      "parent": { "ns": "ns1", "name": "the-parent" },
      "lat": { "ns": "ns2", "name": "child1" },
      "lon": { "ns": "ns3", "name": "child2" },
      "geo-option": [ "boundaries-excluded" ],
      "facet-option": [ "empties" ],
      "heatmap": {
        "s": 23.2, "w": -118.3, "n": 23.3, "e": -118.2,
        "latdivs": 4, "londivs": 4
      }
    }
  }]
}}
See Also

For more details on using this option, see the following topics:

geo-json-property

A component of a constraint option that models a geospatial index with coordinates stored in a single JSON property. That is, geospatial data with the either of the following structures:

"parentProperty": { "property": lat-lon-values }

"property": lat-lon-values

This topic has the following sections:

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-json-property>
  <parent-property>name</parent-property>
  <json-property>name</json-property>
  <facet-option>option</facet-option>
  <heatmap>heatmap descriptor</heatmap>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
  <weight>double</weight>
</geo-json-property>
"geo-json-property": {
  "parent-property": ["name"],
  "json-property": ["name"],
  "facet-option": [ option ],
  "heatmap": {heatmap desc},
  "geo-option": [ option ],
  "fragment-scope": "scope",
  "weight": double
}
Component Description

By default coordinates are stored as (latitude,longitude) points. To reverse the coordinate order, add the geo-option "long-lat-points" to the query options configuration. For more details, see cts:json-property-geospatial-query.

The components of this option have the following semantics:

Element, Attribute or Property Name Description
parent-property

Optional. Identifies the parent JSON property that can contain the latitude and longitude property.

If multiple parents are defined, the query matches if any one of them matches. This component can have an array value in JSON, but need not if there is only one item.

json-property

Required. Identifies the JSON property containing the latitude and longitude values.

If multiple properties are defined, the query matches if any one of them matches. This component can have an array value in JSON, but need not if there is only one item.

heatmap A model of a two-dimensional grid, used to categorize data along two dimensions for geospatial faceting. For details, see heatmap.
facet-option Specify options to apply when generating facets. You can only include facet options when there is a heatmap. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. For details, see Facet Options.
geo-option Specify options that customize the constraint, such as whether or not to include boundaries. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <geo-option>score-function=linear</geo-option> in XML, or "geo-option": ["score-function=linear"] in JSON. For details, see Geospatial Point Query Options.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
Examples

The following example defines two geospatial JSON property constraints, one with a parent property and one without. The second constraint also illustrates the use of the geo-option, facet-option, and heatmap components.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-json-child">
    <geo-json-property> 
      <parent-property>parent<parent-property> 
      <json-property>child</json-property> 
    </geo-json-property>
  </constraint>
  <constraint name="my-geo-json-property">
    <geo-json-property> 
      <json-property>location</json-property> 
      <geo-option>boundaries-excluded</geo-option>
      <facet-option>empties</facet-option>
      <heatmap s="23.2" w="-118.3" n="23.3" e="-118.2" 
               latdivs="4" londivs="4"/>
    </geo-json-property>
  </constraint>
</options>
JSON
{"options":{
  "constraint": [
    { "name": "my-geo-json-child",
      "geo-json-property": {
        "parent-property": "parent",
        "json-property": "child",
    }},
    { "name": "my-geo-json",
      "geo-json-property": {
        "json-property": "location",
        "geo-option": [ "boundaries-excluded" ],
        "facet-option": [ "empties" ],
        "heatmap": {
          "s": 23.2, "w": -118.3, "n": 23.3, "e": -118.2,
          "latdivs": 4, "londivs": 4
        }
    }},
  ]
}}

geo-json-property-pair

A component of a constraint option that models a geospatial index with coordinates stored in a pair of JSON properties that are children of a specific parent property. That is, geospatial data of the following form:

"parentProperty": { 
  "latProperty": lat-value,
  "lonProperty": lon-value
}

This topic has the following sections:

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-json-property-pair>
  <parent-property>name</parent-property>
  <lat-property>name</lat-property>
  <lon-property>name</lon-property>
  <facet-option>option</facet-option>
  <heatmap>heatmap descriptor</heatmap>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
  <weight>double</weight>
</geo-json-property-pair>
"geo-json-property-pair": {
  "parent-property": ["name"],
  "lat-property": ["name"],
  "lon-property": ["name"],
  "facet-option": [ option ],
  "heatmap": {heatmap desc},
  "geo-option": [ option ],
  "fragment-scope": "scope",
  "weight": double
}
Component Description

By default coordinates are stored as (latitude,longitude) points. To reverse the coordinate order, add the geo-option "long-lat-points" to the query options configuration. For more details, see cts:json-property-pair-geospatial-query.

The components of this option have the following semantics:

Element, Attribute or Property Name Description
parent-property

Required. Identifies the parent JSON property that can contain the latitude and longitude property.

If multiple parents are defined, the query matches if any one of them matches. This component can have an array value in JSON, but need not if there is only one item.

lat-property

Required. Identifies the JSON property containing the latitude.

If multiple properties are defined, the query matches if any one of them matches. However, only the first matching child in any point instance is checked. This component can have an array value in JSON, but need not if there is only one item.

lon-property

Required. Identifies the JSON property containing the longitude.

If multiple properties are defined, the query matches if any one of them matches. However, only the first matching child in any point instance is checked. This component can have an array value in JSON, but need not if there is only one item.

heatmap A model of a two-dimensional grid, used to categorize data along two dimensions for geospatial faceting. For details, see heatmap.
facet-option Specify options to apply when generating facets. You can only include facet options when there is a heatmap. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. For details, see Facet Options.
geo-option Specify options that customize the constraint, such as whether or not to include boundaries. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <geo-option>score-function=linear</geo-option> in XML, or "geo-option": ["score-function=linear"] in JSON. For details, see Geospatial Point Query Options.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
Examples

The following example defines a geospatial JSON property pair constraint, including the use of the geo-option, facet-option, and heatmap components.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-json-pair">
    <geo-json-property-pair> 
      <parent-property>parent</parent-property> 
      <lat-property>child1</lat-property> 
      <lon-property>child2</lon-property> 
      <geo-option>boundaries-excluded</geo-option>
      <facet-option>empties</facet-option>
      <heatmap s="23.2" w="-118.3" n="23.3" e="-118.2" 
               latdivs="4" londivs="4"/>
    </geo-json-property-pair>
  </constraint>
</options>
JSON
{"options":{
  "constraint": [
    { "name": "my-geo-json-pair",
      "geo-json-property": {
        "parent-property": "parent",
        "lat-property": "child1",
        "lon-property": "child2",
        "geo-option": [ "boundaries-excluded" ],
        "facet-option": [ "empties" ],
        "heatmap": {
          "s": 23.2, "w": -118.3, "n": 23.3, "e": -118.2,
          "latdivs": 4, "londivs": 4
        }
    }},
  ]
}}
See Also

For more details on using this option, see the following topics:

geo-path

A component of a constraint option that models a geospatial index with coordinates stored in an XML element, XML attribute, or JSON property described by an XPath expression.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-path>
  <path-index/>
  <facet-option>option</facet-option>
  <heatmap>heatmap descriptor</heatmap>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
  <weight>double</weight>
</geo-path>
"geo-path": {
  "path-index": [path index desc],
  "facet-option": [ option ],
  "heatmap": {heatmap desc},
  "geo-option": [ option ],
  "fragment-scope": "scope",
  "weight": double
}
Component Description

By default coordinates are stored as (latitude,longitude) points. To reverse the coordinate order, add the geo-option "long-lat-points" to the query options configuration. For more details, see cts:path-geospatial-query.

The components of this option have the following semantics:

Element, Attribute or Property Name Description
path-index

Required. A geospatial range index references to constrain by; for details, see path-index. The path should reference a point index; for region path indexes, see geo-region-path.

You can specify more than one path-index. The query matches if any one of them matches. This component can have an array value in JSON, but need not if there is only one item.

The database configuration must include a geospatial region path index based on the same path. The path expression and namespace URIs must match the index configuration; namespace prefixes do not have to match.

heatmap A model of a two-dimensional grid, used to categorize data along two dimensions for geospatial faceting. For details, see heatmap.
facet-option Specify options to apply when generating facets. You can only include facet options when there is a heatmap. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. For details, see Facet Options.
geo-option Specify options that customize the constraint, such as whether or not to include boundaries. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <geo-option>score-function=linear</geo-option> in XML, or "geo-option": ["score-function=linear"] in JSON. For details, see Geospatial Point Query Options.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
Examples

The following example illustrates a geospatial path constraint for an XML element or JSON property addressable with the XPath Expression /a/b.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-path">
    <geo-path> 
      <path-index>/a/b</path-index> 
      <geo-option>boundaries-excluded</geo-option>
      <facet-option>empties</facet-option>
      <heatmap s="23.2" w="-118.3" n="23.3" e="-118.2" 
               latdivs="4" londivs="4"/>
    </geo-path>
  </constraint>
</options>
JSON
{"options":{
  "constraint": [
    { "name": "my-geo-path",
      "geo-path": {
        "path-index": { "text" : "/a/b" },
        "geo-option": [ "boundaries-excluded" ],
        "facet-option": [ "empties" ],
        "heatmap": {
          "s": 23.2, 
          "w": -118.3, 
          "n": 23.3, 
          "e": -118.2,
          "latdivs": 4, 
          "londivs": 4
        }
    }},
  ]
}}
See Also

For more details on using this option, see the following topics:

geo-region-path

A component of a constraint option that models a geospatial region index with the location of region coordinates described by an XPath expression.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-region-path coord="coord-sys">
  <path-index/>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
  <weight>double</weight>
</geo-region-path>
"geo-region-path": {
  "path-index": [path index desc],
  "coord": "coord-sys",
  "geo-option": [ option ],
  "fragment-scope": "scope",
  "weight": double
}
Component Description

By default, coordinates are assumed to be (latitude,longitude) points. To reverse the coordinate order, add the geo-option "long-lat-points" to the query options configuration. For more details, see cts:geospatial-region-query.

The components of this option have the following semantics:

Element, Attribute or Property Name Description
path-index

Required. A geospatial region path range index descriptor for an XML element or JSON property whose contents represent a region. Define any required namespace bindings as part of the path-index element or property. For details, see path-index. For geospatial point constraints, see geo-path.

You can specify more than one path-index. The query matches if any one of them matches. This component can have an array value in JSON, but need not if there is only one item.

The database configuration must include a geospatial region path index based on the same path. The path expression and namespace URIs must match the index configuration; namespace prefixes do not have to match.

coord The coordinate system of the region path index. If present, this value must match the index configuration. If the coordinate system and precision are not explicitly specified, wgs84 (single precision) is assumed. For a list of allowed values, see the options for cts:geospatial-region-path-reference.
geo-option Specify options that customize the constraint, such as the units to be used for computations. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <geo-option>units=feet</geo-option> in XML, or "geo-option": ["units=feet"] in JSON. For details, see Geospatial Region Query Options.
fragment-scope Set a local fragment scope for this constraint to further constrain where matches occur. The local fragment scope overrides the global fragment scope. For example, a fragment-scope of properties on a range constraint enables you to facet on a value stored in a property, even if you are searching over documents. Allowed values: properties, documents (default).
weight Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to 64 and greater than or equal to -16 (between -16 and 64); weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
Examples

The following example defines a geospatial region constraint for an XML element or JSON property addressable with the XPath Expression /a/b.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-geo-region">
    <geo-region-path coord="wgs84"> 
      <path-index>/a/b</path-index> 
      <geo-option>units=feet</geo-option>
    </geo-region-path>
  </constraint>
</options>
JSON
{"options":{
  "constraint": [
    { "name": "my-geo-region",
      "geo-region-path": {
        "path-index": {"text": "/a/b"},
        "coord": "wgs84",
        "geo-option": [ "units=feet" ]
    }}
  ]
}}
See Also

For more details on using this option, see the following topics:

custom

A component of a constraint that defines a custom constraint along with the functions that implement it.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<custom facet="boolean">
  <parse apply="funcName" 
      ns="namespace"
      at="/path/to/module.xqy"/>
  <start-facet apply="funcName"
      ns="namespace"
      at="/path/to/module.xqy"/>
  <finish-facet apply="funcName"
      ns="namespace"
      at="/path/to/module.xqy"/>
  <facet-option>option</facet-option>
  <term-option>option</term-option>
</custom>
"custom": {
  "facet": boolean
  "parse": {
    "apply": "funcName",
    "ns": "namespace",
    "at": "/path/to/module.xqy"
  },
  "start-facet": {
    "apply": "funcName",
    "ns": "namespace",
    "at": "/path/to/module.xqy"
  },
  "finish-facet": {
    "apply": "funcName",
    "ns": "namespace",
    "at": "/path/to/module.xqy"
  },
  "facet-option": [ option ],
  "term-option": [ option ]
}
Component Description

The components of this option have the following semantics. The functions that implement the constraint behavior are identified by a name (apply) and optional namespace (ns), and the full path to the module that contains the function implementation (at).

Element, Attribute or Property Name Description
facet

Required. Whether or not to use this constraint for faceting.

If facet is false, you do not need to specify start-facet or finish-facet functions. If facet is true, you must specify a finish-facet function and can specify a start-facet function.

parse Required. Identifies the function used to parse the input query text or structured query.
start-facet Identifies a function that makes lexicon API calls to return the values and counts used to construct facets from this constraint. Required if facet is true and you use the concurrent facet option; optional otherwise.
finish-facet Identifies a function that accepts input from the start-facet function (if used) and constructs a facet element.
facet-option Specify options to apply when generating facets. In XML, specify multiple options by including the element multiple times. The element or array item value is of the form option=value. For example: <facet-option>limit=5</facet-option> in XML, or "facet-option": ["limit=5"] in JSON. For details, see Facet Options.
term-option Specify options to apply when generating facets. In XML, specify multiple options by including the element multiple times. If the option has a value, the element or array item value is of the form option=value. For example: <term-option>lang=en</term-option> in XML, or "term-option": ["lang=en"] in JSON. For details, see Term Options.
Examples

The following example illustrates a custom constraint that supplies parse, start-facet, and finish-facet functions. All three functions are in the namespace my-namespace, implemented in an XQuery module installed as /my/module.xqy. For a complete example that includes function implementations, see Creating a Custom Constraint.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-custom">
    <custom facet="true">
      <parse apply="my-parse-function" 
          ns="my-namespace" at="/my/module.xqy"/>
      <start-facet apply="my-start-function" 
          ns="my-namespace" at="/my/module.xqy"/>
      <finish-facet apply="my-finish-function" 
          ns="my-namespace" at="/my/module.xqy"/>
      <facet-option>concurrent</facet-option>
    </custom>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "my-custom",
      "custom": {
        "facet": true,
        "parse": {
          "apply": "my-parse-function",
          "ns": "my-namespace",
          "at": "/my/module.xqy"
        },
        "start-facet": {
          "apply": "my-start-function",
          "ns": "my-namespace",
          "at": "/my/module.xqy"
        },
        "finish-facet": {
          "apply": "my-finish-function",
          "ns": "my-namespace",
          "at": "/my/module.xqy"
        },
        "facet-option": [ "concurrent" ],
    }},
  ]
}}
See Also

For more details on using this option, see the following topics:

heatmap

A component of a geospatial constraint that models a two-dimensional grid used to categorize data along two dimensions. Use with geospatial indexes and queries to generate geospatial facets in the form of boxes, similar to the boxes created by cts:geospatial-boxes.

A heatmap can only occur as a child of a geospatial constraint, such as geo-elem or geo-json-property. A heatmap is required for generating facets from a geospatial constraint.

A heatmap is a bounding box defined by 4 cooridnates (n, w, e, s) and the number of latitudinal and longitudinal divisions in which to subdivide the region for faceting purposes. The bounding box is divided equally into the requested number of buckets. The bounding coordinates of the buckets have single point float precision.

A geospatial facets takes the form of a geospatial box with a count of the number of matches within the box. By default, each such box facet is the minimum bounding box of all points in the enclosing bucket. Use the "gridded" facet option to return the bucket coordinates defined by the lat and lon divisions instead. Empty buckets return no facets by default; use the "empties" facet option to return empty bucket boxes.

Syntax Summary

This component has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<heatmap s="double" w="double"
         n="double" e="double"
         latdivs="unsignedInt",
         londivs="unsignedInt" />
"heatmap": {
  "n": double,
  "s": double,
  "e": double,
  "w": double,
  "latdivs": unsignedInt,
  "londivs": unsignedInt
}
Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
n Required. Heatmap bounding box north coordinate.
s Required. Heatmap bounding box south coordinate.
e Required. Heatmap bounding box east coordinate.
w Required. Heatmap bounding box west coordinate.
latdivs Required. The number of latitude divisions to apply to the bounding box.
londivs Required. The number of longitude divisions to apply to the bounding box.
Examples

The following example defines a geospatial JSON property pair constraint, with latitude values in event/latitude and longitude values in event/longitude. Since the constraint defines a heatmap, geospatial facets are generated by default. Since the constraint includes the gridded facet option, the boxes generated as facets use the dimensions defined by the lat and lon divs defined by the heatmap, rather than the smallest box within each that encompasses all matching points.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="geo-pair">
    <geo-json-property-pair> 
      <parent-property>event</parent-property> 
      <lat-property>latitude</lat-property>
      <lon-property>longitude</lon-property>
      <facet-option>gridded</facet-option>
      <heatmap s="23.2" w="-118.3" n="23.3" e="-118.2" 
               latdivs="4" londivs="4"/>
    </geo-json-property-pair>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [{
    "name": "geo-pair",
    "geo-json-property-pair": {
      "parent-property": "event",
      "lat-property": "latitude",
      "lon-property": "longitude",
      "facet-option": [ "gridded" ],
      "heatmap": {
        "s": 24.0, "n": 49.0,
        "e": -67.0,"w": -125.0,
        "latdivs": 5, "londivs": 4
    }}
  }]
}}

Applied to a search, the heatmap causes the search response to include a boxes component, similar to the following:

Format Search Response Excerpt
XML
...
<boxes name="geo-pair">
  <box count="2" s="34" w="-125" n="39" e="-110.5"/>
  <box count="12" s="34" w="-110.5" n="39" e="-96"/>
</boxes>
...
JSON
...
"facets": {
  "geo-pair": {
    "boxes": [
      { "count": 2,
        "s": 34, "w": -125,
        "n": 39, "e": -110.5
      },
      { "count": 12,
        "s": 34, "w": -110.5,
        "n": 39, "e": -96
      }
    ]
...
See Also

For more details on using this option, see the following topics:

bucket

A component of a range constraint that defines a range of static values within the constraint that can be used in range query expressions and for generating facets. For dynamic value ranges, refer to computed-bucket.

Values assigned to a bucket meet the following criteria:

ge <= value < lt

Where ge and lt represent the "ge" and "lt" values specified in the bucket descriptor.

Syntax Summary

This component has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API. The bucket definition must contain either a lt or ge value and may contain both.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<bucket name="name" 
    ge="value" lt="value">
  displayLabel
</bucket>
"bucket": [{
  "name": "name",
  "label": "displayLabel",
  "lt": value,
  "ge": value
}]
Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
name Required. The bucket identifier. The name should be unique within the context of the enclosing constraint. The bucket name can be used in string query terms to represent values that fall into the bucket. For details, see Examples.

label (JSON)

fn:data() (XML)

Text that can be used to label the bucket when displaying facets. In XML, this is the text data contained in the <bucket/> element. Optional. The display label has no functional use in searches. If present, it is returned in facets so that applications can use it for display purposes.
lt The upper bound for values assigned to this bucket. Optional, but a bucket must include at least one boundary value. Values assigned to this bucket must be less than this value. Must be an atomic value.
ge The lower bound for values assigned to this bucket. Optional, but a bucket must include at least one boundary value. Value assigned to this bucket must be greater than or equal to this value. Must be an atomic value.
Examples

The following example defines a path range constraint that includes 3 buckets for faceting, corresponding to matches in the ranges (x < 5), (5 <= x < 10), and (10 <= x < 15). For display purposes, these buckets are labeled less than 5, 5 to 9, and 10 to 15.

You can use the bucket names in string query range expressions. For example, a string search for pindex:low finds values less than 5 in nodes with the path /Employee/fn.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="pindex">
    <range type="xs:string" facet="true">
      <path-index>/Employee/fn</path-index>
      <bucket name="low" lt="5">less than 5</bucket>
      <bucket name="medium" lt="10" ge="5">5 to 9</bucket>
      <bucket name="high" lt="15" ge="10">10 to 15</bucket>
    </range>
  </constraint>
</options>
JSON
{"options": {
  "constraint": [{
    "name": "pindex",
    "range": {
      "type": "xs:string",
      "facet": true,
      "path-index": {"text": "/Employee/fn"},
      "bucket": [
        { "name": "low",
          "lt": "5",
          "label": "less than 5"
        },
        { "name": "medium",
          "ge": "5",
          "lt": "10",
          "label": "5 to 9"
        },
        { "name": "high",
          "ge": "10",
          "lt": "15",
          "label": "10 to 15"
        }
      ]
    }
  }]
}}
See Also

For more details on using this option, see the following topics:

computed-bucket

A component of a range constraint that defines a range of dynamic values within the constraint that can be used in range query expressions and for generating facets. For static value ranges, refer to bucket.

Values assigned to a given computed bucket meet the following criteria:

(anchor + ge) <= value < (anchor + lt)

Where anchor, ge, and lt are values specified in the bucket descriptor.

Syntax Summary

This component has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

The bucket definition must include at least one of (ge, lt) and may include both. You must include at least one anchor value. The anchor value can be shared by both boundaries or be boundary-specific. For example, if the bucket definition includes a lt value, then it must include either an anchor or lt-anchor value.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<computed-bucket name="name" 
    ge="value" lt="value">
    anchor="anchorValue"
    lt-anchor="anchorValue"
    ge-anchor="anchorValue"
  displayLabel
</computed-bucket>
"computed-bucket": [{
  "name": "name",
  "label": "displayLabel",
  "lt": value,
  "ge": value,
  "anchor": "anchorValue",
  "lt-anchor": "anchorValue",
  "gt-anchor": "anchorValue"
}]
Component Description

The components of this option have the following semantics.

Element, Attribute or Property Name Description
name Required. The bucket identifier. The name should be unique within the context of the enclosing constraint. The bucket name can be used in string query terms to represent values that fall into the bucket. For details, see Examples.

label (JSON)

data() (XML)

Text that can be used to label the bucket when displaying facets. In XML, this is the text data contained in the <bucket/> element. Optional. The display label has no functional use in searches. If present, it is returned in facets so that applications can use it for display purposes.
lt The upper bound for values assigned to this bucket. Optional, but a bucket must include at least one boundary definition. Values assigned to this bucket must be less than this value. Must be an atomic value.
ge The lower bound for values assigned to this bucket. Optional, but a bucket must include at least one boundary definition. Value assigned to this bucket must be greater than or equal to this value. Must be an atomic value.
anchor A dynamic anchor literal value for the bucket. The bucket bounds are relative to this dynamic value. Optional if you include a boundary-specific anchor (lt-anchor, ge-anchor) for the included boundary values. Allowed values: now, start-of-day, start-of-month, start-of-year.
lt-anchor Overrides anchor for computing the bucket upper bound. Optional. Allowed values: now, start-of-day, start-of-month, start-of-year.
ge-anchor Overrides anchor for computing the bucket lower bound. Optional. Allowed values: now, start-of-day, start-of-month, start-of-year.
Examples

The following example defines an element range constraint on xs:dateTime values that includes 4 buckets, corresponding to matches for the values in dynamic ranges relative to now.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="made">
    <range type="xs:dateTime">
      <element ns="http://example.com" name="manufactured"/>
      <computed-bucket name="today" ge="P0D" lt="P1D"
            anchor="now">Today</computed-bucket>
      <computed-bucket name="30-days" ge="-P30D" lt="P1D"
            anchor="now">Last 30 days</computed-bucket>
      <computed-bucket name="60-days" ge="-P60D" lt="P1D"
            anchor="now">Last 60 Days</computed-bucket>
      <computed-bucket name="year" ge="-P1Y" lt="P1D"
            anchor="now">Last Year</computed-bucket>
    </range>
  </constraint>
</options>
JSON
{ "options": {
    "constraint": [{
      "name": "made",
      "range": {
        "type": "xs:dateTime",
        "element": {
          "ns": "http://example.com",
          "name": "manufactured"
        },
        "computed-bucket": [
          { "name": "today",
            "ge": "P0D",
            "lt": "P1D",
            "anchor": "now",
            "label": "Today"
          },
          { "name": "30-days",
            "ge": "-P30D",
            "lt": "P1D",
            "anchor": "now",
            "label": "Last 30 days"
          },
          { "name": "60-days",
            "ge": "-P60D",
            "lt": "P1D",
            "anchor": "now",
            "label": "Last 60 Days"
          },
          { "name": "year",
            "ge": "-P1Y",
            "lt": "P1D",
            "anchor": "now",
            "label": "Last Year"
          }
        ]
      }
  }]
}}
See Also

For more details on using this option, see the following topics:

path-index

This component identifies a path range index for use in a constraint definition.

Syntax Summary

This component has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<path-index xmlns:nsPrefix="nsURI">
  pathExpression
</path-index>
"path-index": {
  "text": "pathExpression"
  "namespaces": {
    "nsPrefix": "nsURI"
  }
}
Component Description

In XML, specify the XPath expression as the path-index element value. Define any namespace prefix bindings used in the path expression as xmlns attributes of the path-index element.

In JSON, specify the XPath expression as the value of the text property. Define any namespace prefix bindings used in the path expression in the namespaces property. The value of a path-index can be an array in contexts where you can specify multiple path index references.

The database configuration must include a corresponding path range index.

The path expression is limited to the subset of XPath that can be used to define a path range index. For details, see Path Field and Path-Based Range Index Configuration in XQuery and XSLT Reference Guide.

Examples

The following option defines a path index based range constraint and a path index based values specification. The range constraint references two path indexes, one of which uses namespace prefixes. Path range indexes corresponding to the paths /data/a and /ns1:data/ns2:b must exist.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="myPathConstraint">
    <range type="xs:int">
      <path-index>/data/a</path-index>
      <path-index xmlns:ns1="/my/ns1"
        xmlns:ns2="/my/ns2">/ns1:data/ns2:b</path-index>
    </range>
  </constraint>
  <values name="myValuesSpec">
    <range type="xs:int">
      <path-index>/data/a</path-index>
    </range>
  </values>
</options>
JSON
{ "options": {
    "constraint": [ {
      "name": "myPathConstraint",
      "range": {
        "type": "xs:int",
        "path-index": [
          { "text": "/data/a" },
          { "text": "/ns1:data/ns2:b",
            "namespaces": {
              "ns1": "/my/ns1",
              "ns2": "/my/ns2"
            }
          }
        ]
      }
    } ],
    "values": [
      { "name": "myValuesSpec",
        "range": {
          "type": "xs:int",
          "path-index": { "text": "/data/a" }
        }
      }
    ]
} }
See Also

For more details on using this option, see the following topics:

debug

Whether or not to enable debug mode during a search or lexicon query. Allowed values: true, false (default). When debug mode is enabled, additional report elements are included in the search results summary.

The following example enables debug mode.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <debug>true</debug>
</options>
JSON
{"options": {
  "debug": true
}}

default-suggestion-source

This option defines a constraint source for generating suggestions for naked terms with search:suggest. Suggestions are often used for type-ahead suggestions in a search user interface. For terms qualified by a constraint prefix, such as tag:value, use the suggestion-source option. For more details, see default-suggestion-source Option in the Search Developer's Guide.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

Either use ref to specify the name of a constraint defined elsewhere in the in-scope options, or omit ref and define a single range, word, or collection constraint or word lexicon.

Your options can only include one default suggestion source.

The use of word-lexicon (the database-wide word lexicon) is not recommended as best practice; collection and range lexicons yield the best performance.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<default-suggestion-source ref="constraint">
  <range/>
  <word/>
  <collection/>
  <word-lexicon collation="collURI">
    <fragment-scope>scope</fragment-scope>
  </word-lexicon>
  <suggestion-option>option</suggestion-option>
</default-suggestion-source>
"default-suggestion-source" : {
  "ref": "constraintName",
  "range": { constraint defn },
  "word": { constraint defn },
  "collection": {constr. defn},
  "word-lexicon": {
    "collation": "collURI",
    "fragment-scope": "scope"
  },
  "suggestion-option": [option]
}

Component Description

The components of this option have the following semantics. Note that the range, word, collection, and word-lexicon components are mutually exclusive of each other.

Element, Attribute or Property Name Description
ref
The name of a constraint defined in the same set of query options. Optional. If a ref value is present and a matching constraint exists, that constraint takes precedence over any range, word, collection or word-lexicon defined within this option.
range
Defines a range constraint that limits suggestions to values that match this constraint.
word
Defines a word constraint that limits suggestions to words that match this constraint.
collection
Defines a collection constraint that limits suggestions to collection names. If a prefix is present on the constraint definition, constrain suggestions to collection names with the given prefix.
word-lexicon
Limit suggestions to words found in the word lexicon.
suggestion-option
Query options to use in generating suggestions. For details, see Suggestion Options.

Examples

The following example constrains suggestions for naked terms to those values in the XML element (or JSON property, in the JSON example) with the name beast. The constraint is defined external to the default-suggestion-source. A range index must be configured on beast. If you request suggestions for the partial search term an, the animal: constraint prefix is also included in the suggestions because constraint names are always included.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="animal">
   <range type="xs:string">
      <element name="beast"/>
   </range>
 </constraint>
 <default-suggestion-source ref="animal"/>
</options>
JSON
{"options": {
  "constraint": [{
    "name": "animal",
    "range": {
      "type": "xs:string",
      "json-property": "beast"
  }}],
  "default-suggestion-source" : {
    "ref": "animal"
  }
}}

The following example has the same effect as the previous one, but the constraint is defined inside the default-suggestion-source.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
 <default-suggestion-source>
   <range type="xs:string">
      <element name="beast"/>
   </range>
 </default-suggestion-source>
</options>
JSON
{"options": {
  "default-suggestion-source" : {
    "range": {
      "type": "xs:string",
      "json-property": "beast"
  }}
}}

The following example generates suggestions from collection names with the prefix /subject/. For example if you have documents in the collections "/subject/math" and "/subject/science" and you request suggestions for the partial query text sc, then science is returned as a suggestion.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
 <default-suggestion-source>
   <collection prefix="/subject/" />
 </default-suggestion-source>
</options>
JSON
{"options": {
  "default-suggestion-source" : {
    "collection": { "prefix": "/subject/" }
  }
}}

extract-document-data

Use extract-document-data to select one or more XML elements, XML attributes, or JSON properties from each matching document to return in the results of a document search. Selection is via an absolute XPath expression. The XPath expression in extract-path is limited to a subset of XPath; for details, see Restricted XPath in the XQuery and XSLT Reference Guide.

Specify the elements, attributes, or properties as absolute XPath expressions in extract-path. Use the selected property to indicate what data to return in the selected document components. If extract-path is absent or contains no path expressions, the entire content of each matching document is included in the result set.

The manner in which the extracted content is returned depends on the calling context. Using the option in the following calling context returns the extracted content inside the search result summary:

  • XQuery: search:search or search:resolve functions
  • REST Client API: GET /v1/search or POST /v1/search with an Accept header of application/json or application/xml
  • Node.js: DatabaseClient.documents.query that returns a search result summary instead of documents (queryBuilder.withOptions({categories: 'none'})) and includes a result slice with an extract clause.
  • Java: QueryManager.search returns the extracted content in the search results. Access the content using MatchDocumentSummary.getExtracted.

Using the option in the following calling contexts returns the extracted content as a sequence of documents:

  • XQuery: search:resolve-nodes
  • REST Client API: GET /v1/search or POST /v1/search with an Accept header of multipart/mixed (a multi-document read)
  • Node.js: DatabaseClient.documents.query that returns documents and includes a result slice with an extract clause.
  • Java: The DocumentPage returned by DocumentManager.search contains an extracted document instead of a full document for each match.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<extract-document-data selected=value>
  <extract-path xmlns:pfx="nsURI">
    abs-xpath-expr
  </extract-path>
</extract-document-data>
"extract-document-data": {
  "selected": value,
  "extract-path": [ abs-xpath-expr ]
}

Component Description

The components of this option have the following semantics. Setting selected to all or failing to specify at least one extract-path XPath expression means to extract the entire document.

Element, Attribute or Property Name Description
selected

How to handle the content selected by extract-path. Allowed values:

  • include (default): Include the targeted item(s) in the results.
  • include-with-ancestors: Include the targeted item(s) and all containing ancestors.
  • exclude: Include everything except the targeted item(s).
  • all: Include the entire document

For examples of using each setting, see Extracting a Portion of Matching Documents in the Search Developer's Guide.

extract-path

Optional. The absolute XPath expression of an XML element, XML element attribute, or JSON property that is a target for extraction. You can specify multiple paths.

The path expressions are limited to a subset of XPath. For details, see The extract-document-data Query Option in the XQuery and XSLT Reference Guide.

If a path requires namespace prefixes, define the binding on the extract-path XML element, or predefine the binding using a capability such as the REST Client API method PUT /v1/config/namespaces or Java Client API NamespaceManager interface.

Examples

The following example targets two items for extraction with the XPath expressions /my:location and /who/userName. Since selected is include, just these elements (or JSON properties) will be include in the extraction results.

A namespace binding is required for /my:location. In XML options, the binding can be specified on the enclosing extract-path, as shown below. When defining options using JSON or when using an API that does not provide this level of control, you must predefine the namespace binding.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <extract-document-data selected="include">
    <extract-path xmlns:my="/my/namespace">/my:location</extract-path>
    <extract-path>/who/userName</extract-path>
  </extract-document-data>
</options>
JSON
{"options": {
  "extract-document-data": {
    selected: "include",
    extract-path: [ "/my:location", "/who/userName" ]
  }
} }

forest

This option specifies forests to which a search or lexicon query will be constrained. Identify each forest by an unsigned long forest id. If no forest ids are specified, all forests in the database are searched, which is the default behavior.

In the JSON representation, represent the forest ids as a strings because forest ids can exceed the maximum number value supported by JSON.

The following example limits the search to two forests.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <forest>13081837393370312889</forest>
  <forest>13081837393370234811</forest>
</options>
JSON
{"options": {
  "forest": ["13081837393370312889","13081837393370234811"]
}}

For additional examples, see cts:search.

fragment-scope

This option controls the global fragment scope over which to search. The global scope applies to what the search returns (that is, if it returns results from document fragments or from property fragments) and is inherited by any constraints that do not explicitly override the fragment-scope.

Allowed values: properties, documents (default)

You can override the global fragment scope by setting a local fragment scope inside a constraint or term definition. For example, a fragment-scope of properties on a range constraint enables faceting on a value stored in a property, even if you are searching over documents.

For details, see Fragment Scope Option.

The following example sets the global fragment scope to properties.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <fragment-scope>properties</fragment-scope>
</options>
JSON
{"options": {
  "fragment-scope": "properties"
}}

grammar

Use of this option for grammar customization is deprecated as of MarkLogic 9. You should use a 3rd party library if you require a custom string query grammar. For details, see Search API Grammar Customization Deprecated in the Release Notes.

The wrapper element for a custom search grammar definition. The default grammar defines "Google-style" parsing; for details, see The Default String Query Grammar.

See the following topics for a detailed description of the starter and joiner components of a grammar.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<grammar>
  <quotation>quoteChar</quotation>
  <implicit options=">ctsQuery</implicit>
  <starter/>
  <joiner/>
</grammar>
"grammar": {
  "quotation": "quoteChar",
  "implict": "ctsQuery",
  "starter": [...],
  "joiner": [...]
}

Component Description

The components of this option have the following semantics. The grammar should contain at least one implicit, starter, or joiner. If the grammar is empty, then query text is parsed according to the term options.

Element, Attribute or Property Name Description
quotation The string to use to delimit the start and end of a phrase. You cannot specify a search that includes quotation character. For example, in the default grammar, you cannot search for a double quote (") because this is the quotation character.
implicit A serialized cts:query used to join two search terms when they are not separated by an explicit operator. By default, the Search API uses a cts:and-query,. For example, in the default grammar, cat dog is equivalent to cat AND dog. Your grammar should include at most one implicit component.
starter Define a unary operator or a pair of group delimiters. For example, the default grammar includes a starter for the unary operator - that is bound to cts:not-query and a starter for ( and ) for grouping. For details, see starter. Your grammar can include zero or more starters.
joiner Define a binary operator that joins two query expressions. For example, the default grammar defines joiners such as AND, OR, and LT. For details, see joiner. Your grammar can include zero or more joiners.

Examples

The following example is a subset of the default grammar. You can obtain the complete grammar by calling search:get-default-options.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <grammar>
<quotation>"</quotation>
  <implicit>
    <cts:and-query strength="20" xmlns:cts="http://marklogic.com/cts"/>
  </implicit>
  <starter strength="30" apply="grouping" delimiter=")">(</starter>
  <starter strength="40" apply="prefix" element="cts:not-query">-</starter>
  <joiner strength="10" apply="infix" element="cts:or-query"
     tokenize="word">OR</joiner>
  <joiner strength="20" apply="infix" element="cts:and-query"
     tokenize="word">AND</joiner>
  </grammar>
</options>
JSON
{"options": {
  "grammar": {
    "starter": [
      {
        "strength": 30,
        "apply": "grouping",
        "delimiter": ")",
        "label": "("
      }, 
      {
        "strength": 40,
        "apply": "prefix",
        "element": "cts:not-query",
        "label": "-"
      }, 
    ],
    "joiner": [ {
      "strength": 10,
      "apply": "infix",
      "element": "cts:or-query",
      "tokenize": "word",
      "label": "OR"
    } ],
    "quotation": "\"",
    "implicit": "<cts:and-query strength=\"20\" xmlns=\"http://marklogic.com/appservices/search\" xmlns:cts=\"http://marklogic.com/cts\"/>"
    }
  }
} 

starter

A starter is a child of a grammar option that defines a unary operator or a group operator. For more details, see grammar.

Use the apply-at-ns pattern described in Search Customization Via Options and Extensions in Search Developer's Guide to define the XQuery library function that implements the starter. The function must produce a cts:query element of the type named by element.

Syntax Summary

The starter component of a grammar option has the following structure. The operator token is the text data of the starter element in XML and the value of the label property in JSON. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<starter strength="int"
         apply="funcName"
         ns="namespaceURI"
         at="modulePath"
         element="qName"
         options="optList"
         delimiter="delimChar"
         tokenize="value">
  opToken
</starter>
"starter": [{
  "label": "opToken",
  "strength": number,
  "apply": "funcName",
  "ns": "namespaceURI",
  "at": "modulePath",
  "element": "qName",
  "options": "optList",
  "tokenize": "value",
  "delimiter": "delimChar",
}]
Component Description

The starter component of a grammar option has the following semantics:

Element, Attribute or Property Name Description

fn:data() (XML)

label (JSON)

Required. The starter operator token. For example, the default grammar includes a starter with the minus sign (-) as the operator, which enables query text such as -cat.

If defining a pair of grouping delimiters such as ( and ), place set this component to the group start delimiter (() and set delimiter to the group end deliminter ()).

strength Required. The order of precedence of this starter relative to other operators in this grammar. Higher strength tokens or groups are processed before lower ones.
apply The local-name of a function that parses expressions using this starter. This can be one of the functions pre-defined by the default grammar or a custom function; for a custom function, you must also include ns and at values.
ns The XQuery module that contains the apply function, if using a user-defined function.
at The module from which the apply function is imported, if using a user-defined function.
element A cts:query element name that identifies the type of cts:query element produced by the parsing function. For example, the default grammar defines a negation starter using the minus sign, which produces a cts:not-query.
options A space-separated list of options that are passed through to the underlying apply function.
tokenize Allowed values: word or default.
delimiter When defining a pair of grouping deliminters, the string to use as a the delimiter of the end of the grouping. For example, if defining ( and ) as group delimiters, set delimiter to ).
Examples

The following example shows the definition of the - (not) unary operator and ( ) grouping operator defined by the default grammar.

Format Example
XML
<starter strength="30" apply="grouping" delimiter=")">(</starter>
<starter strength="40" apply="prefix"
  element="cts:not-query">-</starter>
JSON
"starter": [
  { "strength": 30,
    "apply": "grouping",
    "delimiter": ")",
    "label": "("
  },
  { "strength": 40,
    "apply": "prefix",
    "element": "cts:not-query",
    "label": "-"
  }
]

joiner

A joiner is a child of a grammar option that defines a binary operator. For more details, see grammar.

Use the apply-at-ns pattern described in Search Customization Via Options and Extensions in Search Developer's Guide to define the XQuery library function that implements the joiner. The function must produce a cts:query element of the type named by element.

Syntax Summary

The joiner component of a grammar option has the following structure. The operator token is the text data of the starter element in XML and the value of the label property in JSON. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<joiner strength="int"
         apply="funcName"
         ns="namespaceURI"
         at="modulePath"
         element="qName"
         options="optList"
         compare="operator"
         consume="nTokens"
         tokenize="value">
  opToken
</joiner>
"joiner": [{
  "label": "opToken",
  "strength": number,
  "apply": "funcName",
  "ns": "namespaceURI",
  "at": "modulePath",
  "element": "qName",
  "options": "optList",
  "compare": "operator",
  "consume": nTokens
  "tokenize": "value"
}]
Component Description

The joiner component of a grammar option have the following semantics:

Element, Attribute or Property Name Description

fn:data() (XML)

label (JSON)

Required. The joiner operator token. For example, the default grammar includes a joiner with AND as the operator, which enables query text such as cat AND dog.
strength Required. The order of precedence of this operator relative to other operators in this grammar. Higher strength tokens or groups are processed before lower ones.
apply The local-name of a function that parses expressions using this operator. This can be one of the functions pre-defined by the default grammar or a custom function; for a custom function, you must also include ns and at values.
ns The XQuery module that contains the apply function, if using a user-defined function.
at The module from which the apply function is imported, if using a user-defined function.
element A cts:query element name that identifies the type of cts:query element produced by the parsing function. For example, the default grammar defines AND as a joiner that produces a cts:and-query.
options A space-separated list of options that are passed through to the underlying apply function.
compare The range query comparison operator to apply when defining a relational operator. Allowed values: LT, LE, GT, GE, NE, EQ.
consume The number of tokens to consume when parsing the right operand of the joiner. For example, the near/ operator defined by the default grammar consumes one token when parsing A NEAR B, but it consumes two tokens when parsing the expression A NEAR/3 B (th count, 3, and B).
tokenize Allowed values: word or default.
Examples

The following examples from the default grammar define the AND and LT operators. For more examples, see the default grammar.

Format Example
XML
joiner strength="20" apply="infix" element="cts:and-query"
        tokenize="word">AND</joiner>
<joiner strength="50" apply="constraint" compare="LT"
        tokenize="word">LT</joiner>
JSON
"joiner": [
  { "strength": 20,
    "apply": "infix",
    "element": "cts:and-query",
    "tokenize": "word",
    "label": "label"
  },
  { "strength": 50,
    "apply": "constraint",
    "compare": "LT",
    "tokenize": "word",
    "label": "LT"
  },
]

operator

A named wrapper for one or more state elements, each representing a unique run-time configuration option. An operator defines a set of options that can be applied at query time when opName:state is encountered in the query text.

For example, if an operator with the name "sort" is defined, then the query text sort:foo will select the "foo" of the sort operator at query runtime, using the options specified on that state element. Options affecting query parsing (such as constraint, grammar, term, empty) may not be configured via operators.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<operator name="opName">
  <state name="stateName">
    <additional-query>
      ctsQuery
    </additional-query>
    <debug>boolean</debug>
    <forest>forestId</forest>
    <page-length>int</page-length>
    <quality-weight>double</quality-weight>
    <search-option>option</search-option>
    <searchable-expression>
      pathExpr
    </searchable-expression>
    <sort-order/>
    <transform-results/>
  </state>
</operator>
"operator: {
  "name": "opName",
  "state": [ {
    "name": "stateName",
    "additional-query": "ctsQuery",
    "debug": boolean,
    "forest": forestId,
    "page-length": integer,
    "quality-weight": double,
    "search-option": [ "option" ],
    "searchable-expression":
       "pathExpr",
    "sort-order": [ ... ],
    "transform-results": ...
  } ]
}

Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
name Required. The name of this operator. The name must be unique across all operators and constraints in scope.
state One or more state definitions for the operator.
state/name Required. The name of this state.
state/additional-query A cts:query to evaluate when the operator is in this state.
state/debug Whether or not to enable debug logging. Default: false.
state/forest A forest id. This must be an unsigned long value.
state/page-length The page length into which results should be chunked.
state/quality-weight Specifies a weighting factor to use in the query. The default value is 1.0.
state/search-option Search options passed to the additional-query. You can include zero or more options.
state/searchable-expression Specifies an XPath expression to search. For details, see searchable-expression.
state/sort-order Specifies a sort order to apply. For details, see sort-order.
state/transform-results Define a transformation to use when applying this state. For details, see transform-results.

Examples

The following example defines 2 operators, named sort and page-length. The sort operator has 2 states, down and up. The nresults operator has 2 states, few and many. This allows you, for example, to include a search term of the form sort:up to request results in ascending order. Similarly, a search term of the form nresults:many cause 50 matches to be returned.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <operator name="sort">
    <state name="up">
      <sort-order>
        <direction>ascending</direction>
        <score/>
      </sort-order>
    </state>
    <state name="down">
      <sort-order>
        <direction>descending</direction>
        <score/>
      </sort-order>
    </state>
  </operator>
  <operator name="nresults">
    <state name="few">
      <page-length>10</page-length>
    </state>
    <state name="many">
      <page-length>50</page-length>
    </state>
  </operator>
</options>
JSON
{"options": {
  "operator": [
    { "name": "sort",
      "state": [
        { "name": "down",
          "sort-order": [{
            "direction": "descending",
            "score-order": null
          }]
        },
        { "name": "up",
          "sort-order": [{
            "direction": "ascending",
            "score-order": null
          }]
        }
      ]
    },
    { "name": "nresults",
      "state": [
        { "name": "few",
          "page-length": 10
        },
        { "name": "many",
          "page-length": 50
        }
      ]
    }]
} }

See Also

For more details on using this option, see the following topics:

page-length

This option specifies the number of search results to include in each page of returned results. The default value is 10.

The following example sets the page length to 20.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <page-length>20</page-length>
</options>
JSON
{"options": {
  "page-length": 20
}}

quality-weight

This option specifies a document quality weight to use when computing scores. The value should be a double. The default value is 1.0.

The following example sets the quality weight to 2.0.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <quality-weight>2.0</quality-weight>
</options>
JSON
{"options": {
  "quality-weight": 2.0
}}

result-decorator

Defines a custom search result decorator XQuery function that is used to decorate each search result with additional information. Before performing a search that uses this option, the XQuery library module containing the function must be installed in the App Server modules database at the XPath given by at.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<result-decorator apply="funcName"
    ns="namespaceURI"
    at="modulePath" />
"result-decorator": {
  "apply": "funcName",
  "ns": "namespaceURI",
  "at": "modulePath"
}

Component Description

The components of this option have the following semantics. The module identified by the option must be installed under the App Server root or int he modules database at the location identified by the at XPath expression.

Element, Attribute or Property Name Description
apply The local name of a custom result decorator function. You must also specify ns and at.
ns The namespace of the function in apply. This must match the namespace declaration of the XQuery library module containing the apply function.
at The XPath to the XQuery library module containing the apply function.

Examples

The following example specifies the function decorator in the XQuery library module located at /ext/my.domain/decorator.xqy. assuming the module namespace is http://marklogic.com/example/my-lib.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <result-decorator apply="decorator"
      ns="http://marklogic.com/example/my-lib"
      at="/ext/my.domain/decorator.xqy"/>
</options>
JSON
{"options": {
  "result-decorator": {
    "apply": "decorator",
    "ns": "http://marklogic.com/example/my-lib",
    "at": "/ext/my.domain/decorator.xqy"
  }
} }

return-aggregates

This option specifies whether or not to include the result of running a builtin or user-defined aggregate function in the result of a lexicon query, such as search:values. Aggregates are not applicable to document searches (search:search).

Default: false (do not include). This option applies only to queries against values or tuples.

The following example sets the option to true.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-aggregates>true</return-aggregates>
</options>
JSON
{"options": {
  "return-aggregates": true
}}

For details, see the following topics:

return-constraints

This option specifies whether or not to include original constraint definitions in the result summary (search:response) of a document search. Default: false (do not include). For details, see Return Options.

The following example sets the option to true.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-constraints>true</return-constraints>
</options>
JSON
{"options": {
  "return-constraints": true
}}

return-facets

This option specifies whether or not to include facets in the result summary (search:response) from a document search. Default: true (include).

The following example sets the option to false.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-facets>false</return-facets>
</options>
JSON
{"options": {
  "return-facets": false
}}

For details, see the following topics:

return-frequencies

This option specifies whether or not to include term frequencies in the search result summary for a values or tuples lexicon query. Default: true (include).

For details, see Return Options.

The following example sets the option to false.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-frequencies>false</return-frequencies>
</options>
JSON
{"options": {
  "return-frequencies": false
}}

return-metrics

This option specifies whether or not to include performance metrics in the search result summary (search:response). Default: true (include).

For details, see Return Options.

The following example sets the option to false.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-metrics>false</return-metrics>
</options>
JSON
{"options": {
  "return-metrics": false
}}

return-plan

This option specifies whether or not to include a query plan in the result summary (search:response) of a document search. Default: false (do not include). The query plan enables you to examine the evaluation plan for a query, which can aid query tuning. For example, you can determine whether or not your range indexes are being used as you expect them to be.

For details, see Return Options and xdmp:plan.

The following example sets the option to true.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-plan>true</return-plan>
</options>
JSON
{"options": {
  "return-plan": true
}}

return-qtext

This option specifies whether or not to include the original query text in the search result summary (search:response). Default: true (include).

For details, see Return Options.

The following example sets the option to true.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-qtext>true</return-qtext>
</options>
JSON
{"options": {
  "return-qtext": true
}}

return-query

This option specifies whether or not to include the final representation of your query as a serialized cts:query in the result summary (search:response) of a document search. Default: false (do not include).

For details, see Return Options.

The following example sets the option to true.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-query>true</return-query>
</options>
JSON
{"options": {
  "return-query": true
}}

return-results

This option specifies whether or not to include search result details (search:result) in the result summary (search:response) of a document search. Default: true (include). You can use the transform-results option to control the formatting of the results.

For details, see Return Options.

The following example sets the option to false.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-results>false</return-results>
</options>
JSON
{"options": {
  "return-results": false
}}

return-similar

This option specifies whether or not to include a list of similar documents in each search result in the result summary (search:response) of a document search. Default: false (do not include).

For details, see Return Options.

The following example sets the option to true.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-similar>true</return-similar>
</options>
JSON
{"options": {
  "return-similar": true
}}

return-values

This option specifies whether or not to include the index/lexicon values in the search results summary when performing a lexicon or index query, such as with search:values. Default: true (include).

For details, see Return Options.

The following example sets the option to false.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <return-values>false</return-values>
</options>
JSON
{"options": {
  "return-values": false
}}

search-option

Advanced users can use this option to pass options to the underlying cts query option. For example, use this option to pass through options such as filtered, unfiltered, and score-logtfidf. See the XQuery function cts:search for a list of possible values.

This option can appear multiple times in XML and has array value in JSON.

The following example specifies two advanced search options.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <search-option>filtered</search-option>
  <search-option>format-text</search-option>
</options>
JSON
{"options": {
  "search-option": ["filtered", "format-text"]
}}

searchable-expression

Due to security and performance considerations, beginning in MarkLogic 9.0-10, the searchable-expression property/element in query options is deprecated. Please see Search API searchable-expression Deprecated in the Release Notes for more information.

This option specifies an XPath expression to be searched when performing a document search. For example, if you specify //p, then p elements that match the search criteria are returned.

The expression must be an inline fully searchable XPath expression, and all necessary namespaces must be declared. The default value is fn:collection(), which searches all documents in the database.

This option does not affect facet results. To constrain facets, use the additional-query option.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<searchable-expression xmlns:prefix="nsURI">
  xpathExpr
</searchable-expression>
"searchable-expression": {
  "text": "xpathExpr",
  "namespaces" : {
    "prefix": "nsURI"
  }
}

Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description

fn:data() (XML)

text (JSON)

A fully searchable XPath expression. In XML, the expression is simply the text data of the searchable-expression element. If the expression uses namespace prefixes, you must define the prefixes in the option.

@xmlns:prefix (XML)

namespaces (JSON)

Define a binding between a prefix used in the searchable XPath expression and a namespace URI. In JSON, each child property of the namespaces component is of the form "prefix": "namespaceURI". In XML, define the binding using the standard xmlns attribute syntax.

Examples

The following example searches over elements addressed by the XPath expression /ex:orders/com:company.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <searchable-expression xmlns:ex="http:example.com"
        xmlns:com="http://company.com">
    /ex:orders/com:company
  </searchable-expression>
</options>
JSON
{"options": {
  "searchable-expression": {
    "text": "/ex:orders/com:company",
    "namespaces": {
      "ex": "http:example.com",
      "com": "http://company.com"
    }
  }
}}

See Also

For more details on using this option, see the following topics:

sort-order

Defines the sort order of an XML element, XML element attribute, field, or JSON property during a document search.

A set of query options can contain multiple sort-order specifiers. The first such specification is the primary sort order, the second is the secondary sort order, and so on. The default sort order is to sort by score, descending.

Syntax Summary

A sort-order option must contain exactly one element, field, or json-property child. If there is an element child it can optionally have an attribute sibling (to specify an attribute of the preceding element). Both the element and attribute must have ns and name attributes to specify the namespace and local-name of the specified element and attribute.

A sort-order option can contain at most one of the ordering specifiers confidence-order, document-order, fitness-order, quality-order, score-order, unordered, or score. Note that some of these ordering algorithms are indistinguishable from each. For example, sorting by fitness and sorting by score yield the same ordering.

The database configuration must include a range index on any XML element, XML element attribute, JSON property, or field used to control sort order.

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<sort-order type="xsType" collation="collURI"
    direction="value">
  <element ns="namespace" name="name"/>
  <attribute ns="namespace" name="name"/>
  <field name="name"/>
  <json-property>name</json-property>
  <path-index/>
  <confidence-order/>
  <document-order/>
  <fitness-order/>
  <quality-order/>
  <undordered/>
  <score-order/>
  <score/>
</sort-order>
"sort-order": {
  "type": "xsType",
  "collation" : "collURI",
  "direction" : "value",
  "element": {
    "ns": "namespace",
    "name": "name"
  },
  "attribute": {
    "ns": "namespace",
    "name": "name"
  },
  "field": {"name": "name"},
  "json-property": "name",
  "path-index": [path index desc],
  "confidence-order": null,
  "document-order": null,
  "fitness-order": null,
  "quality-order": null,
  "unordered": null,
  "score-order": null,
  "score": null
}

Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
element Identifies an XML element to which this sort order applies, or the element containing the attribute to which this sort order applies. If specifying only an element, you must set type to match the range index type of this element. If an element is present, you cannot include a field, json-property, or path-index child.
attribute Identifies the element attribute to which this sort order applies. You must set type to match the range index type of this attribute. If an attribute property is present, you cannot also specify a field, json-property, or path-index, and you must specify element.
field Identifies the field to which this sort order applies. Cannot be used with element, attribute, path-index, or json-property. You should not apply sort-order to a field that has more than one included element.
json-property Identifies the JSON property to which this sort order applies. Cannot be used with element, attribute, path-index, or field.
path-index Defines a path range index reference to which this sort order applies. For details, see path-index. Cannot be used with element, attribute, json-property, or field. The database configuration must include a corresponding path range index.
type If you are sorting by an element, an attribute, or a JSON property, you must specify a type property with a value corresponding to the range index type of that element, attribute, or property. For example, xs:string, xs:dateTime, and so on.
collation A collation URI. Optionally specify a collation when type is xs:string; otherwise, use the collation of the query.
direction Specify the sorting direction. Default: ascending, except for score, which defaults to descending. Allowed values: ascending, descending.
confidence-order Sort by confidence order, ascending. Use the direction specifier to override the default direction. For details, see Relevance Scores: Understanding and Customizing in the Search Developer's Guide. You can define at most one of the ordering specifiers confidence-order, document-order, fitness-order, quality-order, score-order, unordered, or score.
document-order Sort by document order, ascending. Use the direction specifier to override the default direction. For details, see Relevance Scores: Understanding and Customizing in the Search Developer's Guide. You can define at most one of the ordering specifiers confidence-order, document-order, fitness-order, quality-order, score-order, unordered, or score.
fitness-order Sort by fitness order, ascending. Use the direction specifier to override the default direction. For details, see Relevance Scores: Understanding and Customizing in the Search Developer's Guide. You can define at most one of the ordering specifiers confidence-order, document-order, fitness-order, quality-order, score-order, unordered, or score.
quality-order Sort by quality order, ascending. Use the direction specifier to override the default direction. For details, see Relevance Scores: Understanding and Customizing in the Search Developer's Guide. You can define at most one of the ordering specifiers confidence-order, document-order, fitness-order, quality-order, score-order, unordered, or score.
score-order Sort by score order, ascending. Use the direction specifier to override the default direction. For details, see Relevance Scores: Understanding and Customizing in the Search Developer's Guide. You can define at most one of the ordering specifiers confidence-order, document-order, fitness-order, quality-order, score-order, unordered, or score.
unordered Do not apply an ordering. For details, see Relevance Scores: Understanding and Customizing in the Search Developer's Guide. You can define at most one of the ordering specifiers confidence-order, document-order, fitness-order, quality-order, score-order, unordered, or score.
score Sort by score, descending. This selection is equivalent to using sort-order with direction set to descending. For details, see Relevance Scores: Understanding and Customizing in the Search Developer's Guide. You can define at most one of the ordering specifiers confidence-order, document-order, fitness-order, quality-order, score-order, unordered, or score.

Examples

The following example specifies a primary sort order using the element value for my-element and a secondary sort order of score descending. The database configuration must include a range index on my-element with the specified collation.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <sort-order type="xs:string" 
      collation="http://marklogic.com/collation/"
      direction="ascending">
    <element ns="my-namespace" name="my-element"/>
  </sort-order>
  <sort-order direction="ascending">
    <score/>
  </sort-order>
</options>
JSON
{"options": {
  "sort-order": [
    { "direction": "descending",
      "type": "xs:string",
      "collation": "http://marklogic.com/collation/",
      "element": {
        "name": "my-element",
        "ns": "my-namespace",
      }
    },
    { "direction": "ascending",
      "score": null
    }
  ]
} }

suggestion-source

This option defines a search term completion suggestion source for a constraint-qualified search term using search:suggest (or an equivalent operation). That is, terms of the form animal:cat. Suggestions are often used for type-ahead suggestions in a search user interface.

By default, suggestions for constraint-qualified terms are generated based on the qualifying constraint. Use this option to specify an alternative source. This option is useful when you use a named constraint for searching and facets, but you want to use a different source for type-ahead suggestions without re-parsing your search terms.

For naked terms that are unqualified by a constraint prefix, such as cat, use the default-suggestion-source option. For more details, see default-suggestion-source Option in the Search Developer's Guide.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

You must include ref, and it should refer to a named constraint defined elsewhere in your options.

The use of word-lexicon (the database-wide word lexicon) is not recommended as best practice; collection and range lexicons yield the best performance.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<suggestion-source ref="constraint">
  <range/>
  <word/>
  <collection/>
  <word-lexicon collation="collURI">
    <fragment-scope>scope</fragment-scope>
  </word-lexicon>
  <suggestion-option>option</suggestion-option>
</suggestion-source>
"suggestion-source" : [{
  "ref": "constraintName",
  "range": { constraint defn },
  "word": { constraint defn },
  "collection": {constr. defn},
  "word-lexicon": {
    "collation": "collURI",
    "fragment-scope": "scope"
  },
  "suggestion-option": [option]
}]

Component Description

The components of this option have the following semantics. Use ref to identify the constraint to override. Use range, word, collection, or word-lexicon to define the overriding suggestion source. Note that the range, word, collection, and word-lexicon components are mutually exclusive of each other.

A constraint defined within a suggestion-source can include a collation value, which specifies the collation of the value lexicon used during query evaluation. If no collation is specified, then the query uses the default collation for the context in which the query is evaluated.

Element, Attribute or Property Name Description
ref

Required. The name of the constraint overridden by this option. The named constraint must be defined elsewhere in the options.

If the option specifies only ref with no range, word, collection, or word-lexicon, then no suggestions are generated when the named constraint is applied.

range
Defines a range constraint that limits suggestions to values that match this constraint.
word
Defines a word constraint that limits suggestions to words that match this constraint.
collection
Defines a collection constraint that limits suggestions to collection names. If a prefix is present on the constraint definition, constrain suggestions to collection names with the given prefix.
word-lexicon

Limit suggestions to words found in the database-wide word lexicon.

The use of word-lexicon is not recommended as best practice; collection and range lexicons yield the best performance.

suggestion-option
Query options to use in generating suggestions. For details, see Suggestion Options.

Examples

The following options define 3 constraints (color, price, and pets), along with a suggestion-source option applicable to each. The suggestion source for color specifies suggestions matches should be case-sensitive. The suggestion source for price specifies that no suggestions should be generated from price. The suggestion source for pets specifies that suggestions should be drawn from an alternative source, rather than the collection defined by the original constraint

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="color">
    <word>
      <json-property>color</json-property>
    </word>
  </constraint>
  <suggestion-source ref="color">
    <suggestion-option>case-sensitive</suggestion-option>
  </suggestion-source>

  <constraint name="price">
    <range type="xs:unsignedInt">
      <element ns="" name="price"/>
    </range>
  </constraint>
  <suggestion-source ref="price"/>

  <constraint name="pets">
    <collection prefix="/my/collection/" facet="true" />
  </constraint>
  <suggestion-source ref="pets">
    <collection prefix="/some/collection/subset/"
  </suggestion-source>
</options>
JSON
{"options": {
  "constraint": [
    { "name": "color",
      "word": { "json-property": "color" }
    },
    { "name":  "price",
      "range": { 
        "type": "xs:unsignedInt", 
        "element": { "ns": "", "name": "price" }
      }
    },
    { "name":  "pets",
      "collection": { "prefix": "/my/collection", "facet": true}
    }
  ],
  "suggestion-source": [
    { "ref": "color", "suggestion-option": ["case-sensitive"] },
    { "ref": "price" },
    { "ref": "pets", 
      "collection": { "prefix": "/my/collcetion/subset" }
    }
  ]
} }

term

This option defines the handling of empty searches and controls options for how individual terms (that is, terms not associated with a constraint) will be represented when parsing the search terms. This option only applies to document searches and search term suggestions.

An empty search when you pass an empty query text string to search:search or an equivalent operation. To control how empty searches (that is, the empty string passed into search:search) are resolved, specify an empty child element with an apply attribute. The value of the apply attribute specifies the behavior for empty searches: a value of all-results specifies that empty searches return everything in the database, a value of no-results (the default) specifies that an empty search returns nothing.

You can also specify a default child element which determines special handling to all terms, so you can have all terms apply a set of rules such as query weighting, specifying a element or attribute value or word query to be used as a default, or specifying a constraint to be applied by default.

Include a fragment-scope element to limit the scope of term queries to document or fragment scope. The local definition overrides a global fragment scope on the enclosing options element as long as the term definition does not include a constraint definition or reference, or a custom function specification.

A custom term function has the same signature as a custom constraint function. For details about the signature, see Implementing a Structured Query parse Function.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<term apply="funcName" ns="namespaceURI"
      at="modulePath">
  <default ref="constraintName">
    <word/>
    <value/>
    <range/>
  </default>
  <empty apply="value" />
  <weight>double</weight>
  <term-option>option</term-option>
  <fragment-scope>scope</fragment-scope>
</term>
"term": {
"default": {
    "ref": "constraintName",
    "word": ...,
    "value": ...,
    "range": ...
  },
  "empty": {
    "apply": "value",
  },
  "weight": double,
  "fragment-scope": "scope"
  "apply": "funcName",
  "ns": "namespaceURI",
  "at": "modulePath"
  "term-option": [ "option" ]
}

Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
apply The local-name of a function that parses expressions using this starter. This can be one of the functions pre-defined by the default grammar or a custom function; for a custom function, you must also include ns and at values.
ns The XQuery module that contains the apply function, if using a user-defined function.
at The module from which the apply function is imported, if using a user-defined function.
default Specify default handling of naked terms. Either use ref to provide the name of a constraint defined elsewhere in the options, or define a range, value, or word constraint child to apply.
empty Specify how to resolve an empty, such as when an empty string query is passed to search:search. Set apply to either "all-results" or "no-results". Default: all-results.
weight A weighting factor to apply to individual terms. Default: 1.0.
term-option Zero or more options to apply to term matching. For details, see Term Options.
fragment-scope Specifies a local fragment scope for evaluating term. The local fragment-scope overrides any global fragment-scope. However, this local scope is ignored if the containing term definition includes a constraint definition, constraint reference, or a custom function (via apply). Allowed values: properties, documents (default).

Examples

The following example specifies that an empty search should return no results, and that terms are matched diacritic-insensitive and unwildcarded.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <term>
    <empty apply="no-results" />
    <term-option>diacritic-insensitive</term-option>
    <term-option>unwildcarded</term-option>
  </term>
<options>
JSON
{"options": {
  "term": {
    "empty": {"apply": "no-results"},
    "term-options": ["diacritic-insensitive", "unwildcarded"]
  }
}}

The following example specifies a custom term handling function.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <term apply="my-handler" ns="/my/namespace" at="/my/custom.xqy">
    <empty apply="all-results" />
  </term>
<options>
JSON
{"options": {
  "term": {
    "apply": "my-handler",
    "ns": "/my/namespace",
    "at": "/my/custom.xqy",
    "empty": {"apply": "no-results"},
  }
}}

The following example specifies that terms with no constraint qualifier should be parsed as a weighted word query on the element with QName foo:bar:

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <term>
    <default>
      <word>
        <element ns="foo" name="bar" />
        <weight>2.0</weight>
      </word>
    </default>
  </term>
<options>
JSON
{"options": {
  "term": {
    "default": {
      "word": { 
        "element": { "ns": "foo", "name": "bar" },
        "weight" 2.0
      }
    }
  }
}}

The following example specifies that a constraint defined elsewhere in the options should be applied to terms:

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="my-constraint">...</constraint>
  <term>
    <default ref="my-constraint" />
  </term>
<options>
JSON
{"options": {
  "constraint": { "name": "my-constraint", ... },
  "term": {
    "default": {
      "ref": { "my-constraint" }
    }
  }
}}

transform-results

Specifies a function to use to process a search result for the snippet output. The default is that each result is formatted using the built-in default snippetting function. For details, see Modifying Your Snippet Results.

You can also use one of the other pre-defined snippeting functions or define your own custom snippet generation function. See the description of apply in Component Description. When you define a custom function, you can pass in parameters using the param child elements or properties.

Syntax Summary

Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

When using a built-in snippeting function, this option can take one of the following forms:

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<transform-results apply="snippet">
  <preferred-matches>
    <element ns="namespace" name="elemName" />
    <json-property>name</json-property>
  </preferred-matches>
  <per-match-tokens>value</per-match-tokens>
  <max-matches>value</max-matches>
  <max-snippet-chars>value</max-snippet-chars>
</transform-results>

<transform-results apply="metadata-snippet">
  <preferred-matches>
    <element ns="namespace" name="elemName" />
    <json-property>name</json-property>
  </preferred-matches>
</transform-results>

<transform-results apply="raw" />

<transform-results apply="empty-snippet" />
"transform-results": {
  "apply": "snippet",
  "per-match-tokens": number,
  "max-matches": number,
  "max-snippet-chars": number,
  "preferred-matches": { 
    "element": [{
      "ns": "namespaceURI",
      "name": "elemName"
     }],
     "json-property": ["name"]
  }
}

"transform-results": {
  "apply": "metadata-snippet",
  "preferred-matches": { 
    "element": [{
      "ns": "namespaceURI",
      "name": "elemName"
    }],
    "json-property": ["name"]
  }
}

"transform-results": {
  "apply": "raw",
}

"transform-results": {
  "apply": "empty-snippet",
}

To use a custom snippeting function, use the following form of the option:

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<transform-results apply="customFunc"
    ns="namespaceURI" at="modulePath">
  userDefinedParams
</transform-results>
Using the built-in snippeters:
"transform-results": {
  "apply": "funcName",
  "ns": "namespaceURI",
  "at": "modulePath",
  "userDefinedParam": value
}

Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
apply The local-name of a built-in or custom function* with which to produce snippet output for a search result. The following are the builtin function names; any other value is taken to be the name of a custom snippeting function.
  • snippet (default)
  • raw: return the whole node
  • empty-snippet: return an empty snippet
  • metadata-snippet: return the snippet from the specified element in the properties document
preferred-matches When using the snippet or metadata-snippet built-in function, the snippet alogorithm looks for matches first in the specified XML element or JSON property nodes in each snippet. If no matches are found in the preferred elements and/or properties, the algorithm falls back to default content.
per-match-tokens When using the snippet built-in function, the maximum number of tokens (typically words) per matching node that surround the highlighted term(s) in the snippet. Default: 30.
max-matches When using the snippet built-in function, the maximum number of nodes containing a highlighted term that will display in the snippet. Default: 4.
max-snippet-chars When using the snippet built-in function, limit total snippet size to this many characters. Default: 200.
ns When using a custom snippeting function, the namespace URI of the containing module.
at When using a custom snippeting function, the path to the module containing the function.
userDefinedParams When using a custom snippeting function, specify parameters to pass to the custom function as additional XML elements or JSON properties on the option.

*Custom constraints, decorators, and other hooks on the Search API cannot be implemented as JavaScript MJS modules.

Examples

The following example modifies the characteristics of the default snippeting function (apply=snippet is implicit because no function is named).

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <transform-results>
    <max-matches>5</max-matches>
    <max-snippet-chars>100</max-snippet-chars>
    <preferred-matches>
      <element ns="/my/namespace" name="some-element" />
      <json-property>myProperty</json-property>
    </preferred-matches>
  </transform-results>
</options>
JSON
{"options": {
  "transform-results": {
    "max-matches": 5,
    "max-snippet-chars": 100,
    "preferred-matches": {
      "element": [{"ns": "/my/namespace", "name": "some-element"}],
      "json-property": ["myProperty"]
    }
  }
}}

The following example illustrates how to use the raw built-in snippeter. Use the same form for empty-snippet, but change the value of apply.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <transform-results apply="raw">
    <max-matches>5</max-matches>
  </transform-results>
</options>
JSON
{"options": {
  "transform-results": {"apply": "raw"}
}}

The following example demonstrates how to specify a custom snippet function and pass in some parameter values:

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <transform-results apply="my-snippeter"
      ns="/my/namespace" at="/my-library.xqy">
    <my-param1>42</my-param1>
    <my-param2>abc</my-param2>
  </transform-results>
</options>
JSON
{"options": {
  "transform-results": {
    "apply": "my-snippeter",
    "ns": "/my/namespace",
    "at": "/my-library.xqy",
    "my-param1": 42,
    "my-param2": "abc"
  }
}}

See Also

For more details on using this option, see the following topics:

tuples

The tuples option identifies values range indexes or lexicons in which to find value co-occurrences. Co-occurrences take the form of a values-response in the query response. Use this option with search:values and equivalent lexicon query interfaces.

You can specify range and geospatial indexes or the collection or URI lexicons. Include an aggregate child to specify an aggregate builtin or user-defined function to apply to the values. You can further tailor your results using top level options such as return-frequencies, return-values, and return-aggregates.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<tuples name="name" style="value">
  <range/>
  <geo-elem/>
  <geo-elem-pair/>
  <geo-attr-pair/>
  <geo-json-property/>
  <geo-json-property-pair/>
  <geo-path>
  <collection/>
  <uri/>
  <aggregate apply="funcName"
    udf="udfName" />
  <values-option>option</values-option>
</tuples>
"tuples": {
  "style": "value",
  "name": "name",
  "collection": ...,
  "range": ...,
  "geo-elem": ...,
  "geo-elem-pair": ...,
  "geo-attr-pair": ...,
  "geo-json-property": ...,
  "geo-json-property-pair": ...,
  "geo-path": ...,
  "collection": null,
  "uri": null,
  "aggregate": [{
    "apply": "funcName",
    "udf": string
  }],
"values-option": [ "option" ]
}

Component Description

The components of this option have the following semantics:

Element, Attribute or Property Name Description
name Required. The name identifying this tuples definition.
style How to format the results. Allowed values: default, consistent. When set to consistent, the output is structured the same whether returning single values or tuples. When set to default, the layout differs between values and tuples results.
range A range constraint with which to extract values from a range index or value lexicon.
geo-elem A geospatial element constraint with which to extract values from a geospatial index.
geo-elem-pair A geospatial element pair constraint with which to extract values from a geospatial index.
geo-attr-pair A geospatial element attribute constraint with which to extract values from a geospatial index.
geo-json-property A geospatial JSON property constraint with which to extract values from a geospatial index.
geo-json-property-pair A geospatial JSON property pair constraint with which to extract values from a geospatial index.
geo-path A geospatial path constraint with which to extract values from a geospatial index.
collection Extract values from the collection lexicon.
uri Extract values from the URI lexicon.
aggregate Specify builtin or user-defined aggregate functions to apply to lexicon values or value co-occurrences. The apply child is required and names the built-in or user-defined aggregate function to apply. When using a UDF, use udf to specify the path to the native plugin library containing the implementation of the function. In XML, specify this element multiple times to compute multiple aggregates.
values-option Specify zero or more options that affect the values under consideration. For details, see Values Options.

Examples

The following example specifies co-occurrences between editor and author element values.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <tuples name="editor-author">
    <range type="xs:string"
         collation="http://marklogic.com/collation">
      <element name="editor" ns="" />
    </range>
    <range type="xs:string"
         collation="http://marklogic.com/collation">
      <element name="author" ns="" />
    </range>
    <values-option>limit=5</values-option>
  </tuples>
</options>
JSON
{"options": {
  "tuples": [ {
    "name": "editor-author",
    "indexes": [
      {"range": {
        "type": "xs:string",
        "collation": "http://marklogic.com/collation",
        "element": {
          "name": "editor",
          "ns": ""
        }
      } },
      {"range": {
        "type": "xs:string",
         "collation": "http://marklogic.com/collation",
         "element": {
           "name": "author",
           "ns": ""
         }
      } }
    ],
    "values-option": [ "limit=5" ]
  } ]
} }

values

The values option constrains a values search to one or more range indexes or lexicons. Matched values take the form of a values-response in the query response. Use this option with search:values and equivalent interfaces.

You can specify range and geospatial indexes or the collection or URI lexicons. Include an aggregate child to specify an aggregate builtin or user-defined function to apply to the values. You can further tailor your results using top level options such as return-frequencies, return-values, and return-aggregates.

Syntax Summary

This option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XML JSON
All elements are in the namespace http://marklogic.com/appservices/search.
<values name="name" style="value">
  <range/>
  <geo-elem/>
  <geo-elem-pair/>
  <geo-attr-pair/>
  <geo-json-property/>
  <geo-json-property-pair/>
  <geo-path>
  <collection/>
  <uri/>
  <aggregate apply="funcName"
    udf="udfName" />
  <values-option>option</values-option>
</values>
"values": {
  "style": "value",
  "name": "name",
  "range": ...,
  "geo-elem": ...,
  "geo-elem-pair": ...,
  "geo-attr-pair": ...,
  "geo-json-property": ...,
  "geo-json-property-pair": ...,
  "geo-path": ...,
  "collection": null,
  "uri": null,
  "aggregate": [{
    "apply": "funcName",
    "udf": string
  }],
"values-option": [ "option" ]
}

Component Description

The components of this option have the following semantics. You can only include one index/lexicon specification.

Element, Attribute or Property Name Description
name Required. The name identifying this tuples definition.
style How to format the results. Allowed values: default, consistent. When set to consistent, the output is structured the same whether returning single values or tuples. When set to default, the layout differs between values and tuples results.
range A range constraint with which to extract values from a range index or value lexicon.
geo-elem A geospatial element constraint with which to extract values from a geospatial index.
geo-elem-pair A geospatial element pair constraint with which to extract values from a geospatial index.
geo-attr-pair A geospatial element attribute constraint with which to extract values from a geospatial index.
geo-json-property A geospatial JSON property constraint with which to extract values from a geospatial index.
geo-json-property-pair A geospatial JSON property pair constraint with which to extract values from a geospatial index.
geo-path A geospatial path constraint with which to extract values from a geospatial index.
collection Extract values from the collection lexicon.
uri Extract values from the URI lexicon.
aggregate Specify builtin or user-defined aggregate functions to apply to the lexicon values. The apply child is required and names the built-in or user-defined aggregate function to apply. When using a UDF, use udf to specify the path to the native plugin library containing the implementation of the function.In XML, specify this element multiple times to compute multiple aggregates.
values-option Specify zero or more options that affect the values under consideration. For details, see Values Options.

Examples

The following example illustrates several kinds of values query specification: An element range index spec that uses values-option, a URI lexicon spec, a collection lexicon spec, and a JSON property range index spec that applies a custom aggregate function to index values. For more examples, see search:values.

Format Example
XML
<options xmlns="http://marklogic.com/appservices/search">
  <values name="editor-author">
    <range type="xs:string"
         collation="http://marklogic.com/collation">
      <element name="editor" ns="" />
    </range>
    <values-option>limit=5</values-option>
  </values>
  <values name="uris">
    <uri/>
  </values>
  <values name="coll">
    <collection/>
  </values>
  <values name="aggregate">
    <range type="xs:double">
      <json-property>test</json-property>
    </range>
    <aggregate apply="mycalc" udf="sampleplugin" />
  </values>
</options>
JSON
{"options": {
  "values": [ 
    { "name": "editor-author",
      "range": {
        "type": "xs:string",
        "collation": "http://marklogic.com/collation",
        "element": { "name": "editor", "ns": "" }
      },
      "values-option": "limit=5"
    },
    { "name": "uris",
      "uri": null
    },
    { "name": "coll",
      "collection": null
    },
    { "name": "aggregate",
      "range": {
        "type": "xs:double",
        "json-property": "test"
      },
      "aggregate": [{
        "apply": "mycalc",
        "udf": "sampleplugin"
      }]
    }
  ]
} }

Term Options

The following options can be specified as the value of a term-option child in options that support them, such as a value or word constraint. By default, a query uses the same default options as the underlying cts:query constructors, and the defaults change based on your index configuration.

The following term options are supported:

  • case-sensitive
  • case-insensitive
  • diacritic-sensitive
  • diacritic-insensitive
  • punctuation-sensitive
  • punctuation-insensitive
  • whitespace-sensitive
  • whitespace-insensitive
  • stemmed
  • unstemmed
  • wildcarded
  • unwilcarded
  • exact
  • lang=iso639code
  • distance-weight
  • lexicon-expand=full
  • lexicon-expand=prefix-postfix
  • lexicon-expand=off
  • lexicon-expand=heuristic

Both distance-weight and lexicon-expand options are new with MarkLogic version 8. The following are new with MarkLogic version 9:

  • lexicon-expansion-limit
  • limit-check
  • no-limit-check

Facet Options

The following options can be specified as the value of a facet-option child in constraint types that can be used as a facet (any constraints except word, value, element-query, or property).

Legal values for a facet-option are generally any option that can be passed into the underlying query or lexicon API. The following list enumerates the facet-option values, but be aware that some options are only available with some range types. For more detail on these options, see the documentation for the underlying range or lexicon APIs.

The following facet options are supported:

  • ascending
  • descending
  • empties
  • any
  • document
  • properties
  • locks
  • frequency-order
  • item-order
  • fragment-frequency
  • item-frequency
  • gridded (geospatial constraints only)
  • type=type
  • timezone=TZ
  • limit=N
  • sample=N
  • truncate=N
  • skip=N
  • score-logtfidf
  • score-logtf
  • score-simple
  • score-random
  • checked
  • unchecked
  • eager
  • lazy
  • concurrent
  • map

The concurrent and map options are removed in the latest version of MarkLogic version 7 and all newer releases. The any, document, locks, and properties options are new with MarkLogic version 8. The lazy and eager options are new with MarkLogic version 9.

Range Options

The following options can be specified as the value of a range-option child in options that support them, such as a range constraint.

  • score-function=zero (default)
  • score-function=reciprocal
  • score-function=linear
  • slope-factor=number
  • max-occurs=number
  • min-occurs=number
  • cached
  • uncached
  • cached-incremental
  • synonym

For details, see Including a Range or Geospatial Query in Scoring and cts:element-range-query (XQuery) or cts.elementRangeQuery (JavaScript), or equivalent functions for other constraint types. The cached-incremental option is new with MarkLogic version 9.

Geospatial Point Query Options

The following options can be specified as the value of a geospatial-option child in options that support them, such as a geo-elem or geo-json-property.

  • coordinate-system=coord_sys/precision
  • coordinate-system=raw
  • coordinate-system=wgs84/double
  • coordinate-system=etrs89/double
  • coordinate-system=raw/double
  • cached-incremental
  • precision=float
  • precision=double
  • units=units
  • boundaries-included
  • boundaries-excluded
  • boundaries-latitude-excluded
  • boundaries-longitude-excluded
  • boundaries-south-excluded
  • boundaries-north-excluded
  • boundaries-east-excluded
  • boundaries-west-excluded
  • boundaries-circle-excluded
  • type=point
  • type=long-lat-point
  • score-function=zero (default)
  • score-function=reciprocal
  • score-function=linear
  • slope-factor=number
  • cached
  • uncached
  • synonym

Geospatial Region Query Options

The following options can be specified as the value of a geospatial-option child in a geospatial region query, such as a geo-region-path. For more information about the options, see cts:geospatial-region-query.

  • score-function=zero (default)
  • score-function=reciprocal
  • score-function=linear
  • slope-factor=number
  • synonym
  • tolerance=distance
  • units=units

Suggestion Options

The following options can be specified as the value of a suggestion-option child in a default-suggestion-source or suggestion-source option.

  • case-sensitive
  • case-insensitive
  • diacritic-sensitive
  • diacritic-insensitive
  • ascending
  • descending
  • frequency-order
  • item-order
  • fragment-frequency
  • item-frequency
  • type=type
  • timezone=TZ
  • sample=N
  • truncate=N
  • score-logtfidf
  • score-logtf
  • score-simple
  • score-random
  • checked
  • unchecked
  • any
  • document
  • locks
  • properties

The any, document, locks, and properties options are new with MarkLogic version 8.

Values Options

The following options can be specified as the value of a values-option child in a tuples or values option. For a description of these options, see cts:values and cts:value-tuples in the XQuery and XSLT Reference Guide. Some options can only be used when defining a values configurations; others can only be used when defining tuples.

  • ascending
  • descending
  • any
  • document
  • properties
  • locks
  • frequency-order
  • item-order
  • fragment-frequency
  • item-frequency
  • timezone=TZ
  • limit=N
  • skip=N
  • sample=N
  • truncate=N
  • score-logtfidf
  • score-logtf
  • score-simple
  • score-random
  • score-zero
  • checked
  • unchecked
  • eager
  • lazy
  • concurrent
  • map (for values only)
  • ordered (for tuples only)
  • proximity=N (for tuples only)
  • too-many-positions-error

The any, document, locks, too-many-positions-error and properties options are new with MarkLogic version 8. The eager and lazy options are new with MarkLogic version 9.

« Previous chapter