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

REST Application Developer's Guide — Chapter 10

Appendix B: XML Query Options Reference

This chapter defines the XML 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 in JSON. For details, see Appendix A: JSON Query Options Reference.

For more information, see Understanding the Search API in the Search Developer's Guide.

<additional-query>

An additional serialized cts:query node, which is combined using a cts:and-query with the query resulting from the query text. The query results are constrained by the specified additional-query, but any terms matching the addtional-query are not highlighted in the snippet result output. For example, the following options node constrains the results to the directory named /my/directory/:

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

If you have multiple additional-query options, they are combined using a cts:and-query.

<concurrency-level>

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. For example, the following specifies a concurrency level of 16:

<options xmlns="http://marklogic.com/appservices/search">
  <concurrency-level>16</concurrency-level>
</options>

<constraint>

The outer wrapper element for a constraint definition. Constraints are used to define facets which can be returned as part of the search results. The default is no defined constraints.

Each constraint element must have an @name attribute (required), which is the unique name of this constraint. The name can then be used in the search grammar to specify the constraint. A constraint name must be unique within the containing query options and must not contain whitespace.

The constraint element can have zero or more of the following elements:

<value>

Specifies element or attribute values on which to constrain. You cannot create facets from a value constraint. For example:

<constraint name="my-value">
    <value>
      <element ns="my-namespace" name="my-localname"/>
    </value>
</constraint> 
<constraint name="my-attribute-value">
    <value>
      <attribute ns="" name="my-attribute"/>
      <element ns="my-namespace" name="my-localname"/>
    </value>
</constraint>
<constraint name="fieldvalue">
    <value>
      <field name="fieldvalue"/>
      <weight>2.0</weight>
    </value>
</constraint>

<word>

Specifies the element, attribute, or field on which to constrain by word. You cannot create facets from a word constraint. For example:

<constraint name="name">
    <word>
      <element ns="http://widgets-r-us.com" name="name"/>
    </word>
</constraint>
<constraint name="description">
    <word>
        <field name="my-field"/>
        <weight>2.0</weight>
    </word>
</constraint>

<collection>

Specifies the collection on which to constrain. For example:

<constraint name="my-collection">
    <collection prefix="http://server.com/my-collection/"/>
</constraint>

<range>

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 for the specified element or attribute.

Each range element with a type attribute child, an optional collation attribute child (for string range indexes), an element child, an optional attribute child (for attribute ranges), and may have one or more computed-bucket children and/or one or more facet-option children (to pass options to the underlying lexicon apis). If it is a field range constraint, then the range element has a field child element with a name attribute. If it is a path-index range constraint, then the range element has a path-index child element with any namespaces defined in xmlns attributes. For example:

<options xmlns="http://marklogic.com/appservices/search">
 <constraint name="made">
    <range type="xs:dateTime"><!-- requires a dateTime range index -->
    <element ns="http://example.com" name="manufactured"/>
    <attribute ns="" name="date"/>
    <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>
 <constraint name="color">
   <range type="xs:string">
     <element ns="" name="bodycolor"/>
   </range>
 </constraint>
 <constraint name="name">
   <range type="xs:string" collation="http://marklogic.com/collation/">
     <field name="my-field-name"/>
   </range>
 </constraint>
 <constraint name="color-facet">
    <range type="xs:string" facet="true">
      <element ns="" name="bodycolor"/>
      <!-- the facet-option values are passed directly to the 
           underlying lexicon calls -->
      <facet-option>frequency-order</facet-option>
      <facet-option>descending</facet-option>
    </range>
 </constraint>
 <constraint name="fieldrange">
    <range type="xs:string"
            collation="http://marklogic.com/collation/">
        <field name="fieldrange"/>
    </range>
 </constraint>
 <constraint name="fieldrangebucket">
   <range type="xs:dateTime">
     <facet-option>ascending</facet-option>
     <field name="fieldrangebucket"/>
     <computed-bucket name="older" lt="-P365D" anchor="now">
       Older than 1 years
     </computed-bucket>
     <computed-bucket name="year" ge="-P365D" lt="-P30D" anchor="now">
       1 month to 1 year ago
     </computed-bucket>
     <computed-bucket name="month" ge="-P30D" lt="-P7D" anchor="now">
       7 to 30 days ago
     </computed-bucket>
     <computed-bucket name="week" ge="-P7D" lt="-P1D" anchor="now">
       1 to 7 days ago
     </computed-bucket>
     <computed-bucket name="today" ge="-P1D" lt="P0D" anchor="now">
       Today
     </computed-bucket>
     <computed-bucket name="future" ge="P0D" anchor="now">
       Future
     </computed-bucket>
    </range>
 </constraint>
 <constraint name="year">
   <range type="xs:gYear" facet="true">
     <path-index xmlns:my="http://example.com">
       /publication/my:meta/my:year
     </path-index>
     <!--uses same options structure, options as element, 
         element-attribute or field based range constraints -->
   </range>
 </constraint>
</options>

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.

<element-query>

Specifies a constraint that restricts the search to the specified element. You cannot create facets from an element-query constraint.

<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="sample-element-constraint">
    <element-query name="title" ns="http://my/namespace" />
  </constraint>
</options>

<properties>

Specifies a constraint that finds matches on the corresponding properties documents. You cannot create facets from a properties constraint.

<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="sample-property-constraint">
    <properties />
  </constraint>
</options>

For an additional example, see the second example below.

<geo-*>

Specifies a geospatial constraint. Must be one of the following elements: <geo-attr-pair>, <geo-elem-pair>, or <geo-elem>. If the constraint has a <heatmap> child, then it can be used as a facet, and can contain <facet-options>. For example:

<constraint name="my-geo-attr-pair">
    <!-- Uses cts:element-attribute-pair-geospatial-query, and
    cts:element-attribute-pair-geospatial-boxes for the 
    heatmap facet.  -->
  <geo-attr-pair> 
    <heatmap s="23.2" w="-118.3" n="23.3" e="-118.2" 
             latdivs="4" londivs="4"/>
    <facet-option>empties</facet-option> 
    <parent ns="ns1" name="elem1"/> 
    <lat ns="ns2" name="attr2"/> 
    <lon ns="ns3" name="attr3"/>
  </geo-attr-pair>
</constraint>
<constraint name="my-geo-elem-pair">
    <!-- Uses cts:element-pair-geospatial-query, and
    cts:element-pair-geospatial-boxes for the 
    heatmap facet (not shown).  -->
  <geo-elem-pair> 
    <parent ns="ns1" name="elem2"/> 
    <lat ns="ns2" name="attr2"/> 
    <lon ns="ns3" name="attr3"/>
  </geo-elem-pair>
</constraint>
<constraint name="my-geo-elem">
    <!-- Uses cts:element-geospatial-query, and
    cts:element-geospatial-boxes for the 
    heatmap facet (not shown).  -->
  <geo-elem> 
    <element ns="ns1" name="elem3"/> 
    <geo-option>type=long-lat-points</geo-option>
  </geo-elem>
</constraint>
<constraint name="my-geo-elem-child">
    <!-- Uses cts:element-child-geospatial-query, and
    cts:element-geospatial-boxes for the 
    heatmap facet (not shown).  -->
  <geo-elem> 
    <parent ns="ns1" name="elem4"/> 
    <element ns="ns1" name="elem5"/> 
  </geo-elem>
</constraint>

Note that when specifying coordinates using a geospatial constraint, you must put any coordinate values that contain the negative sign (-) in double-quotes, otherwise the search API will interpret the negative sign as the negation operator (when using the default grammar). For example, to specify a point using a geospatial constraint, specify qtext of the form my-geo-elem-child:"-12, 5" in your search string.

<custom>

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

<constraint name="my-custom">
  <custom facet="true">
    <parse apply="my-parse-function" 
        ns="my-function-namespace" at="path-to-module.xqy"/>
    <start-facet apply="my-start-function" 
        ns="my-function-namespace" at="path-to-module.xqy"/>
    <finish-facet apply="my-finish-function" 
        ns="my-function-namespace" at="path-to-module.xqy"/>
  </custom>
</constraint>
<!--  The start-facet and finish-facet elements can be omitted if 
      facet="false". When facet="true", the start-facet can be ommitted
      if you do not run in concurrent mode ("concurrent" option on the
      lexicon functions). 
-->

<term-option>

Specifies the options passed into the search (for example, case-insensitive). There can be zero or more term-option elements. By default, the search uses the same default options as the underlying cts:query constructors, and the defaults change based on your index configuration. You can use term-option elements in several places, including as a child of the term element and within many constraint elements (except for element-query constraints). Within constraints, term-option specifications typically occur as a child of the type of constraint (for example, in a word constraint, as a child of word. Use search:check-options to make sure the usage is legal.

Legal term option 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:

<term-option>diacritic-insensitive</term-option>

Or, for example, within in a word constraint:

<constraint name="name" 
  xmlns="http://marklogic.com/appservices/search">
  <word>
    <element ns="http://widgets-r-us.com" name="name"/>
    <term-option>case-sensitive</term-option>
  </word>
</constraint>

<facet-option>

Specifies options for facets, and is specified as a child of any range constraint or other constraint that can be used as a facet (any constraints except word, value, element-query, or property).

Legal values for a facet-option element are generally any option that can be passed into the underlying cts:range-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:

<constraint name="color" xmlns="http://marklogic.com/appservices/search">
   <range type="xs:string">
     <element ns="" name="bodycolor"/>
     <facet-option>item-frequency</facet-option>
   </range>
</constraint>

<debug>

Activates debugging mode. Additional report elements will be present in the output. Set to true to activate. The default is false.

<default-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 element can optionally have an @collation attribute, which specifies the collation of the value lexicon used during query evaluation. If no collation is specified, then the query uses default collation for the context in which the query is evaluated.

The default-suggestion-source element can have zero or more of the following child elements:

<collection>

Specifies using the collection lexicon for suggestions. For example:

<default-suggestion-source>
        <collection/>
</default-suggestion-source>

<range>

Specifies the element or attribute lexicon to use for suggestions. For example:

<default-suggestion-source>
  <range type="xs:string">
    <element ns="my-namespace" name="my-localname"/>
    <attribute ns="" name="my-attribute"/>
  </range>
</default-suggestion-source>

<word>

Specifies using the word lexicon for suggestions. This option might not scale well for a large database. For example:

<default-suggestion-source>
    <word/>
</default-suggestion-source>
<default-suggestion-source>
    <word>
        <field name="my-field"/>
    </word>
</default-suggestion-source>

<extract-metadata>

Specifies data to return in the search:metadata section of the search:response output. You can specify element or attribute content from the search hits to be returned or values from any constraints in your search.

<search:extract-metadata>
           <!-- qnames specify elements or attributes in document 
                content; multiples will be returned if they exist -->
   <search:qname elem-ns="" elem-name="bar"/>
   <search:qname elem-ns="http://example.com" elem-name="baz" 
                 attr-ns="http://ick" attr-name="id"/>
   <search:qname elem-ns="http://example.com" 
                 elem-name="blech" attr-ns="" attr-name="size"/>
           <!-- constraint-values extract values from the index 
                associated with the constraint -->
   <search:constraint-value ref="idx"/>
   <search:constraint-value ref="id"/>
   <search:qname elem-ns="http://example.com" elem-name="foo"/>
</search:extract-metadata> 

<forest>

A single forest ID to pass into cts:search. To specify multiple forests, use multiple forest elements in the options node.

The value must be an xs:unsignedLong type.

<fragment-scope>

Controls the scope over which to search. Valid values are documents and properties, and the default value is documents.

You can specify fragment-scope as a child of <options>, and that sets a global fragment scope which 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 also specify fragment-scope as a child of <range>, <value>, or <word> constraints. Specifying as a child of one of these constraints sets a local fragment scope for that 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. For example:

<options xmlns="http://marklogic.com/appservices/search">
<fragment-scope>documents</fragment-scope>
  <constraint name="last-modified">
    <range type="xs:dateTime">
      <element ns="http://marklogic.com/xdmp/property"
               name="last-modified"/>
      <fragment-scope>properties</fragment-scope>
    </range>
  </constraint>
  <debug>true</debug>
</options>

<grammar>

Wrapper element for grammar definition. The default grammar defines "Google-style" parsing.

The grammar element has a quotation element that specifies the quotation character with which to surround phrases. The text between the quotation characters is treated as a phrase. You cannot specify a search that includes the quotation character; for example, to specify a search that includes the double quotation character (the default quotation character), modify your grammar to use a different quotation character.

The grammar element can have 0 or more joiner elements and 0 or more starter elements.

The grammar element should contain at least one joiner, starter, or implicit child element. If the grammar element is present but empty, then the grammar does nothing, and the search is parsed according to the term option.

<implicit>

Specifies the cts:query to use to implicitly combine terms when no joiner is specified in the qtext. Use this to modify the implicit search grammar (for example, if you want the default search to be a cts:or-query instead of a cts:and-query).

The following is an example of a options element with an implicit specification for a cts:or-query:

<options xmlns="http://marklogic.com/appservices/search">
  <grammar>
    <implicit>
      <cts:or-query strength="10" xmlns:cts="http://marklogic.com/cts"/>
    </implicit>
  </grammar>
</options>

<joiner>

Specifies what text to use to combine terms together, and what is the underlying cts:query constructor to use to join the terms together. You specify the function to call for the joiner with the apply attribute, along with optional ns (for the module namespace) and at (for the module path) attributes. Additionally, the strength attribute determines the order of precedence over other joiner elements, the optional options attribute specifies a space-separated list of options that are passed through to the underlying cts:query constructor, and the element attribute specifies the cts:query element name (for example, cts:and-query).

<starter>

Specifies what text to use to delimit and group terms. You specify the function to call for the starter with the apply attribute, along with optional ns (for the module namespace) and at (for the module path) attributes. Additionally, the strength attribute determines the order of precedence over other starter elements, the optional options attribute specifies a space-separated list of options that are passed through to the underlying cts:query constructor, the element attribute specifies the cts:query element name (for example, cts:and-query), and the delimiter attribute specifies the string to use as a delimiter for the starter.

The following is an example of a grammar element.

<grammar xmlns="http://marklogic.com/appservices/search">
  <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>
  <joiner strength="30" apply="infix" element="cts:near-query" 
    tokenize="word">NEAR</joiner>
  <joiner strength="30" apply="near2"
    element="cts:near-query">NEAR/</joiner>
  <joiner strength="50" apply="constraint">:</joiner>
  <joiner strength="50" apply="constraint" compare="LT"
    tokenize="word">LT</joiner>
  <joiner strength="50" apply="constraint" compare="LE" 
    tokenize="word">LE</joiner>
  <joiner strength="50" apply="constraint" compare="GT" 
    tokenize="word">GT</joiner>
  <joiner strength="50" apply="constraint" compare="GE" 
    tokenize="word">GE</joiner>
  <joiner strength="50" apply="constraint" compare="NE" 
    tokenize="word">NE</joiner>
</grammar>

<operator>

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.

An operator element can have one or more state elements. Each state element can have one of the following elements:

  • additional-query
  • debug
  • forest
  • page-length
  • quality-weight
  • searchable-expression
  • sort-order
  • transform-results

In the following example, a search for special:hello constrains the search by the "hello world" query, and a search for special:forest constrains the search to the forest names "my-forest".

<operator name="special">
  <state name="hello">
    <additional-query>{cts:word-query("hello world")}
    </additional-query>
  </state>
  <state name="forest">
    <forest>{xdmp:forest("my-forest")}</forest>
  </state>
</operator>

<page-length>

Specifies the number of results per page. The default value is 10.

The value must be an xs:unsignedInt type.

<quality-weight>

Specifies a a weighting factor to use in the query. The default value is 1.0.

The value must be an xs:double type.

<return-constraints>

Include original constraint definitions in the results. The default is false.

The value must be an xs:boolean type.

<return-facets>

Include resolved facets in the results. The default is true.

The value must be an xs:boolean type.

<return-metrics>

Include statistics in the results. The default is true.

The value must be an xs:boolean type.

<return-plan>

Include xdmp:plan output in the results. The default is false. The output is useful in examining the evaluation plan of the search.

The value must be an xs:boolean type.

<return-qtext>

Include the original query text in the results. The default is true.

The value must be an xs:boolean type.

<return-query>

Include the XML query representation in the results. The default is false.

The value must be an xs:boolean type.

<return-results>

Include search results in the output. (Use transform-results to specify how each result should be formatted.) The default is true.

The value must be an xs:boolean type.

<return-similar>

Include with each search result a list of URLs of similar documents in the database. The default is false.

The value must be an xs:boolean type.

<search-option>

For advanced users, a single option to be passed in with cts:search calls (for example, filtered, unfiltered, score-logtfidf, and so on). To pass in multiple options, specify multiple search-options elements in the options node. The default is no additional options. For example:

<search-option>unfiltered</search-option>
<search-option>score-logtf</search-option>

<searchable-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 using xmlns attributes. For example:

<searchable-expression xmlns:ex="http:example.com"
    xmlns:com="http://company.com">/ex:orders/com:company
</searchable-expression>

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>

Set the default sort order. The first such element 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. If you are sorting by an element or an attribute, you must specify a type attribute with a value corresponding to the range index type of that element or attribute (for example, xs:string, xs:dateTime, and so on). If the corresponding range index is of type xs:string, then you can optionally specify a collation attribute (otherwise the collation of the query is used). To change the sorting direction, specify an optional direction attribute with a value of descending (the default) or ascending.

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

The sort-order element 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 a score child, it specifies to sort by the score of the search result. 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. Additionally, the sort-order element can have 0 or more annotation elements (to add comments, for example).

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:

<sort-order type="xs:string" 
collation="http://marklogic.com/collation/"
            direction="ascending">
  <element ns="my-namespace" name="my-element"/>
  <annotation>some user comment can go here</annotation>
</sort-order>
<sort-order direction="ascending">
  <score/>
</sort-order>

<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 attribute corresponding to a named constraint (one suggestion-source per named constraint). A suggestion-source can have one of the following child elements: collection, range, word, or word-lexicon.

For example, the following overrides the tag: prefix, using the range index for the attribute shortname instead of the one for name when using search:suggest:

<constraint name="tag">
  <range collation="http://marklogic.com/collation/" 
          type="xs:string" facet="true">
    <element ns="my-namespace" name="my-element"/>
    <attribute ns="" name="name"/>
  </range>
</constraint>
<suggestion-source ref="tag">
  <range collation="http://marklogic.com/collation/" 
          type="xs:string" facet="true">
    <element ns="my-namespace" name="my-element"/>
    <attribute ns="" name="shortname"/>
  </range>
</suggestion-source>

<term>

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.

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 in the apply attribute, the namespace of the function library module in the ns attribute, and the path to the module in the at attribute.

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.

Additionally, you can specify zero or more term-option elements to control the behavior of the search terms.

For example:

<term>
   <empty apply="no-results" />
   <term-option>diacritic-insensitive</term-option>
   <term-option>unwildcarded</term-option>
</term>

The following examples show default term specifications for terms with no constraints:

Term element, parsing to a weighted word query.

<term xmlns="http://marklogic.com/appservices/search>
    <default>
        <word>
            <weight>2.0</weight>
        </word>
    </default>
    <empty apply="all-results"/>
</term>

Term element, parsing to a weighted element word query on element "foo:bar":

<term xmlns="http://marklogic.com/appservices/search">
    <default>
        <word>
            <element ns="foo" name="bar"/>
            <weight>2.0</weight>
        </word>
    </default>
    <empty apply="all-results"/>
</term>

Term element, parsing to an element-values query scoped to the properties fragment:

<term xmlns="http://marklogic.com/appservices/search">
    <default>
        <value>
            <element ns="http://example.com" name="copyright-year"/>
            <fragment-scope>properties</fragment-scope>
        </value>
    </default>
    <empty apply="all-results"/>
</term>

Term element, parsing to a field word query via an existing field-word constraint:

<term>     
    <default ref="my-field-word-constraint"/>
    <empty apply="all-results"/>
</term>

Term element, referencing custom code (<default> configuration will be ignored in a conflict).

<term apply="my-term-query" ns="http://custom/search" 
   at="/lib/custom.xqy">     
    <default ref="my-field-word-constraint"/>
    <empty apply="all-results"/>
</term>

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

To use a different snippetting function, you must use either search:search or search:resolve; the search:snippet function always uses the default snippeting function. Specify the local-name of the function to pass in as the value of the apply attribute, the namespace as the value of the ns attribute, and the path to the module as the value of the at attribute. You can pass in parameters to the function by specifying zero or more param child elements (the parameters are passed in in the order specified).

In addition to the default snippetting function, there are three other built-in snippetting functions: apply="raw" (return the whole node), apply="empty-snippet" (return an empty snippet), and apply="metadata-snippet" (return the snippet from the specified element in the properties document).

The following example specifies a custom snippetting function:

<transform-results apply="snippet" ns="my-namespace"
                   at="/my-library.xqy"/>

The following example specifies a snippet returning the element named my-element in the properties document:

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

<tuples>

Identifies values range indexes or lexicons in which to find value co-occurrences. A <values-response> of co-occurrences is included in the search response. You can specify range, collection, geospatial, and uri indexes or lexicons.

A <tuples/> element can include an <aggregate/> child to specify an aggregate builtin or user-defined function to apply to the values. You can also specify one or more options using <values-options/>; see cts:values for a list of available options.

The following example specifies co-occurrences between editor and author element values. attribute range index and the URI lexicon.

<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>
    <lexicon-option>limit=10</lexicon-option>
  </tuples>
</options>

<values>

Identifies a values range index or lexicon with which to constrain the search. A <values-response> of matching index or lexicon values is included in the search response. You can specify range, collection, geospatial, and uri indexes or lexicons.

A <values/> element can include an <aggregate/> child to specify an aggregate builtin or user-defined function to apply to the values. You can also specify one or more options using <values-options/>; see cts:values for a list of available options.

The following example specifies values from an element attribute range index and from the URI lexicon. For more examples, see search:values.

<options xmlns="http://marklogic.com/appservices/search">
    <!-- element attribute range index values -->
    <values name="example">
        <range type="xs:integer">
            <element ns="" name="game"/>
            <attribute ns="" name="runs"/>
        </range>
        <aggregate apply="sum"/>
    </values>

    <!-- uri lexicon values -->
    <values name="uri">
      <uri/>
      <values-option>limit=10</values-option>
    </values>  
</options>

« Previous chapter