This page was generated
January  28,  2016
4:08  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Search

The Search function module is installed as the following file:

  • install_dir/Modules/MarkLogic/appservices/search/search.xqy

where install_dir is the directory in which MarkLogic Server is installed.

To use the search.xqy module in your own XQuery modules, include the following line in your XQuery prolog:

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

The Search functions are used to create search high-level results, facets, snippets, and other search-related items.

Function Summary
search:check-options This function verifies that options XML is properly structured.
search:estimate This function quickly estimates the number of hits a query will return.
search:get-default-options This function returns the default options XML.
search:parse This function parses query text according to given options and returns the appropriate cts:query XML.
search:remove-constraint This function safely removes a token from query text, ensuring that grammar elements (AND, OR, quotes, parentheses) are handled properly.
search:resolve This function is the same as search:search, except that it takes a parsed and annotated cts:query XML node or a structured search search:query XML node as input.
search:resolve-nodes This function performs the same search as search:search, but it takes a parsed and annotated cts:query XML node or a structured search search:query XML node as input and returns the actual result nodes from the database.
search:search This function parses and invokes a query according to specified options, returning up to $page-length result nodes starting from $start.
search:snippet This function extracts matching text from the result node based on options, and returns the matches wrapped in a containing node, with highlights tagged.
search:suggest This function returns a sequence of suggested text strings that match a wildcarded search for the $qtext input, ready for use in a user interface.
search:unparse This function turns a serialized and annotated cts:query (typically from search:parse) back into query text according to the specified rules.
search:values This function returns lexicon values and co-occurrences, and allows you to calculate aggregates based on the lexicon values.
Function Detail
search:check-options(
$options as element(search:options),
[$strict as xs:boolean?]
)  as   element(search:report)*
Summary:

This function verifies that options XML is properly structured. Used in debugging, normally not in production. Returns the empty sequence on success, otherwise it returns one or more error messages inside <report> elements.

Parameters:
$options : Options to define the search grammar and control the search. See description for $options for the function search:search.
$strict (optional): If true, index settings are additionally verified. The default is false.

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

search:check-options(
    <options xmlns="http://marklogic.com/appservices/search">
      <grammar>
        <joiner strength="10" apply="infix"
                element="cts:or-query">|</joiner>
        <joiner strength="20" apply="infix"
                element="cts:and-query">&amp;</joiner>
      </grammar>
    </options>)

=>

()

      

search:estimate(
$cts-query as element(),
[$options as element(search:options)?]
)  as   xs:unsignedLong
Summary:

This function quickly estimates the number of hits a query will return. The result is unfiltered and reflects the index resolution of the search (like xdmp:estimate).

Parameters:
$cts-query : A serialized and annotated cts:query, typically the result of a call to search:parse.
$options (optional): Options to define the search grammar and control the search. See description for $options for the function search:search.

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

search:estimate(search:parse("Vannevar Bush"))

=>

12345

      

search:get-default-options(  ) as  element(search:options)
Summary:

This function returns the default options XML. Default options do not contain any constraints or anything else that requires specific index settings.

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

search:get-default-options()

=>

<options xmlns="http://marklogic.com/appservices/search">
  ...
</options>

      

search:parse(
$qtext as xs:string+,
[$options as element(search:options)?],
[$output as xs:string?]
)  as   element()?
Summary:

This function parses query text according to given options and returns the appropriate cts:query XML.

Parameters:
$qtext : The query text to parse. This may be a sequence, to accommodate more complex search UI. Multiple query texts will be ANDed together.
$options (optional): Options to define the search grammar and control the search. See description for $options for the function search:search.
$output (optional): The format of the parsed query, either the string cts:query or search:query. The search:query output is the structured query XML output. The default is cts:query, which is the annotated cts:query XML output.

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

search:parse("tag:technology AND format:pdf",
   <options xmlns="http://marklogic.com/appservices/search">
     <constraint name="tag">
       <collection/>
     </constraint>
     <constraint name="format">
        <value>
          <element ns="http://purl.org/dc/elements/1.1/" name="tag"/>
        </value>
     </constraint>
   </options>
) 
=>

<cts:and-query qtextjoin="AND" strength="20" 
	xmlns:cts="http://marklogic.com/cts">
  <cts:collection-query qtextpre="tag:" qtextref="cts:annotation">
   <cts:annotation qtextref="following-sibling::cts:uri"/>
   <cts:uri>technology</cts:uri>
  </cts:collection-query>
  <cts:element-value-query qtextpre="format:" qtextref="cts:annotation">
   <cts:element xmlns:_1="http://purl.org/dc/elements/1.1/">_1:tag</cts:element>
   <cts:annotation qtextref="following-sibling::cts:text"/>
   <cts:text>pdf</cts:text>
  </cts:element-value-query>
</cts:and-query>

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

search:parse("hello tag:technology AND format:pdf",
   <options xmlns="http://marklogic.com/appservices/search">
     <constraint name="tag">
       <collection/>
     </constraint>
     <constraint name="format">
        <value>
          <element ns="http://purl.org/dc/elements/1.1/" name="tag"/>
        </value>
     </constraint>
   </options>, "search:query")

=> the following structured query:

<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:and-query>
    <search:term-query>
      <search:text>hello</search:text>
    </search:term-query>
    <search:and-query>
      <search:collection-constraint-query>
        <search:constraint-name>tag</search:constraint-name>
        <search:uri>technology</search:uri>
      </search:collection-constraint-query>
      <search:value-constraint-query>
        <search:constraint-name>format</search:constraint-name>
        <search:text>pdf</search:text>
      </search:value-constraint-query>
    </search:and-query>
  </search:and-query>
</search:query>


  

search:remove-constraint(
$qtext as xs:string,
$ptext as xs:string,
$options as element(search:options)?
)  as   xs:string?
Summary:

This function safely removes a token from query text, ensuring that grammar elements (AND, OR, quotes, parentheses) are handled properly.

Parameters:
$qtext : The full query text string.
$ptext : A token to remove from full query text.
$options : Options to define the search grammar and control the search. See description for $options for the function search:search.

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

let $options :=
 <options xmlns="http://marklogic.com/appservices/search">
   <constraint name="tag">
     <word>
      <element ns="http://widgets-r-us.com" name="tag"/>
     </word>
   </constraint>
   <constraint name="year">
     <value>
      <element ns="http://widgets-r-us.com" name="year"/>
     </value>
   </constraint>
 </options>
return
search:remove-constraint("tag:foo AND (year:2007 OR year:2008)",
   "year:2008", $options)

=>
"tag:foo AND year:2007"


search:resolve(
$query as element(),
[$options as element(search:options)?],
[$start as xs:unsignedLong?],
[$page-length as xs:unsignedLong?]
)  as   element(search:response)
Summary:

This function is the same as search:search, except that it takes a parsed and annotated cts:query XML node or a structured search search:query XML node as input.

Parameters:
$query : Either a serialized and annotated cts:query, or a structured query (search:query). You can generate either form of query as the result of a call to search:parse.
$options (optional): Options to define the search grammar and control the search. See description for $options for the function search:search.
$start (optional): The index of the first hit to return. The default is 1.
$page-length (optional): The maximum number of hits to return. The default is 10. If the value is 0, no results are returned.

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

search:resolve(search:parse("Vannevar Bush"),
    <options xmlns="http://marklogic.com/appservices/search">
      <return-results>false</return-results>
      <return-facets>true</return-facets>
    </options>)

=>

<search:response total="1234" start="1" page-length="10" xmlns=""
        xmlns:search="http://marklogic.com/appservices/search">
  <search:facet name="date">
	  <search:facet-value value="today" count="1000">
		  Today</search:facet-value>
	  <search:facet-value value="yesterday" count="234">
		  Yesterday</search:facet-value>
	  <search:facet-value value="thismonth" count="1234">
		  This Month</search:facet-value>
  <search:/facet>
    ...
</search:response>

      
Example:
(: structured query example, plain search for "hello" :)
xquery version "1.0-ml";
import module namespace search = "http://marklogic.com/appservices/search"
     at "/MarkLogic/appservices/search/search.xqy";

let $struct-query :=
<query xmlns="http://marklogic.com/appservices/search">
 <term-query>
  <text>hello</text>
 </term-query>
</query>
return
search:resolve($struct-query)
=> returns the a search:response node that matches a query for "hello"      
      

      

search:resolve-nodes(
$query as element(),
[$options as element(search:options)?],
[$start as xs:unsignedLong?],
[$page-length as xs:unsignedLong?]
)  as   node()*
Summary:

This function performs the same search as search:search, but it takes a parsed and annotated cts:query XML node or a structured search search:query XML node as input and returns the actual result nodes from the database.

Parameters:
$query : Either a serialized and annotated cts:query, or a structured query (search:query). You can generate either form of query as the result of a call to search:parse.
$options (optional): Options to define the search grammar and control the search. See description for $options for the function search:search.
$start (optional): The index of the first hit to return. The default is 1.
$page-length (optional): The maximum number of hits to return. The default is 10. If the value is 0, no results are returned.

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

search:resolve-nodes(search:parse("Vannevar Bush"),
    <options xmlns="http://marklogic.com/appservices/search">
      <return-results>false</return-results>
      <return-facets>true</return-facets>
    </options>)

=>

... sequence of document nodes ...


      
Example:
(: structured query example, plain search for "hello" :)
xquery version "1.0-ml";
import module namespace search = "http://marklogic.com/appservices/search"
     at "/MarkLogic/appservices/search/search.xqy";

let $struct-query :=
<query xmlns="http://marklogic.com/appservices/search">
 <term-query>
  <text>hello</text>
 </term-query>
</query>
return
search:resolve-nodes($struct-query)
=> returns the nodes that match a query for "hello"      

      

search:search(
$qtext as xs:string+,
[$options as element(search:options)?],
[$start as xs:unsignedLong?],
[$page-length as xs:unsignedLong?]
)  as   element(search:response)
Summary:

This function parses and invokes a query according to specified options, returning up to $page-length result nodes starting from $start.

Parameters:
$qtext : The query text to parse. This may be a sequence, to accommodate more complex search UI. Multiple query texts are combined with an AND operator.
$options (optional): Options to define the search grammar and control the search.

The following is a summary of the XML structure of an options node:

<additional-query>
An additional serialized cts:query node, which is combined using a cts:and-query with the query resulting from the specified $qtext. 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("/my/directory/")}
  </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 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"/>
      <weight>2.0</weight>
    </word>
</constraint>
<constraint name="description">
    <word>
        <field name="my-field"/>
    </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>, <geo-elem>, or <geo-path>. 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>
<constraint name="my-geo-path">
    <!-- Uses cts:element-child-geospatial-query, and
    cts:element-geospatial-boxes for the 
    heatmap facet (not shown).  -->
  <geo-path>
    <path-index>/a/b</path-index> 
  </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 negaitve 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 a constrained word lexicon for suggestions. For example:
<default-suggestion-source>
  <word>
    <field name="my-field"/>
  </word>
</default-suggestion-source>
<word>
Specifies using the database-wide word lexicon for suggestions. This option might not scale well for a large database. For example:
<default-suggestion-source>
  <word-lexicon/>
</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.

A grammar element should contain at least one joiner, starter, or implicit child element. If the grammer 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 weighting factor to use in the query. The default value is 1.0.

The value must be an xs:double type.

<result-decorator>
Specifies a custom search result decorator XQuery function.
<result-decorator apply="decorator" ns="http://my/ns" at="/my/path" />
<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 criteria are returned. The expression must be an inline, fully searchable XPath expression. 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 apply to 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 decending (the default) or ascending.

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). You should not apply sort-order to a field backed by a field range index with more than one included element.

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.

The term definition can include a fragment-scope that limits query scope to the documents or properties fragments. For details, see 'Fragment Scope Option' in the Search Developer's Guide

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>
 
$start (optional): The index of the first hit to return. If 0, treated as 1. If greater than the number of results, no results will be returned. The default is 1.
$page-length (optional): The maximum number of hits to return. The default is 10. If the value is 0, no results are returned.

Usage Notes:

The output of search:search returns a <response> element, which in turn contains a total attribute. The value of the total attribute is an estimate, based on the index resolution of the query, and it is not filtered for accuracy. The accuracy of the index resolution depends on the index configuration of the database, on the query, and on the data being searched.


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

search:search("Vannevar Bush",
    <options xmlns="http://marklogic.com/appservices/search">
      <return-results>false</return-results>
      <return-facets>true</return-facets>
    </options>)

=>

<search:response total="1234" start="1" page-length="10" xmlns=""
        xmlns:search="http://marklogic.com/appservices/search">
  <search:facet name="date">
	  <search:facet-value value="today" count="1000">
		  Today</search:facet-value>
	  <search:facet-value value="yesterday" count="234">
		  Yesterday</search:facet-value>
	  <search:facet-value value="thismonth" count="1234">
		  This Month</search:facet-value>
  <search:/facet>
    ...
</search:response>

    
Example:
(: properties constraint example :)
xquery version "1.0-ml";
(: create a document with some properties to test with :)
xdmp:document-insert("/foo.xml", <foo>hello</foo>);
xdmp:document-set-properties("/foo.xml", <blah>boo</blah>);

(: do a properties constraint search :)
import module namespace search = "http://marklogic.com/appservices/search"
     at "/MarkLogic/appservices/search/search.xqy";

search:search("hello sample-property-constraint:boo",
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="sample-property-constraint">
    <properties />
  </constraint>
  <debug>true</debug>
</options>)

=>

<search:response total="1" start="1" page-length="10" xmlns=""
	xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/foo.xml" 
		path="fn:doc(&quot;/foo.xml&quot;)" score="328" 
		confidence="0.807121" fitness="0.901397">
    <search:snippet>
	    <search:match path="fn:doc(&quot;/foo.xml&quot;)/foo">
		    <search:highlight>hello</search:highlight></search:match>
    </search:snippet>
  </search:result>
  <search:qtext>hello sample-property-constraint:boo</search:qtext>
  <search:report id="SEARCH-FLWOR">(cts:search(fn:collection(), 
	  cts:and-query((cts:word-query("hello", ("lang=en"), 1), 
	  cts:properties-query(cts:word-query("boo", ("lang=en"), 1))), 
	  ()), ("score-logtfidf"), 1))[1 to 10]
  </search:report>
  <search:metrics>
    <search:query-resolution-time>PT0.647S</search:query-resolution-time>
    <search:facet-resolution-time>PT0S</search:facet-resolution-time>
    <search:snippet-resolution-time>PT0.002S</search:snippet-resolution-time>
    <search:total-time>PT0.651S</search:total-time>
  </search:metrics>
</search:response>


    

search:snippet(
$result as node(),
$cts-query as schema-element(cts:query),
[$options as element(search:transform-results)?]
)  as   element(search:snippet)
Summary:

This function extracts matching text from the result node based on options, and returns the matches wrapped in a containing node, with highlights tagged.

Parameters:
$result : A node from which to pull matching snippets from.
$cts-query : A serialized and annotated cts:query, typically the result of a call to search:parse.
$options (optional): Options to define the search grammar and control the search. See description for $options for the function search:search. Note that you cannot specify the apply attribute on the transform-results option with search:snippet; to use a different snippetting function, use search:search or search:resolve instead.

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

search:snippet(
 <html xmlns="http://www.w3.org/1999/xhtml">
     <head>
        <title>Page Title</title>
     </head>
     <body>
       <div>Query terms in this div will be ignored for snippeting.</div>
       <p>Text surrounding query terms is highlighted and truncated
               according to configuration.</p>
     </body>
     </html>,
      search:parse("term"),
      <transform-results apply="snippet"
      xmlns="http://marklogic.com/appservices/search">
          <per-match-tokens>30</per-match-tokens>
          <max-matches>4</max-matches>
          <max-snippet-chars>200</max-snippet-chars>
          <preferred-elements>
              <element name="p" ns="http://www.w3.org/1999/xhtml"/>
          </preferred-elements>
      </transform-results>)

=>

<search:snippet xmlns:search="http://marklogic.com/appservices/search">
  <search:match path="/*:html/*:body/*:p[1]">
      Text surrounding query
    <search:highlight>terms</search:highlight>
      is highlighted and truncated according to configuration.
  </search:match>
</search:snippet>

  

search:suggest(
$qtext as xs:string+,
[$options as element(search:options)?],
[$limit as xs:unsignedInt?],
[$cursor-position as xs:unsignedInt?],
[$focus as xs:positiveInteger?],
[$query as element(search:query)*]
)  as   xs:string*
Summary:

This function returns a sequence of suggested text strings that match a wildcarded search for the $qtext input, ready for use in a user interface. Typically this is used for type-ahead applications to provide the user suggestions while entering terms in a search box.

Parameters:
$qtext : One or more strings of query text. The first string in the list (or the string corresponding to the position in the $focus parameter value) is used to find matching suggestions by performing a lexicon match query. The other strings (if any) are parsed as a cts:query, with the resulting queries combined with a cts:and-query, and the resulting cts:query is passed as a constraining query to the lexicon match query, restricting the suggestions to fragments that match the cts:query. Typically, each item in the sequence corresponds to a single text entry box in a user interface.
$options (optional): Options to define the search grammar and control the search. See description for $options for the function search:search. In particular, the default-suggestion-source and suggestion-source options are specific to search:suggest.
$limit (optional): The maximum number of suggestions to return. The default is 10.
$cursor-position (optional): The position of the cursor, from point of origin, in the text box corresponding to the $focus parameter. This is used to determine on which part of the query text to perform a lexicon match. The default is the string length of the $focus string (all of the string).
$focus (optional): If there are multiple $qtext strings, the index of the string corresponding to the text box that has current "focus" in the user interface (and therefore containing a partial query text for completion). The default is 1 (the first $qtext string.
$query (optional): Zero or more structured queries with which to constrain the scope of the match for qtext. Default: No additional constraints on the suggestions.

Usage Notes:

On large databases, the performance of using a word lexicon for suggestions will probably be slower than using a value lexicon. This can be very application specific, and in some cases the performance might be good, but in general, value lexicons (range constraints) will perform much better than word lexicons (word constraints) with search:suggest. Therefore, MarkLogic recommends using value lexicons for suggestions, not word lexicons.

The performance of search:suggest is highly data-dependent. The best performing suggestion sources are value lexicons (range indexes) that use the codepoint collation. Performance is also impacted based on the number of matches, and it can help to design the interaction between search:suggest and the UI so that suggestions are given after a minimum of 3 characters are entered (that is, the lexicon match calls will have at least 3 characters). Again, this is quite data-dependent, so you should try it on a large data set with your own data.

The output of search:suggest is a sequence of query text strings, not a sequence of words. Each query text string can include quoted text, such as phrases. The output of search:suggest is appropriate to pass into the first argument of search:search, including any quoted phrases. For example, if you have a suggestion that returns multi-word phrases (for example, from range element index values), then the suggestion will quote the phrase.

For more details, see 'Search Term Completion Using search:suggest' in the Search Developer's Guide.

Use the query parameter to supply structured queries with which to constrain the returned results. Only suggestions that match these additional queries are returned. For more information about structured queries, see 'Searching Using Structured Queries' in the Search Developer's Guide.


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

let $options := 
<search:options xmlns="http://marklogic.com/appservices/search">
 <default-suggestion-source>
   <range collation="http://marklogic.com/collation/" 
          type="xs:string" facet="true">
      <element ns="http://marklogic.com/xdmp/apidoc" 
               name="function"/>
      <attribute ns="" name="name"/>
   </range>
 </default-suggestion-source>
</search:options>
return
search:suggest("docu", $options)

=> a sequence of strings representing query text:

document-add-collections
document-add-permissions
document-add-properties
document-checkin
document-checkout

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

let $options := 
<search:options xmlns="http://marklogic.com/appservices/search">
 <default-suggestion-source>
    <range collation="http://marklogic.com/collation/" 
          type="xs:string" facet="true">
      <element ns="" name="hello"/>
   </range>
 </default-suggestion-source>
</search:options>
return
search:suggest("a", $options)

=>  a sequence of strings representing query text:
"and that"
"and this"


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

search:suggest(("ta","foo"),(),5)

=>  a sequence of strings representing query text:

tab
table
tadpole
tag


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

search:suggest(("table","foo"),(),(),5,2)

=>  a sequence of strings representing query text:

food
fool
foolhardy
foolish
foolishness


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

(: 
given a document created with the following:

xdmp:document-insert("/test.xml",
<root>
  <my:my-element xmlns:my="my-namespace" shortname="fool"/>
  <my:my-element xmlns:my="my-namespace" shortname="food"/>
  <my:my-element xmlns:my="my-namespace" shortname="foolhardy"/>
  <my:my-element xmlns:my="my-namespace" shortname="foolish"/>
  <my:my-element xmlns:my="my-namespace" shortname="foolishness"/>
  <my:my-element xmlns:my="my-namespace" name="foody"/>
</root>)
:)
let $options := 
<options xmlns="http://marklogic.com/appservices/search">
 <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>
</options>
return	  
search:suggest("tag:foo", $options)

=>
suggestions to complete tag: from the range index on the 
"shortname" attribute (notice "foody" is not in the answer):

tag:food
tag:fool
tag:foolhardy
tag:foolish
tag:foolishness

      

search:unparse(
$qtree as element()
)  as   xs:string+
Summary:

This function turns a serialized and annotated cts:query (typically from search:parse) back into query text according to the specified rules.

Parameters:
$qtree : A serialized and annotated cts:query, typically the result of a call to search:parse.

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

search:unparse(
    search:parse("tag:technology AND format:pdf",
    search:get-default-options()))

=>

"tag:technology AND format:pdf"

      

search:values(
$spec-name as xs:string,
$options as element(search:options),
[$query as element(search:query)?],
[$limit as xs:unsignedLong?],
[$start as xs:anyAtomicType?],
[$page-start as xs:unsignedLong?],
[$page-length as xs:unsignedLong?]
)  as   element(search:values-response)
Summary:

This function returns lexicon values and co-occurrences, and allows you to calculate aggregates based on the lexicon values.

Parameters:
$spec-name : The name of a specification in the supplied options node (a <values> or <tuples> specification).
$options : Options to define the search grammar and control the search. See description for $options for the function search:search Must include the $spec-name definitions supplied in the first parameter.

The following is sample options node that includes lexicon specifications:

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

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

     <!-- collection lexicon -->
    <values name="coll">
      <collection/>
      <values-option>limit=10</values-option>
    </values>
 
    <!-- user-supplied aggregate -->
    <values name="udf">
        <range type="xs:double">
            <element ns="" name="test"/>
        </range>
        <aggregate apply="mycalc" udf="sampleplugin"/>
    </values>
 
    <!-- co-occurrences -->
    <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>

    <!-- path -->
    <values name="datepath">
      <range type="xs:dateTime">
        <facet-option>descending</facet-option>
        <facet-option>limit=10</facet-option>
        <path-index 
          xmlns:d="http://purl.org/dc/elements/1.1/"
          >/document/d:date</path-index>
       </range>
    </values>

    <!-- field -->
    <values name="field-range">
        <range type="xs:dateTime">
            <field name="range"/>
        </range>
    </values>
 
    <return-frequency>false</return-frequency>
    <return-values>true</return-values>
    <return-aggregates>true</return-aggregates>
</options> 
$query (optional): A structured query to apply as a constraint when retrieving lexicon values.
$limit (optional): The maximum number of values to return. The default is no limit.
$start (optional): A starting value in the lexicon. If the $start value is not present in the lexicon, the values are returned starting with the next value in the range index after where $start would logically appear. If no $start value is supplied, the values are returned starting with the first value in the range index.
$page-start (optional): The index of the first value to return from within the subset defined by limit and start. Default: 1.
$page-length (optional): The number of values to return within the subset of values defined by limit and start. Default: Return all values.

Usage Notes:

For details and more examples, see 'Returning Lexicon Values With search:values' in the Search Developer's Guide.

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

let $options := 
<options xmlns="http://marklogic.com/appservices/search">
  <values name="uri">
    <uri/>
    <aggregate apply="min"/>
  </values>
</options>
return
search:values("uri", $options)
=>
<values-response name="uri" type="xs:string" 
  xmlns="http://marklogic.com/appservices/search" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <distinct-value frequency="2">/date.xml</distinct-value>
  <distinct-value frequency="2">/gajanan.xml</distinct-value>
  <distinct-value frequency="2">/test/keys.json</distinct-value>
  <aggregate-result name="min">/date.xml</aggregate-result>
  <metrics>
    <values-resolution-time>PT0.000193S</values-resolution-time>
    <aggregate-resolution-time>PT0.000409S</aggregate-resolution-time>
    <total-time>PT0.001987S</total-time>
  </metrics>
</values-response>
    
Example:
xquery version "1.0-ml";
import module namespace search = "http://marklogic.com/appservices/search"
     at "/MarkLogic/appservices/search/search.xqy";

(: 
   Requires URI lexicon and string range index on "hello". 
   This finds the values for "hello" for all documents that 
   have the element "hello".
:)
let $options := 
<options xmlns="http://marklogic.com/appservices/search">
  <tuples name="hello">
    <uri/>
    <range type="xs:string" collation="http://marklogic.com/collation/">
      <element ns="" name="hello"/>
    </range>
  </tuples>
</options>
let $values:= search:values("hello", $options)
return (
$values, 
fn:doc($values/search:tuple/search:distinct-value/fn:data()) )
=>
<values-response name="hello" 
  xmlns="http://marklogic.com/appservices/search" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <tuple frequency="1">
    <distinct-value xsi:type="xs:string" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      >/date.xml</distinct-value>
    <distinct-value xsi:type="xs:string" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      >2012-08-10-05:00</distinct-value>
  </tuple>
  <tuple frequency="1">
    <distinct-value xsi:type="xs:string" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      >/gajanan.xml</distinct-value>
    <distinct-value xsi:type="xs:string" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      >fooooooooo</distinct-value>
  </tuple>
  <metrics>
    <values-resolution-time>PT0.0006S</values-resolution-time>
    <aggregate-resolution-time>PT0.000014S</aggregate-resolution-time>
    <total-time>PT0.002337S</total-time>
  </metrics>
</values-response>
<?xml version="1.0" encoding="UTF-8"?>
<hello>2012-08-10-05:00</hello>
<?xml version="1.0" encoding="UTF-8"?>
<foo>bar</foo>
    
Example:
xquery version "1.0-ml";
import module namespace search = "http://marklogic.com/appservices/search"
    at "/MarkLogic/appservices/search/search.xqy";

let $options := 
<options xmlns="http://marklogic.com/appservices/search">
  <values name="animals">
    <range type="xs:string">
      <field name="animal-name" collation="http://marklogic.com/collation/" />
    </range>
  </values>
</options>
return
search:values("animals", $options, search:parse("mammal OR marsupial", (), "search:query"), 10, "camel", 5, 3)

==> Assuming the value subset defined by the query (mammal OR marsupial),
    limit (10), and start ("buffalo") contains the values (camel, fox,
    hare, jaguar, kangaroo, lemur, moose, ocelot, panda, rhino), then
    adding a page-start of 5 and a page-length of 3, you get the following:

<values-response name="animals" type="xs:string" xmlns="http://marklogic.com/appservices/search" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<distinct-value frequency="1">kangaroo</distinct-value>
<distinct-value frequency="1">lemur</distinct-value>
<distinct-value frequency="1">moose</distinct-value>
<metrics>
<values-resolution-time>PT0.000242S</values-resolution-time>
<total-time>PT0.00134S</total-time>
</metrics>
</values-response>