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.

XMLJSON
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.

KeyDescription
additional-queryAdditional serialized cts:query's, as XML literals. This option has array value in JSON and can appear multiple times in XML.
concurrency-levelThe maximum number of threads used to resolve facets.
constraintZero 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.
debugWhether or not to enable debugging mode. The default is false.
default-suggestion-sourceDefines the content to be used as the default source of suggestions (see search:suggest).
extract-document-dataSpecify element, attribute, or JSON property content from the search matches to return.
forestOne or more forest IDs. This option has array value in JSON and can appear multiple times in XML.
fragment-scopeControls the global fragment scope over which to search.
grammarA custom search grammar definition.
operatorA 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-lengthThe number of results to return per page. The default value is 10.
quality-weightSpecifies a weighting factor to use in the query. The default value is 1.0.
return-aggregatesInclude the result of running a builtin or user-defined aggregate function. Applies only to queries against values or tuples.
return-constraintsInclude the input constraint definitions in the results. The default is false.
return-facetsInclude resolved facets in the results. The default is true.
return-frequenciesInclude frequencies in the results. The default is true.
return-metricsInclude performance statistics in the results. The default is true.
return-planInclude xdmp:plan output in the results. The default is false.
return-qtextInclude the original query text in the results. The default is true.
return-queryInclude the XML query representation in the results. The default is false.
return-resultsInclude search results in the output. The default is true.
return-similarInclude with each search result a list of URLs of similar documents in the database. The default is false.
return-valuesWhen 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-expressionAn XPath expression to be searched. Whatever expression is specified is returned from the search.
sort-orderSet 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-sourceSpecify a search term completion suggestion source.
transform-resultsSpecify a function to use to process a search result for the snippet output.
tuplesDefine one or more value lexicons query against, matching value co-occurrences. That is, tuples of values, each of which appear in the same fragment.
valuesDefine 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.

XMLJSON
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.

FormatExample
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.

FormatExample
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.

XMLJSON
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 NameDescription
nameRequired. An identifier for the constraint. The name must be unique within the in-scope query options and may not contain whitespace.
annotationYour comments. Annotations have no effect on a query.
anyConstraintTypeA 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.

FormatExample
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.

XMLJSON
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>pathExpr</path-index>
  <fragment-scope>scope</fragment-scope>
  <bucket/>
  <computed-bucket/>
  <facet-option>option</facet-option>
  <range-option>option</range-option>
</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": "pathExpr",
  "fragment-scope": "scope",
  "bucket": [bucket descriptor],
  "computed-bucket": [bucket desc],
  "facet-option" : [ "option" ],
  "range-option": [ "option" ],
  "nullable" : boolean
}
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 NameDescription
typeThe 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.
collationA 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.
facetWhether or not to include facets based on this constraint in the query results.
nullableWhether 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 an XPath expression to constrain by. The path expression is limited to the subset of XPath that can be used to define a path range index. For details, see Understanding Path Range Indexes in Administrator's Guide.

The database configuration must include a corresponding path range index.

fragment-scopeSet 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).
bucketZero or more named ranges of static values. For details, see bucket.
computed-bucketZero or more named ranges of dynamic values. For details, see computed-bucket.
facet-optionSpecify 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-optionSpecify 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.
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.

FormatExample
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": "myNsURI"}, 
          "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.

FormatExample
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.

XMLJSON
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 NameDescription
typeA 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.
elementDefines 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.
attributeDefines 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-propertyDefines a JSON property on which to constrain queries.
fieldDefines a field on which to constrain queries.
weightHigher 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-scopeSet 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-optionSpecify 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.

FormatExample
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.

XMLJSON
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 NameDescription
elementDefines 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.
attributeDefines 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-propertyDefines a JSON property on which to constrain queries.
fieldDefines a field on which to constrain queries.
weightHigher 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-scopeSet 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-optionSpecify 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.

FormatExample
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.

XMLJSON
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 NameDescription
prefixConstrain 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.
facetWhether or not to generate facets from this constraint. Default: true.
facet-optionSpecify 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.

FormatExample
XML
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="mycoll" facet="true">
    <collection prefix="/my/collection/"/>
    <facet-option>limit=5</facet-option>
  </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.

XMLJSON
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 NameDescription
elementDefines 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-propertyDefines a JSON property on which to constrain queries.
fragment-scopeSet 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.

FormatExample
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.

XMLJSON
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 NameDescription
nsThe namespace of the element, if it is in a namespace.
nameRequired. The local name of the element.
fragment-scopeSet 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.

FormatExample
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.

XMLJSON
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.

FormatExample
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.

XMLJSON
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>
</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"
}
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 NameDescription
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.

heatmapA model of a two-dimensional grid, used to categorize data along two dimensions for faceting. For details, see heatmap.
facet-optionSpecify 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-optionSpecify 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-scopeSet 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 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.

FormatExample
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
      }
    }
  }]
}}

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.

XMLJSON
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>
</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"
}
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 NameDescription
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.

heatmapA model of a two-dimensional grid, used to categorize data along two dimensions for faceting. For details, see heatmap.
facet-optionSpecify 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-optionSpecify 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-scopeSet 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 defines two geo-elem constraints, one without a parent element specification and one with a parent element specification.

FormatExample
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.

XMLJSON
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>
</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",
}
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 NameDescription
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.

heatmapA model of a two-dimensional grid, used to categorize data along two dimensions for faceting. For details, see heatmap.
facet-optionSpecify 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-optionSpecify 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-scopeSet 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 defines a geospatial element pair constraint named 'my-geo-elem-pair'.

FormatExample
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.

XMLJSON
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>
</geo-json-property>
"geo-json-property": {
  "parent-property": ["name"],
  "json-property": ["name"],
  "facet-option": [ option ],
  "heatmap": {heatmap desc},
  "geo-option": [ option ],
  "fragment-scope": "scope"
}
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 NameDescription
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.

heatmapA model of a two-dimensional grid, used to categorize data along two dimensions for faceting. For details, see heatmap.
facet-optionSpecify 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-optionSpecify 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-scopeSet 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 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.

FormatExample
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.

XMLJSON
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>
</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"
}
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 NameDescription
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.

heatmapA model of a two-dimensional grid, used to categorize data along two dimensions for faceting. For details, see heatmap.
facet-optionSpecify 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-optionSpecify 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-scopeSet 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 defines a geospatial JSON property pair constraint, including the use of the geo-option, facet-option, and heatmap components.

FormatExample
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.

XMLJSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-path>
  <path-index>path</path-index>
  <facet-option>option</facet-option>
  <heatmap>heatmap descriptor</heatmap>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
</geo-path>
"geo-path": {
  "path-index": [ "path" ],
  "facet-option": [ option ],
  "heatmap": {heatmap desc},
  "geo-option": [ option ],
  "fragment-scope": "scope"
}
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 NameDescription
path-index

Required. XPath expression by which to constrain the search.

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 path expression is limited to the subset of XPath that can be used to define a path range index. For details, see Understanding Path Range Indexes in Administrator's Guide.

heatmapA model of a two-dimensional grid, used to categorize data along two dimensions for faceting. For details, see heatmap.
facet-optionSpecify 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-optionSpecify 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-scopeSet 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 illustrates a geospatial path constraint for an XML element or JSON property addressable with the XPath Expression '/a/b'.

FormatExample
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": "/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.

XMLJSON
All elements are in the namespace http://marklogic.com/appservices/search.
<geo-region-path coord="coord-sys">
  <path-index>path</path-index>
  <fragment-scope>scope</fragment-scope>
  <geo-option>option</geo-option>
  <weight>double</weight>
</geo-region-path>
"geo-region-path": {
  "path-index": [ "path" ],
  "coord": "coord-sys",
  "geo-option": [ option ],
  "fragment-scope": "scope",
  "weight": number
}
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 NameDescription
path-index

A path range expression matching an XML element or JSON property whose contents represent a region.

The database configuration must include 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.

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 path expression is limited to the subset of XPath that can be used to define a path range index. For details, see Understanding Path Range Indexes in Administrator's Guide.

coordThe 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-optionSpecify 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-scopeSet 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).
weightA weighting factor to apply to individual terms. Default: 1.0.
Examples

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

FormatExample
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": "/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.

XMLJSON
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 NameDescription
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.

parseRequired. Identifies the function used to parse the input query text or structured query.
start-facetIdentifies 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-facetIdentifies a function that accepts input from the start-facet function (if used) and constructs a facet element.
facet-optionSpecify 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-optionSpecify 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.

FormatExample
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 sub-component a geospatial constraint, such as geo-elem or geo-json-property. It is required when generating facets from a geospatial constraint.

A heatmap is a bounding box defined by 4 cooridnates (n, w, e, w) 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.

By default, each box facet returned in the search response 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 option has the following structure. Note that you can only use the JSON form with selected Client APIs, such as the REST Client API.

XMLJSON
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 NameDescription
nRequired. Heatmap bounding box north coordinate.
sRequired. Heatmap bounding box south coordinate.
eRequired. Heatmap bounding box east coordinate.
wRequired. Heatmap bounding box west coordinate.
latdivsRequired. The number of latitude divisions to apply to the bounding box.
londivsRequired. 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.

FormatExample
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:

FormatSearch 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 option 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.

XMLJSON
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 NameDescription
nameRequired. 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.
ltThe 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.
geThe 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.

FormatExample
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": "/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 option 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.

XMLJSON
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 NameDescription
nameRequired. 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.
ltThe 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.
geThe 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.
anchorA 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-anchorOverrides anchor for computing the bucket upper bound. Optional. Allowed values: now, start-of-day, start-of-month, start-of-year.
ge-anchorOverrides 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'.

FormatExample
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:

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.

FormatExample
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.

XMLJSON
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 NameDescription
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.

FormatExample
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.

FormatExample
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.

FormatExample
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 the subset suitable for defining path range indexes; for details, see Limitations on Index Path Expressions in the Administrator's 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.

XMLJSON
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 NameDescription
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 the subset of XPath that can be used to define a path range index. For details, see Understanding Path Range Indexes in Administrator's 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.

FormatExample
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.

FormatExample
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'.

FormatExample
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.

XMLJSON
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 NameDescription
quotationThe 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.
implicitA 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.
starterDefine 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.
joinerDefine 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.

FormatExample
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\"/>"
    }
  }
} 

See Also

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

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.

XMLJSON
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 NameDescription

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 (')').

strengthRequired. The order of precedence of this starter relative to other operators in this grammar. Higher strength tokens or groups are processed before lower ones.
applyThe 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.
nsThe XQuery module that contains the apply function, if using a user-defined function.
atThe module from which the apply function is imported, if using a user-defined function.
elementA 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.
optionsA space-separated list of options that are passed through to the underlying apply function.
tokenizeAllowed values: 'word' or 'default'.
delimiterWhen 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.

FormatExample
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.

XMLJSON
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 NameDescription

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'.
strengthRequired. The order of precedence of this operator relative to other operators in this grammar. Higher strength tokens or groups are processed before lower ones.
applyThe 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.
nsThe XQuery module that contains the apply function, if using a user-defined function.
atThe module from which the apply function is imported, if using a user-defined function.
elementA 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.
optionsA space-separated list of options that are passed through to the underlying apply function.
compareThe range query comparison operator to apply when defining a relational operator. Allowed values: LT, LE, GT, GE, NE, EQ.
consumeThe 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).
tokenizeAllowed 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.

FormatExample
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.

XMLJSON
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 NameDescription
nameRequired. The name of this operator. The name must be unique across all operators and constraints in scope.
stateOne or more state definitions for the operator.
state/nameRequired. The name of this state.
state/additional-queryA cts:query to evaluate when the operator is in this state.
state/debugWhether or not to enable debug logging. Default: false.
state/forestA forest id. This must be an unsigned long value.
state/page-lengthThe page length into which results should be chunked.
state/quality-weightSpecifies a weighting factor to use in the query. The default value is 1.0.
state/search-optionSearch options passed to the additional-query. You can include zero or more options.
state/searchable-expressionSpecifies an XPath expression to search. For details, see searchable-expression.
state/sort-orderSpecifies a sort order to apply. For details, see sort-order.
state/transform-resultsDefine 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.

FormatExample
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>ascending</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": null
          }]
        },
        { "name": "up",
          "sort-order": [{
            "direction": "ascending",
            "score": 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.

FormatExample
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.

FormatExample
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.

XMLJSON
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 NameDescription
applyThe localname of a custom result decorator function. You must also specify ns and at.
nsThe namespace of the function in apply. This must match the namespace declaration of the XQuery library module containing the apply function.
atThe 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.

FormatExample
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.

FormatExample
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.

FormatExample
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.

FormatExample
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.

FormatExample
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.

FormatExample
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.

FormatExample
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.

FormatExample
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 XML 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.

FormatExample
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.

FormatExample
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.

FormatExample
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.

FormatExample
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.

FormatExample
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

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.

Using this option in the options section of a combined query evaluated using the REST, Java, or Node.js Client API requires the rest-admin role or equivalent privileges if the expression is not a valid indexable path. For details, see Using Dynamically Defined Query Options in the REST Application Developer's Guide.

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.

XMLJSON
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 NameDescription

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'.

FormatExample
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 element, element attribute, field, or JSON property during a document search.

A set of 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, score, 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.

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.

XMLJSON
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>
  <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",
  "score": null
}

Component Description

The components of this option have the following semantics:

Element, Attribute or Property NameDescription
elementIdentifies 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 or json-property child.
attributeIdentifies 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 field or json-property, and you must specify element.
fieldIdentifies the field to which this sort order applies. Cannot be used with element, attribute or json-property. You should not apply sort-order to a field that has more than one included element.
json-propertyIdentifies the JSON property to which this sort order applies. Cannot be used with element, attribute or field.
scoreSort by the score of the search result. For details, see Relevance Scores: Understanding and Customizing in the Search Developer's Guide.
typeIf 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.
collationA collation URI. Optionally specify a collation when type is xs:string; otherwise, use the collation of the query.
directionSpecify the sorting direction. Default: descending. Allowed values: ascending, descending.

Examples

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

FormatExample
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.

XMLJSON
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 NameDescription
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

FormatExample
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-key": "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.

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.

XMLJSON
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 NameDescription
applyThe 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.
nsThe XQuery module that contains the apply function, if using a user-defined function.
atThe module from which the apply function is imported, if using a user-defined function.
defaultSpecify 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.
emptySpecify 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.
weightA weighting factor to apply to individual terms. Default: 1.0.
term-optionZero or more options to apply to term matching. For details, see Term Options.
fragment-scopeSpecifies 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.

FormatExample
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.

FormatExample
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:

FormatExample
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:

FormatExample
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:

XMLJSON
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:

XMLJSON
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 NameDescription
applyThe 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-matchesWhen 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-tokensWhen 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-matchesWhen 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-charsWhen using the snippet built-in function, limit total snippet size to this many characters. Default: 200.
nsWhen using a custom snippeting function, the namespace URI of the containing module.
atWhen using a custom snippeting function, the path to the module containing the function.
userDefinedParamsWhen using a custom snippeting function, specify parameters to pass to the custom function as additional XML elements or JSON properties on the option.

Examples

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

FormatExample
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.

FormatExample
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:

FormatExample
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.

XMLJSON
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 NameDescription
nameRequired. The name identifying this tuples definition.
styleHow 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.
rangeA range constraint with which to extract values from a range index or value lexicon.
geo-elemA geospatial element constraint with which to extract values from a geospatial index.
geo-elem-pairA geospatial element pair constraint with which to extract values from a geospatial index.
geo-attr-pairA geospatial element attribute constraint with which to extract values from a geospatial index.
geo-json-propertyA geospatial JSON property constraint with which to extract values from a geospatial index.
geo-json-property-pairA geospatial JSON property pair constraint with which to extract values from a geospatial index.
geo-pathA geospatial path constraint with which to extract values from a geospatial index.
collectionExtract values from the collection lexicon.
uriExtract values from the URI lexicon.
aggregateSpecify 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-optionSpecify 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.

FormatExample
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.

XMLJSON
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 NameDescription
nameRequired. The name identifying this tuples definition.
styleHow 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.
rangeA range constraint with which to extract values from a range index or value lexicon.
geo-elemA geospatial element constraint with which to extract values from a geospatial index.
geo-elem-pairA geospatial element pair constraint with which to extract values from a geospatial index.
geo-attr-pairA geospatial element attribute constraint with which to extract values from a geospatial index.
geo-json-propertyA geospatial JSON property constraint with which to extract values from a geospatial index.
geo-json-property-pairA geospatial JSON property pair constraint with which to extract values from a geospatial index.
geo-pathA geospatial path constraint with which to extract values from a geospatial index.
collectionExtract values from the collection lexicon.
uriExtract values from the URI lexicon.
aggregateSpecify 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-optionSpecify 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.

FormatExample
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

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
  • type=type
  • timezone=TZ
  • limit=N
  • sample=N
  • truncate=N
  • skip=N
  • score-logtfidf
  • score-logtf
  • score-simple
  • score-random
  • checked
  • unchecked
  • concurrent
  • map

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
  • 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.

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
  • 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.

  • 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

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:values-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
  • concurrent
  • map (for values only)
  • ordered (for tuples only)
  • proximity=N (for tuples only)

« Previous chapter
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy