Loading TOC...
REST Application Developer's Guide (PDF)

REST Application Developer's Guide — Chapter 9

Appendix A: JSON Query Options Reference

This chapter defines the JSON structure of query options (search:options) used by the search related features of the MarkLogic REST API and the MarkLogic Java API.

Query options can also be expressed as XML. For details, see Appendix B: XML Query Options Reference.

How to Use This Reference

This reference describes the layout of the options structure usable with the query capabilities of the MarkLogic REST API and MarkLogic Java API, when expressed as JSON. The structures are shown with all possible properties, but not all properties may be usable together.

For specific semantics, refer to the description of each structure. For more details, refer to the options descriptions for the XQuery function search:search in the XQuery and XSLT Reference Guide.

Query Options

"options": {
  "additional-query": [ string ],
  "concurrency-level": string,
  "constraint": [ constraint ],
  "debug": boolean,
  "default-suggestion-source": [ suggestion-source ],
  "extract-metadata": extract-metadata,
  "forest": unsigned long,
  "fragment-scope": string,
  "grammar": grammar,
  "operator": [ operator ],
  "page-length": unsigned long,
  "quality-weight": double,
  "return-aggregates": boolean,
  "return-constraints": boolean,
  "return-facets": boolean,
  "return-frequencies": boolean,
  "return-metrics": boolean,
  "return-plan": boolean,
  "return-qtext": boolean
  "return-query": boolean,
  "return-results": boolean,
  "return-similar": boolean,
  "return-values": boolean,
  "search-option": [ string ],
  "searchable-expression": { path-expression }
  "sort-order": [ sort-order ],
  "suggestion-source": [ suggestion-source ],
  "term": term-definition,
  "transform-results": transform-results,
  "tuples": values-or-tuples,
  "values": values-or-tuples 
}

Key Value Description
additional-query[] [ string ] Additional serialized cts:query's, as XML literals. The queries are AND'd with the string and/or structured query that is supplied to the request. The query results are constrained by the additional-query, but any terms matching the addtional-query are not highlighted in the snippet result output. For example, the following constrains the results to the directory named /my/directory/:
"additional-query":[
"<directory-query
    xmlns='http://marklogic.com/cts'>
  <uri>/my/dir/</uri>
</directory-query>"
]
concurrency-level unsigned integer The maximum number of threads used to resolve facets. The default is 8, which specifies that at most 8 threads will be used concurrently to resolve facets.
constraint[] [ constraint ] Constraints define facets which can be returned as part of the search results. The default is no defined constraints. Each constraint must have an name, which is the unique name of this constraint. The name can be used in the search grammar to specify the constraint. The list can contain zero or more constraint objects.
debug boolean Activates debugging mode. Additional report elements will be present in the output. Set to true to activate. The default is false.
default-suggestion-source[] [suggestion-source]

Defines the content to be used as the default source of suggestions (see search:suggest). The source may be expressed as a reference to an existing named constraint, or as a collection, value, word or word-lexicon element. Note that the use of word-lexicon (the database-wide word lexicon) is not recommended as best practice; collection and range lexicons will yield the best performance.

Each default-suggestion-source object can optionally have 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.

extract-metadata extract-metadata Specifies data to return in the metadata section of the response output. You can specify element or attribute content from the search hits to be returned or values from any constraints in your search.
forest[] [ unsigned long ] One or more forest IDs.
fragment-scope string

Allowable values:

  • properties
  • documents (default)

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

You can override the global fragment scope by setting a local fragment scope inside a constraint definition. 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.

grammar grammar A custom search grammar definition. The default grammar defines "Google-style" parsing.
operator[] [ operator ] A list of state elements, each representing a unique run-time configuration option. For example, if an operator with the name "sort" is defined, query text [sort:foo] will select the state child with the name "foo" at query runtime, using the option specified on that state element. Options affecting query parsing (such as constraint, grammar, term, empty) may not be configured via operators.
page-length unsigned long Specifies the number of results per page. The default value is 10.
quality-weight double Specifies a a weighting factor to use in the query. The default value is 1.0.
return-aggregates boolean Include the result of running a builtin or user-defined aggregate function. Applies only to queries against values or tuples.
return-constraints boolean Include original constraint definitions in the results. The default is false.
return-facets boolean Include resolved facets in the results. The default is true.
return-frequencies boolean Include frequencies in the results.
return-metrics boolean Include statistics in the results. The default is true.
return-plan boolean Include xdmp:plan output in the results. The default is false. The output is useful in examining the evaluation plan of the search.
return-qtext boolean Include the original query text in the results. The default is true.
return-query boolean Include the XML query representation in the results. The default is false.
return-results boolean Include search results in the output. (Use transform-results to specify how each result should be formatted.) The default is true.
return-similar boolean Include with each search result a list of URLs of similar documents in the database. The default is false.
return-values boolean When querying a range index or values lexicon, whether or not to include the index/lexicon values in the results. Default: true.
search-option[] [ string ] For advanced users, one or more options to be passed in to the query operation (for example, filtered, unfiltered, score-logtfidf, and so on). See the XQuery function cts:search.
searchable-expression path-expression An expression to be searched. Whatever expression is specified is returned from the search. For example, if you specify //p, then p elements that match the search criteris are returned. The expression must be an inline fully searchable XPath expression, and all necessary namespaces must be declared. The default value is fn:collection(), which searches all documents in the database. This option does not affect facet results. To constrain facet results, use additional-query.
sort-order[] [ sort-order ] Set the default sort order. The first such value is the primary sort order, the second secondary sort order, and so on. The default is to sort by score, descending. Note that the default scoring algorithm can be set just like any other option with the option named search-option.
suggestion-source [suggestion-source]

Specifies a constraint source to override a named constraint when using search:suggest. The suggestions are often used for type-ahead suggestions in a search user interface. If empty, no suggestions are generated when that constraint is applied. Specifying an alternate suggestion-source is useful in cases where you have a named constraint to use for searching and facets, but you might want to use a slightly (or completely) different source for type-ahead suggestions without needed to re-parse your search terms.

Each suggestion source must have a ref property corresponding to a named constraint (one suggestion-source per named constraint).

transform-results 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.
tuples values-or-tuples Defines one or more value lexicons query against, matching value co-occurrences. That is, tuples of values, each of which appear in the same fragment.
values values-or-tuples Defines one or more value lexicons to query against.

attribute-descriptor

{
  "name": string,
  "ns": string
}

The definition of an XML element attribute. An attribute descriptor is generally accompanied by an element descriptor to identify the containing element.

Key Value Description
name string Required. The name of an attribute.
ns string The namespace in which the attribute is defined.

Example:

{ "name": "bar", "ns": "http://marklogic.com/examples" }

bucket

{
  "name": string,
  "label": string,
  "lt": atomic-value,
  "ge": atomic-value
}

A named range of static values within a range constraint. For dynamic value ranges see computed-bucket. Values assigned to a bucket meet the criteria:

bucket.lt < value <= bucket.gt

Key Value Description
name string Required. Identifies this bucket.
label string Text that can be used to label the bucket. Corresponds to the text() in an XML <bucket/> definition.
lt atomic-value The lower bound for values assigned to this bucket.
ge atomic-value The upper bound for values assigned to this bucket.

Example:

{
  "options": {
    "constraint": [
      {
        "name": "decade",
        "range": {
          "type": "xs:gYear",
          "facet": true,
          "facet-option": [
            "limit=10"
          ],
          "bucket": [
            {
              "lt": "1930",
              "ge": "1920",
              "name": "1920s",
              "label": "1920s"
            },
            {
              "lt": "1940",
              "ge": "1930",
              "name": "1930s",
              "label": "1930s"
            }
          ],
          "attribute": {
            "ns": "",
            "name": "year"
          },
          "element": {
            "ns": "http:\/\/marklogic.com\/wikipedia",
            "name": "nominee"
          }
        }
      }
    ]
  }
}

collection-constraint

{
  "prefix": string,
  "facet-option": [ string ],
  "facet": boolean
}

Key Value Description
prefix string Required. Constrain a query to documents in collections matching this prefix.
facet-option[] [ string ] Zero or more facet-options.
facet boolean Whether or not to generate facets from this constraint.

The following example defines a collection constraint called 'my-collection' that constrains a query to documents in collections with the prefix '/my/path/':

{
  "options": {
    "constraint": [
      {
        "name": "my-collection",
        "collection": {
          "prefix": "\/my\/path\/"
        }
      }
    ]
  }
}

computed-bucket

{
  "name": string,
  "label: string,
  "lt": atomic-value,
  "ge": atomic-value,
  "anchor": string,
  "lt-anchor": string,
  "ge-anchor": string
}

A named range of dynamic temporal values within a range constraint. For static value ranges see bucket. Values assigned to a bucket meet the criteria:

(bucket.anchor + bucket.lt) < value <= (bucket.anchor + bucket.gt)

Use lt-anchor and ge-anchor to override the anchor value used to compute the lower and upper bounds, respectively.

Key Value Description
name string Required. The name of this bucket.
label string Text that can be used to label the bucket. Corresponds to the text() in an XML <bucket/> definition.
lt atomic-value The lower bound for values assigned to this bucket, relative to anchor or lt-anchor. The value should be an xs:duration, xs:yearMonthDuration, or xs:dayTimeDuration.
ge atomic-value The lower bound for values assigned to this bucket, relative to anchor or ge-anchor. The value should be an xs:duration, xs:yearMonthDuration, or xs:dayTimeDuration.
anchor string A dynamic temporal anchor value for the bucket. The bucket bounds are relative to this dynamic value. Allowed values:
  • now
  • start-of-day
  • start-of-month
  • start-of-year
lt-anchor string Overrides anchor for computing the bucket lower bound. For allowed values, see anchor.
ge-anchor string Overrides anchor for computing the bucket upper bound. For allowed values, see anchor.

Example:

{
  "options": {
    "constraint": [
      {
        "name": "made",
        "range": {
          "type": "xs:dateTime",
          "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"
            }
          ],
          "element": {
            "ns": "http:\/\/example.com",
            "name": "manufactured"
          },
          "attribute": {
            "ns": "",
            "name": "date"
          }
        }
      }
    ]
  }
}

constraint

{
  "name": string,
  "annotation": [ string ],
  "range": range-constraint,
  "word": word-constraint,
  "value": value-constraint,
  "collection": collection-constraint,
  "properties": properties-constraint,
  "element-query": element-descriptor,
  "custom": custom-constraint,
  "geo-elem": geo-elem-constraint,
  "geo-elem-pair": geo-elem-pair-constraint,
  "geo-attr-pair": geo-attr-pair-constraint 
}

Every constraint must have a unique name and may have an annotation. The constraint semantics are expressed through one or more of the remaining constraint object types (range, word, value, etc.).

Key Value Description
name string Required. The name must be unique within these query options and may not contain whitespace.
annotation [ string ] Your comments. Annotations have no effect.
range range-constraint Specifies the element or attribute on which to constrain by range. There must be a range index of the specified type (and collation for string range indexes) defined.
word word-constraint Specifies the element, attribute, or field on which to constrain by word. You cannot create facets from a word constraint.
value value-constraint Specifies element or attribute values on which to constrain by value. You cannot create facets from a value constraint.
collection collection-constraint Specifies a collection which to constrain.
properties properties-constraint Specifies a constraint that finds matches on the corresponding properties documents. You cannot create facets from a properties constraint.
element-query element-descriptor Specifies a constraint that restricts the search to the specified element. You cannot create facets from an element-query constraint.
custom custom-constraint Specifies a custom constraint along with the name of the function implementations used to evaluate the custom constraint.
geo-elem geo-elem-constraint Specifies a geospatial constraint. If the constraint has a heatmap child, then it can be used as a facet, and can contain facet-options.
geo-elem-pair geo-elem-pair-constraint Specifies a geospatial constraint. If the constraint has a heatmap child, then it can be used as a facet, and can contain facet-options.
geo-attr-pair geo-attr-pair-constraint Specifies a geospatial constraint. If the constraint has a heatmap child, then it can be used as a facet, and can contain facet-options.

custom-constraint

{
  "parse": {
    "apply": string,
    "ns": string,
    "at": string
  },
  "start-facet": {
    "apply": string,
    "ns": string,
    "at": string
  },
  "finish-facet": {
    "apply": string,
    "ns": string,
    "at": string
  },
  "facet-option": [ string ],
  "term-option": string,
  "facet": boolean
}

Specifies a custom constraint along with the name of the function implementations used to evaluate the custom constraint.

Key Value Description
parse object Required. Identifies the function used to parse the query text to produce a cts:query.
parse.apply string Required. The parsing function localname.
parse.ns string The namespace in which the function is declared.
parse.at string The URI of the XQuery library module implementing function.
start-facet object Identifies a function to make lexicon API calls that return the values and counts used to construct facets.
start-facet.apply string Required if start-facet is defined.
start-facet.ns string The namespace in which the function is declared.
start-facet.at string The URI of the XQuery library module implementing function.
finish-facet object Identifies the function takes input from the start-facet function (if it is used) and constructs the facet element.
finish-facet.apply string Required if finish-facet is defined. The function localname.
finish-facet.ns string The namespace in which the function is declared.
finish-facet.at string The URI of the XQuery library module implementing function.
facet-option[] [ string ] Zero or more facet-options.
term-option[] [ string ] Zero or more term-options.
facet boolean Whether or not to use this constraint for faceting.

element-descriptor

{
  "name": string,
  "ns": string
}

This object defines an XML element for use in options such as constraints.

Key Value Description
name string Required. The name of an element.
ns string The namespace in which the named element is defined.

Example:

{ "name": "foo", "ns": "http://marklogic.com/examples" }

extract-metadata

{
  "constraint-value": [
    { "ref": string }
  ],
  "qname": [ 
    {
      "elem-ns": string,
      "elem-name": string,
      "attr-ns": string,
      "attr-name": string
    }
  ]
  "json-key": [ string ]
}

Use extract-metadata to select one or more metadata elements from each document in the query result set. Selections are made by specifying qnames (element or element and attribute), JSON keys, or constraint references (collection, range and geospatial types only) for extraction from indexes.

Key Value Description
constraint-value[] array An array of references to named constraints defined in these query options. Corresponding indexes must exist when the query executes.
constraint-value.ref string The name of a collection, range, or geospatial constraint defined in these query options.
qname[] array An array of QName definitions for element or element attribute content from the search hits to be returned.
qname.elem-name string The name of an element from which content should be returned. Required (if using qname).
qname.elem-ns string The namespace URI in which qname.elem-name is defined. Required (if using qname)
qname.attr-name string The name of an attribute of qname.elem-name whose value should be returned.
qname.attr-ns string The namespace URI in which qname.attr-name is defined.
json-key[] [ string ] The names of json keys from which content should be returned. Applicable only to JSON documents loaded using the MarkLogic REST API or MarkLogic Java API.

Example:

{
  "options": {

    "extract-metadata": {
      "constraint-value": [
        { "ref": "title" },
        { "ref": "speaker" }
      ],
      "qname": [
        {
          "elem-ns": "http:\/\/example.com",
          "elem-name": "foo"
        }
      ],
      "json-key": [ "foo", "bar" ]
    }
    "constraint": [
      {
        "name": "title",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "TITLE"
          }
        }
      },
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "SPEAKER"
          }
        }
      }
    ]
  }
}

field-descriptor

{
  "name": string,
  "collation": string
}

Key Value Description
name string Required. The name of a field.
collation string An optional collation URI.

geo-attr-pair-constraint

{
  "parent": element-descriptor,
  "lat": attribute-descriptor,
  "lon": attribute-descriptor,
  "facet-option": [ string ],
  "geo-option": [ string ],
  "heatmap": heatmap-descriptor 
}

A geospatial constraint modelling a geospatial index with coordinates stored as element attributes. 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-attribute-pair-geospatial-query.

Key Value Description
parent element-descriptor Defines the parent element.
lat object The latitude-defining attribute.
lon object The longitude-defining attribute.
facet-option[] [ string ] Zero or more facet-options.
geo-option[] [ string ] Zero or more geo-options.
heatmap heatmap-descriptor A heatmap that to use for faceting.

Example:

{
  "options": {
    "constraint": [
      {
        "name": "my-geo-attr-pair",
        "geo-attr-pair": {
          "facet-option": [
            "empties"
          ],
          "heatmap": {
            "s": 23.2,
            "w": -118.3,
            "n": 23.3,
            "e": -118.2,
            "latdivs": 4,
            "londivs": 4
          },
          "parent": {
            "ns": "ns1",
            "name": "elem1"
          },
          "lat": {
            "ns": "ns2",
            "name": "attr2"
          },
          "lon": {
            "ns": "ns3",
            "name": "attr3"
          }
        }
      }
    ]
  }
}

geo-elem-constraint

{
  "parent": element-descriptor,
  "element": element-descriptor,
  "facet-option": [ string ],
  "geo-option": [ string ],
  "heatmap": heatmap-descriptor}

A geospatial constraint modelling a geospatial index with coordinates stored in a single element. 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-geospatial-query.

Key Value Description
parent element-descriptor The parent element.
element element-descriptor The element defining the latitude and longitude.
facet-option[] [ string ] Zero or more facet-options.
geo-option[] [ string ] Zero or more geo-options.
heatmap heatmap-descriptor Describes a heatmap to use for faceting.

Example:

{
  "options": {
    "constraint": [
      {
        "name": "geo-elem-child",
        "geo-elem": {
          "parent": {
            "ns": "",
            "name": "g-elem-child-parent"
          },
          "element": {
            "ns": "",
            "name": "g-elem-child-point"
          }
        }
      }
    ]
  }
}

geo-elem-pair-constraint

{
  "parent": element-descriptor,
  "lat": element-descriptor,
  "lon": element-descriptor,
  "facet-option": [ string ],
  "geo-option": [ string ],
  "heatmap": heatmap-descriptor 
}

A geospatial constraint modelling a geospatial index with coordinates stored in a two elements. 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 details, see cts:element-pair-geospatial-query.

Key Value Description
parent element-descriptor The parent element.
lat element-descriptor The latitude-defining element.
lon element-descriptor The longitude-defining element.
facet-option[] [ string ] Zero or more facet-options.
geo-option[] [ string ] Zero or more geo-options.
heatmap heatmap-descriptor Defines a heatmap to be used for faceting.

grammar

{
  "implict": string,
  "quotation": string,
  "starter": [ starter ],
  "joiner": [ joiner ]
}

Specifies a custom search grammar. For details, see Modifying and Extending the Search Parsing Grammar in the Search Developer's Guide.

Key Value Description
implict string A cts:query, as a serialized string literal, to use by default to join two search terms together. By default, the Search API uses a cts:and-query, but you can change it to any cts:query with the implicit grammar option.
quotation string The string to use to indicate the start and end of a phrase.
starter starter Zero or more custom starters that denote special parsing for terms.
joiner [ joiner ] Zero or more custom joiners for joining two terms (cat AND dog) or for separating a constraint or operator from its value.

Example:

{
  "options": {
    "grammar": {
      "starter": [
        {
          "strength": 30,
          "apply": "grouping",
          "delimiter": ")",
          "label": "("
        }
      ],
      "joiner": [
        {
          "strength": 10,
          "apply": "infix",
          "cts-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\"\/>"
    }
  }
}

heatmap-descriptor

{
  "n": double,
  "s": double,
  "e": double,
  "w": double,
  "latdivs": number,
  "londivs": number
}

Models a two-dimensional grid used to categorize data along two dimenstions. Use with geospatial indexes.

Key Value Description
n double Required. The north coordinate.
s double Required. The south coordinate.
e double Required. The east coordinate.
w double Required. The west coordinate.
latdivs unsigned integer Required. The number of latitude divisions.
londivs unsigned integer Required. The number of longitude divisions.

joiner

{
  "apply": string,
  "ns": string,
  "at": string,
  "label": string,
  "strength": integer,
  "element": string,
  "options": string,
  "tokenize": string,
  "compare": string,
  "consume": integer
}

Key Value Description
label string Required. The joiner operator token. For example, the default grammar includes a joiner with the label 'AND', which enables queries like 'cat AND dog'.
apply string The local-name of a function to use to apply the joiner.
ns string The namespace in which the apply function is defined, if using a user-defined function.
at string The module from which the apply function is imported, if using a user-defined function.
strength integer Required. The order of precedence of this joiner over others. Higher strength tokens or groups are processed before lower ones.
element string A cts:query element name (for example, cts:and-query).
options string A space-separated list of options that are passed through to the underlying cts:query constructor
tokenize string Allowed values: 'word' or 'default'.
compare string The comparison operator used in range queries. Allowed values: LT, LE, GT, GE, NE
consume integer The number of tokens to consume when parsing N-token joiners. For example, in the expression 'A NEAR B', one token is consumed, but in the expression 'A NEAR/2 B' two tokens are consumed.

Example:

{
  "options": {
    "grammar": {
      "joiner": [
        {
          "strength": 10,
          "apply": "infix",
          "cts-element": "cts:or-query",
          "tokenize": "word",
          "label": "OR"
        }
      ]
    }
  }
}

operator

{
  "name": string,
  "state": [ 
    {
      "name": string,
      "additional-query": string,
      "annotation": [ string ],
      "debug": boolean,
      "forest": unsigned long,
      "page-length": unsigned long,
      "quality-weight": double,
      "search-option": [ string ],
      "searchable-expression": path-expression,
      "sort-order": [ sort-order ],
      "transform-results": transform-results    }
  ]
}

A named wrapper for one or more state elements, each representing a unique run-time configuration option. For example, if an operator with the name "sort" is defined, query text [sort:foo] will select the state child with the name "foo" at query runtime, using the option specified on that state element. Options affecting query parsing (such as constraint, grammar, term, empty) may not be configured via operators.

Key Value Description
name string Required. The name of this operator. The name must be unique across all operators and constraints
state[] array One or more state definitions.
state.name string Required. The name of this state.
state.additional-query string A query to perform when the operator is encountered.
state.annotation [ string ] Your comments. Annotations have no effect.
state.debug boolean Whether or not to enable debug logging. Default: false.
state.forest unsigned long A forest id.
state.page-length unsigned long The page length into which results are chunked.
state.quality-weight double Specifies a a weighting factor to use in the query. The default value is 1.0.
state.search-option[] [ string ] Zero or search options.
state.searchable-expression path-expression A query to perform when the operator is encountered.
state.sort-order[] [ sort-order ] Sort order rules to apply when the operator is encountered in a query.
state.transform-results transform-results Transformations to apply to the results produced by this operator.

The following example defines 2 operators, named 'sort' and 'page-length'. The 'sort' operator has 2 states, 'down' and 'up'. The 'page-length' operator has 2 states, 'short' and 'long'. This allows you, for example, to include a search term of the form sort:up to request results in ascending order.

{
  "options": {
    "operator": [
      {
        "name": "sort",
        "state": [
          {
            "name": "down",
            "sort-order": [{
                "direction": "descending",
                "score": null
              }]
          },
          {
            "name": "up",
            "sort-order": [{
                "direction": "ascending",
                "score": null
              }]
          }]
      },
      {
        "name": "page-length",
        "state": [
          {
            "name": "short",
            "page-length": 10
          },
          {
            "name": "long",
            "page-length": 50
          }]
      }]
  }
}

path-expression

{
  "text": string,
  "namespaces": { prefix-list }
}

Key Value Description
text string Required. The XPath expression. If the expression uses namespace prefixes, the prefixes must be defined in the namespaces property. Path elements with no prefix are assumed to be in no namespace.
namespaces prefix-list Optional. A list of prefix:uri pairs, defining any namespace prefixes used in the text property of this expression. See the example below.

The following example demonstrates using the path-expression 'a:foo/b:bar/qux' as the definition of a searchable-expression:

{
  "options": {
    "searchable-expression": {
      "text": "\/a:foo\/b:bar\/qux",
      "namespaces": {
        "a": "http:\/\/a",
        "b": "http:\/\/b"
      }
    }
  }
}

properties-constraint

{ "properties": null }

Constrains a search to matches found in document properties.

Example:

{
  "options": {
    "constraint": [
      { "name": "just-props", "properties": null" }
    ]
  }
}

range-constraint

{
  "type": string,
  "element": element-descriptor,
  "attribute": attribute-descriptor,
  "field": field-descriptor,
  "json-key": string,
  "path-index": path-expression,
  "fragment-scope": string,
  "bucket": [ bucket ],
  "computed-bucket": [ computed-bucket ],
  "facet-option" : [ string ]
  "collation" : string,
  "facet": boolean
}

Specifies an element, element attribute, field, JSON key, or XPath expression on which to constrain by range. The constraint must include one of element, field, json-key, or path-index. If there is an element, an attribute may also be included.

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

For range constraints with either bucket or computed-bucket specifications, for maximum performance and sortability, the buckets should be in a continuous order; if the order is not continuous (either ascending or descending), then the buckets are returned in the order specified, regardless of any sorting facet-option in the specification.

Key Value Description
type string Required. The XQuery type of the values in the range. There database configuration must include a range index with this value type.
element element-descriptor Defines an XML element to constrain by or the element containing attribute. If there is an element, there can also be an attribute. There must not be a field, json-key, or path-index. The database configuration must include a corresponding element or element attribute range index.
attribute attribute-descriptor Defines an XML element attribute to constrain by. There must be an accompanying element property. There must not be a field, json-key, or path-index. The database configuration must include a corresponding attribute range index.
field field-descriptor Defines field to constrain by. There must be an accompanying element property. There must not be a element, attribute, json-key, or path-index. The database configuration must include a corresponding field range index.
json-key string Defines JSON key to constrain by. There must be an accompanying element property. There must not be an element, attribute, field, or path-index. JSON key constraints apply only to JSON documents loaded using the MarkLogic REST API or the MarkLogic Java API.
path-index path-expression Defines an XPath expression to constrain by. There must be an accompanying element property. There must not be a element, attribute, json-key, or field. The database configuration must include a corresponding path range index.
fragment-scope string

Allowable values:

  • properties
  • documents (default)

Set a local fragment scope for this constraint. The local fragment-scope overrides a 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.

bucket[] [ bucket ] Zero or more named ranges of static values.
computed-bucket[] [ computed-bucket ] Zero or more named ranges of dynamic values.
facet-option[] [ string ] Zero or more facet-options.
collation string A collation URI, if type is xs:string.
facet boolean Whether or not to include facets.

Example:

{
  "options": {
    "constraint": [
      {
        "name": "size",
        "range": {
          "type": "xs:unsignedInt",
          "bucket": [
            {
              "name": "small",
              "lt": "5",
              "label": "Under 5"
            },
            {
              "name": "medium",
              "ge": "5",
              "lt": "12",
              "label": "5 to 12"
            },
            {
              "name": "large",
              "ge": "12",
              "label": "12+"
            }
          ],
          "element": {
            "name": "shoe",
            "ns": "http:\/\/implementation-specific.com"
          },
          "attribute": {
            "name": "size",
            "ns": ""
          }
        }
      }
    ]
  }
}

sort-order

{
  "element": element-descriptor,
  "attribute": attribute-descriptor,
  "field": field-descriptor,
  "json-key": string,
  "score": string,
  "annotation": [ string ],
  "type": string,
  "collation": string,
  "direction": string
}

Defines the sort order of an element, element attribute, field, or JSON property. A sort-order object must have one of a single element child, a single score child, a single field child, or a single json-key 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 elements must have ns and name attributes to specify the namespace and local-name of the specified element and attribute.

You should not apply sort-order to a field that has more than one included element.

If there is a score child, it specifies to sort by the score of the search result.

Key Value Description
element element-descriptor Identifies the 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 property is present, you cannot also specify field or json-key.
attribute attribute-descriptor Identifies the element attribute to which this sort order applies. You must set type to match the range index type of this attribute. If an attribute property is present, you cannot also specify field or json-key, and you must specify element.
field field-descriptor Identifies the field to which this sort order applies. Cannot be used with element, attribute or json-key.
json-key string Identifies the JSON property to which this sort order applies. This applies only to matches in JSON documents loaded using the MarkLogic REST API. Cannot be used with element, attribute or field.
score string Allowed values:
  • null
  • score-logtfidf
  • score-logtf
  • score-simple
  • score-random
annotation[] [ string ] Your comments. Annotations have no effect.
type string If you are sorting by an element or an attribute, you must specify a type property with a value corresponding to the range index type of that element or attribute (for example, xs:string, xs:dateTime, and so on).
collation string A collation URI. Optionally specify a collation whensort-order.type is xs:string; otherwise, use the collation of the query.
direction string Specify the sorting direction. Default: descending. Allowed values:
  • ascending
  • descending

For example, the following specifies a primary sort order using the element value for my-element (which needs a string range index with the specified collation), and a secondary sort order of score ascending:

{
  "options": {
    "sort-order": [
      {
        "direction": "descending",
        "type": "xs:string",
        "collation": "http://marklogic.com/collation/",
        "element": {
          "name": "my-element",
          "ns": "my-namespace",
        },
        "annotation": [ "some user comment can go here" ] },
      {
        "direction": "ascending",
        "score": null
      }
    ]
  }

starter

{
  "label": string,
  "apply": string,
  "ns": string,
  "at": string,
  "strength": integer,
  "element": string,
  "options": string,
  "tokenize": string,
  "delimiter": string
}

A starter is a component of a customer search grammar that specifies the text to use to delimit and group terms.

Key Value Description
label string Required. The joiner operator token. For example, the default grammar includes a joiner with the label 'AND', which enables queries like 'cat AND dog'.
apply string The local-name of a function to use to apply the starter.
ns string The namespace in which the apply function is defined, if using a user-defined function.
at string The module from which the apply function is imported, if using a user-defined function.
strength integer Required. The order of precedence of this starter over others. Higher strength tokens or groups are processed before lower ones.
element string A cts:query element name (for example, cts:and-query).
options string A space-separated list of options that are passed through to the underlying cts:query constructor
tokenize string Allowed values: 'word' or 'default'.
delimiter string The string to use as a delimiter for the starter.

Example:

{
  "options": {
    "grammar": {
      "starter": [
        {
          "strength": 30,
          "apply": "grouping",
          "delimiter": ")",
          "label": "("
        },
        {
          "strength": 40,
          "apply": "prefix",
          "cts-element": "cts:not-query",
          "label": "-"
        }
      ]
    }
  }
}

suggestion-source

{
  "ref": string,
  "suggestion-option": [ string ]
  "annotation": [ string ]
  "range": range-constraint,
  "word": word-constraint,
  "value": value-constraint,
  "collection": collection-constraint,
  "properties": properties-constraint,
  "custom": custom-constraint,
  "geo-elem": geo-elem-constraint,
  "geo-elem-pair": geo-elem-pair-constraint,
  "geo-attr-pair": geo-attr-pair-constraint  "word-lexicon": word-lexicon 
}

Key Value Description
ref string The name of a constraint defined by the query options.
suggestion-option [ string ] Query options to use in generating suggestions, as name-value pairs.
annotation [ string ] Your comments. Annotations have no effect.
range range-constraint Defines a constraint that overrides the one named by ref when generating search suggestions.
word word-constraint Defines a constraint that overrides the one named by ref when generating search suggestions.
collection collection-constraint Defines a constraint that overrides the one named by ref when generating search suggestions.
word-lexicon word-lexicon Defines a constraint that overrides the one named by ref when generating search suggestions.

term-definition

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

{
  "term-option": [ string ],
  "default": {
    "ref": string
    "word": word-constraint,
    "value": value-constraint,
    "range": value-constraint,
    "annotation": [ string ],
  },
  "empty": {
    "apply": string,
    "ns": string,
    "at": string
  },
  "weight": double,
  "apply": string,
  "ns": string,
  "at": string
}

Key Value Description
term-option[] [ string ] Zero or more term-options.
default object Specify a default property 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.
default.ref string A reference to a constraint defined elsewhere in the query options.
default.range range-constraint A range constraint to apply to individual terms without other constraints.
default.value value-constraint A value constraint to apply to individual terms without other constraints.
default.word word-constraint A word constraint to apply to individual terms without other constraints.
default.annotation [ string ] Your comments. Annotations have no effect.
apply string The name of a custom function to control individual term handling. If you specify a custom function name, you must also specify term.ns and term.at.
ns string Only required when using term.apply. The namespace of the function library module containing your function.
at string Only required when using term.apply. The path to the module containing your function.
empty object 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. Additionally, you create your own function to handle empty searches. To specify your own function, create a function that returns a cts:query and specify the local-name of your function, along with the namespace of the function library module, and the path to the module.
empty.apply string Allowed values:
  • all-results
  • no-results
  • your own function name
When specifying your own function, you must also specify empty.ns and empty.at.
empty.ns string Only required when empty.apply is a custom function. The namespace of the function library module containing your function.
empty.at string Only required when empty.apply is a custom function. The path to the module containing your function.
weight double A weighting factor to apply to individual terms. Default: 1.0.

An example of using a custom function custom code:

{
  "options": {
    "term": {
      "apply": "my-term-query",
      "ns": "http:\/\/custom\/search",
      "at": "\/lib\/custom.xqy",
      "empty": {
        "apply": "all-results"
      }
    }
  }
}

An example parsing to a weighted element word query on element "foo:bar":

{
  "options": {
    "term": {
      "default": {
        "word": {
          "element": {
            "ns": "foo",
            "name": "bar"
          },
          "weight": 2
        }
      },
      "empty": {
        "apply": "all-results"
      }
    }
  }
}

transform-results

{
  "apply": string,
  "ns": string,
  "at": string,
  "per-match-tokens": unsigned integer,
  "max-matches": unsigned integer,
  "max-snippet-chars": unsigned integer,
  "preferred-elements": [ element-descriptor ],
  "user-defined-param": "param-value"
}

Key Value Description
apply string

The local-name of a function to use to process a search result for the snippet output. Default: 'snippet'.

There are three other built-in snippetting functions whose behavior you can affect: "raw" (return the whole node), "empty-snippet" (return an empty snippet), and "metadata-snippet" (return the snippet from the specified element in the properties document).

ns string The namespace in which the apply function is defined, if using a user-defined function.
at string The module from which the apply function is imported, if using a user-defined function.
per-match-tokens unsigned integer Usable with the builtin snippeting functions.
max-matches unsigned integer Usable with the builtin snippeting functions.
max-snippet-chars unsigned integer Usable with the builtin snippeting functions.
preferred-elements [ element-descriptor] Usable with the builtin snippeting functions.
user-defined-param value Pass parameters to your snippeting function by including param-name:value pairs. For example, to pass in a value of 1 for the 'limit' parameter of your function: 'limit':1.

For example, to modify the default snippeting function, 'snippet':

{
  "options": {
    "transform-results": {
      "apply": "snippet",
      "per-match-tokens": "30",
      "max-matches": "4",
      "max-snippet-chars": "200",
      "preferred-elements": ""
    }
  }
}

To define a custom transformation using your own snippeting function, 'my-snippet' and pass it two parameters:

{
  "options": {
    "transform-results": {
      "apply": "my-snippet",
      "ns": "my-namespace",
      "at": "/my-snippet.xqy",
      "my-param1": "42",
      'my-param2': 'abc'
    }
  }
}

value-constraint

{
  "json-key": string,
  "element": element-descriptor,
  "attribute": attribute-descriptor,
  "field": field-descriptor,
  "weight": double,
  "fragment-scope": string,
  "term-option": string
}

Defines elements, element attributes, fields, and JSON keys on which to constrain values. You cannot create facets from a value constraint.

Key Value Description
json-key string A JSON key on which to constrain queries. Only applicable to JSON documents ingested using the MarkLogic REST API or the MarkLogic JSON API.
element element-descriptor An element on which to constrain queries, or the element containing attribute when constraining by element attribute.
attribute attribute-descriptor An element attribute on which to constrain queries. The constraint must also contain an element if there is an attribute.
field field-descriptor A field on which to constrain queries.
weight double Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to the absolute value of 16 (between -16 and 16); weights greater than 16 will have the same effect as a weight of 16. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
fragment-scope string

Allowable values:

  • properties
  • documents (default)

Set a local fragment scope for this constraint. The local fragment-scope overrides a 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.

term-option string Zero or more term-options.

Example:

{
  "options": {
    "constraint": [
      {
        "name": "my-value",
        "value": {
          "element": {
            "ns": "my-namespace",
            "name": "my-localname"
          }
        }
      }
    ]
  }
}

values-or-tuples

{
  "name": string,
  "uri": null,
  "annotation": [ string ],
  "collection": collection-constraint,
  "range": range-constraint,
  "field": field-descriptor,
  "geo-elem": geo-elem-constraint,
  "geo-elem-pair": geo-elem-pair-constraint,
  "geo-attr-pair": geo-attr-pair-constraint,
  "aggregate": {
    "apply": string,
    "udf": string
  },
  "values-option": [ string ]
}

Key Value Description
name string Required. The name that identifies this values or tuples definition.
annotation [ string ] Your comments. Annotations have no effect.
uri null Specifies the database URI lexicon.
collection collection-constraint A collection constraint with which to extract values from the database collection lexicon.
range range-constraint A range constraint with which to extract values from a range index or value lexicon.
field field-descriptor A field constraint with which to extract values from a field index or value lexicon.
geo-elem geo-elem-constraint A geospatial constraint with which to extract values from a geospatial index.
geo-elem-pair geo-elem-pair-constraint A geospatial constraint with which to extract values from a geospatial index.
geo-attr-pair geo-attr-pair-constraint A geospatial constraint with which to extract values from a geospatial index.
aggregate object Defines a builtin or user-defined aggregate function to apply to lexicon values or value co-occurrences.
aggregate.apply string Required. The name of a builtin aggregate or aggregate UDF.
aggregate.udf string The path to the native plugin library containing the implementation of the user-defined extension aggregate. Omit when using a builtin aggregate.
values-option[] [ string ] Zero or more values-options.

Example:

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "SPEAKER"
          }
        }
      }
    ]
  }
}

word-constraint

{
  "json-key": string,
  "element": element-descriptor,
  "attribute": attribute-descriptor,
  "field": field-descriptor,
  "weight": double,
  "fragment-scope": string,
  "term-option": string,
  "collation": string
}

Constrains by a word query of JSON key, element, element attribute, or field. You cannot facet on word constraints.

Key Value Description
json-key string Constrain by JSON key. Mutually exclusive of element, attribute, and field.
element element-descriptor Constrain by JSON key. Mutually exclusive of json-key and field.
attribute attribute-descriptor Constrain by JSON key. Mutually exclusive of json-key and field. An element is also required.
field field-descriptor Constrain by JSON key. Mutually exclusive of element, attribute, and field.
weight double Higher weights move search results up in the relevance order. The default is 1.0. The weight should be less than or equal to the absolute value of 16 (between -16 and 16); weights greater than 16 will have the same effect as a weight of 16. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score.
fragment-scope string

Allowable values:

  • properties
  • documents (default)

Set a local fragment scope for this constraint. The local fragment-scope overrides a 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.

term-option string Zero or more term-options.
collation string A collation URI.

word-lexicon

{
  "fragment-scope": string,
  "collation": string
}

Key Value Description
fragment-scope string Allowable values:
  • properties
  • documents (default)
collation string A collation URI. If no collation is specified, then the query uses default collation for the context in which the query is evaluated.

facet-options

Facet options are specified as properties of range and other constraints that can be used as a facet (any constraints except word, value, element-query, or property).

Legal values for a facet-option property 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

  • 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

For example:

{
  "options": {
    "constraint": [
      {
        "name": "color",
        "range": {
          "type": "xs:string",
          "facet-option": [
            "item-frequency"
          ],
          "element": {
            "ns": "",
            "name": "bodycolor"
          }
        }
      }
    ]
  }
}

term-options

Specifies the options passed into the query (for example, case-insensitive). By default, the query uses the same default options as the underlying cts:query constructors, and the defaults change based on your index configuration.

You can use term options in several places, including as a property of a term-definition and within many constraints. Within constraints, term options typically occur as property the type of constraint (for example, inside a word-constraint). You can use the /config/query service to validate a set of options.

Legal term options values are:

  • case-sensitive
  • case-insensitive
  • diacritic-sensitive
  • diacritic-insensitive
  • punctuation-sensitive
  • punctuation-insensitive
  • whitespace-sensitive
  • whitespace-insensitive
  • stemmed
  • unstemmed
  • wildcarded
  • unwilcarded
  • exact
  • lang=iso639code

For example

{
  "options": {
    "term": {
      "apply": "term",
      "empty": {
        "apply": "all-results"
      },
      "term-option":[
        "diacritic-insensitive",
        "unwildcarded"
      ]
    }
  }
}

values-options

Options that can be used in defining values and tuples. 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)

geo-options

Options that can be used when defining geo constraints. The options usable in a given geo constraint depend on the type of constraint. See the constraint for limitations.

  • coordinate-system=wgs84
  • units=miles
  • 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
  • cached
  • uncached
  • type=point
  • type=long-lat-point

« Previous chapter
Next chapter »