<!-- Copyright 2002-2010 MarkLogic Corporation.  All Rights Reserved. -->
<apidoc:module name="SearchBoxModule" category="Search" lib="search"
  bucket="XQuery Library Modules"
  xmlns:apidoc="http://marklogic.com/xdmp/apidoc"
  xmlns="http://www.w3.org/1999/xhtml">
  <apidoc:summary>
    <p>The Search function module is installed as the following file:</p>
    <ul>
      <li>
        <code><em>install_dir</em>/Modules/MarkLogic/appservices/search/search.xqy</code>
      </li>
    </ul>
    <p>where <code>
        <em>install_dir</em>
      </code> is the directory in which MarkLogic Server is installed.</p>
      <p>To use the <code>search.xqy</code> module in your own XQuery modules, 
	      include the following line in your XQuery prolog:</p>
    <pre xml:space="preserve">
import module namespace search="http://marklogic.com/appservices/search"
                    at "/MarkLogic/appservices/search/search.xqy";</pre>
	    <p>The Search functions are used to create search high-level 
		    results, facets, snippets, and other search-related 
		    items.</p>
  </apidoc:summary>
  <apidoc:function name="check-options" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc: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 <code>&lt;report&gt;</code> elements.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="options" type="element(search:options)?">
		    Options to define the search 
		    grammar and control the search. See description for 
		    <a href="#search-options"><code>$options</code></a> for 
		    the function <code>search:search</code>. 
      </apidoc:param>
      <apidoc:param name="strict" type="xs:boolean?" optional="true">If 
	      <code>true</code>, index settings are additionally 
	      verified. The default is <code>false</code>.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(search:report)*</apidoc:return>
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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>)

=>

()
]]>
      </pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="estimate" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc: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
		  <code>xdmp:estimate</code>).
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="cts-query" type="schema-element(cts:query)">A
		    serialized and annotated <code>cts:query</code>, 
		    typically the result of a call to 
		    <a href="#search:parse"><code>search:parse</code></a>.
	    </apidoc:param>
	    <apidoc:param name="options" type="element(search:options)?" 
		    optional="true">Options to define the search 
		    grammar and control the search. See description for 
		    <a href="#search-options"><code>$options</code></a> for 
		    the function <code>search:search</code>. 
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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
]]>
      </pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-default-options" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the default options 
		  XML. Default options do not contain any constraints 
		  or anything else that requires specific index 
		  settings.</apidoc:summary>
    <apidoc:return>element(search:options)</apidoc:return>
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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>
]]>
      </pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="parse" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc:summary>This function parses query text according 
		  to given options and returns the appropriate 
		  <code>cts:query</code> XML.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="qtext" type="xs:string+">The query 
		    text to parse. This may be a sequence, to accommodate 
		    more complex search UI. Multiple query texts will be 
		    ANDed together.</apidoc:param>
      <apidoc:param name="options" type="element(search:options)?" 
		    optional="true">Options to define the search 
		    grammar and control the search. See description for 
		    <a href="#search-options"><code>$options</code></a> for 
		    the function <code>search:search</code>. 
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element()?</apidoc:return>
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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>
]]>
  </pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="remove-constraint" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc:summary>This function safely removes a token from query text, 
		  ensuring that grammar elements (AND, OR, quotes, 
		  parentheses) are handled properly.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="qtext" type="xs:string">The full query 
		    text string.</apidoc:param>
	    <apidoc:param name="ptext" type="xs:string">A token to remove 
		    from full query text.</apidoc:param>
      <apidoc:param name="options" type="element(search:options)?" 
		    optional="true">Options to define the search 
		    grammar and control the search. See description for 
		    <a href="#search-options"><code>$options</code></a> for 
		    the function <code>search:search</code>. 
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string?</apidoc:return>
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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"
]]>
</pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="resolve" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc:summary>This function is the same as 
		  <code>search:search</code>, except that it takes 
		  a parsed and annotated <code>cts:query</code> XML tree as 
		  input.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="cts-query" type="schema-element(cts:query)">A
		    serialized and annotated <code>cts:query</code>, 
		    typically the result of a call to 
		    <a href="#search:parse"><code>search:parse</code></a>.
	    </apidoc:param> 
	    <apidoc:param name="options" type="element(search:options)?" 
		    optional="true">Options to define the search 
		    grammar and control the search. See description for 
		    <a href="#search-options"><code>$options</code></a> for 
		    the function <code>search:search</code>. 
	    </apidoc:param>
	    <apidoc:param name="start" type="xs:unsignedLong?" 
		    optional="true">The index of the first hit to return. 
		    The default is 1.
	    </apidoc:param>
	    <apidoc:param name="page-length" type="xs:unsignedLong?" 
		    optional="true">The maximum number of hits to return. 
		    The default is 10. If the value is 0, no results 
		    are returned.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(search:response)</apidoc:return>
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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>
]]>
      </pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="resolve-nodes" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc:summary>This function performs the same search as 
		  <code>search:search</code>, but it takes 
		  a parsed and annotated <code>cts:query</code> XML tree as 
		  input and returns the actual result nodes from the database.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="cts-query" type="schema-element(cts:query)">A
		    serialized and annotated <code>cts:query</code>, 
		    typically the result of a call to 
		    <a href="#search:parse"><code>search:parse</code></a>.
	    </apidoc:param>
	    <apidoc:param name="options" type="element(search:options)?" 
		    optional="true">Options to define the search 
		    grammar and control the search. See description for 
		    <a href="#search-options"><code>$options</code></a> for 
		    the function <code>search:search</code>. 
	    </apidoc:param>
            <apidoc:param name="start" type="xs:unsignedLong?" 
		    optional="true">The index of the first hit to return. 
		    The default is 1.
            </apidoc:param> 
	    <apidoc:param name="page-length" type="xs:unsignedLong?" 
		    optional="true">The maximum number of hits to return. 
		    The default is 10. If the value is 0, no results are 
		    returned.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>node()*</apidoc:return>
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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 ...

]]>
      </pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="search" lib="search" category="Search"
          bucket="XQuery Library Modules">
          <apidoc:summary>This function parses and invokes a query according to
                  specified options, returning up to $page-length result nodes
                  starting from $start.</apidoc:summary>
    <apidoc:params>
            <apidoc:param name="qtext" type="xs:string+">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.</apidoc:param>
            <apidoc:param name="options" type="element(search:options)?"
                    optional="true">Options to define
        the search grammar and control the search.
	<p id="search-options"> The following is a summary of the 
		XML structure of an options node: </p>

          <blockquote>
            <dl>
              <dt>
                <pre>&lt;additional-query&gt;</pre>
              </dt>
              <dd>An additional serialized <code>cts:query</code> node,
                      which is combined using a
                      <code>cts:and-query</code> with the query resulting from
		      the specified <code>$qtext</code>.  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 <code>/my/directory/</code>:
                      <pre xml:space="preserve"><![CDATA[
<options xmlns="http://marklogic.com/appservices/search">
  <additional-query>{cts:directory-query("/my/directory/")}
  </additional-query>
</options>
  ]]></pre>
            <p>If you have multiple <code>additional-query</code> options,
	    they are combined using a <code>cts:and-query</code>.</p>
	      </dd>
	      <dt>
                <pre id="concurrency-level">&lt;concurrency-level&gt;</pre>
              </dt>
	      <dd>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: 
		      <pre xml:space="preserve"><![CDATA[
<options xmlns="http://marklogic.com/appservices/search">
	<concurrency-level>16</concurrency-level>
</options>
  ]]></pre>
	      </dd>

              <dt>
                <pre id="constraint">&lt;constraint&gt;</pre>
              </dt>
              <dd>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.
                      <p>Each <code>constraint</code>  element must have
                              an <code>@name</code> attribute (required),
                              which is the unique name of this constraint.
                              The name can then be used in the search
                              grammar to specify the constraint.
                      </p>
                      <p>The <code>constraint</code>  element can have zero
                              or more of the following elements:</p>
                      <dl>
                              <dt>
                                      <pre>&lt;value&gt;</pre>
                              </dt>
                              <dd>Specifies element or attribute values on
                                      which to constrain. You 
				      cannot create facets from a 
				      <code>value</code> constraint.
                                      For example:
  <pre xml:space="preserve"><![CDATA[
<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>]]></pre>
                              </dd>
                              <dt>
                                      <pre>&lt;word&gt;</pre>
                              </dt>
                              <dd>Specifies the element, attribute, or field on
                                      which to constrain by word.  You 
				      cannot create facets from a 
				      <code>word</code> constraint. 
                                      For example:
  <pre xml:space="preserve"><![CDATA[
<constraint name="name">
    <word>
      <element ns="http://widgets-r-us.com" name="name"/>
    </word>
</constraint>
<constraint name="description">
    <word>
        <field name="my-field"/>
    </word>
</constraint>
  ]]></pre>
                              </dd>
                              <dt>
                                      <pre>&lt;collection&gt;</pre>
                              </dt>
                              <dd>Specifies the collection on
                                      which to constrain.
                                      For example:
  <pre xml:space="preserve"><![CDATA[
<constraint name="my-collection">
    <collection prefix="http://server.com/my-collection/"/>
</constraint>
  ]]></pre>
                              </dd>
                              <dt>
                                      <pre>&lt;range&gt;</pre>
                              </dt>
                              <dd>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
                                      <code>range</code> element with a
				      <code>type</code> attribute child, an
				      optional <code>collation</code> attribute
				      child (for string range indexes),
                                      an <code>element</code> child, an optional
                                      <code>attribute</code> child (for
                                      attribute ranges), and may have one
                                      or more <code>computed-bucket</code>
				      children and/or one or more
				      <code>facet-option</code> children (to
				      pass options to the underlying lexicon
				      apis). 
				      For example:
                <pre xml:space="preserve"><![CDATA[
<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="color">
    <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>
</options>
]]></pre>
<p>
	For <code>range</code> constraints with either <code>bucket</code>
	or <code>computed-bucket</code> 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 
	<code>facet-option</code> in the specification.
</p>
			      </dd>
			                                    <dt>
                                      <pre>&lt;element-query&gt;</pre>
			      </dt>
			      <dd>Specifies a constraint that restricts the
				      search to the specified element.  You 
				      cannot create facets from an 
				      <code>element-query</code> constraint.
				      <pre xml:space="preserve"><![CDATA[
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="sample-element-constraint">
    <element-query name="title" ns="http://my/namespace" />
  </constraint>
</options>
					      ]]></pre>
			      </dd>
			                                    <dt>
                                      <pre>&lt;properties&gt;</pre>
			      </dt>
			      <dd>Specifies a constraint that finds matches on
				      the corresponding properties documents.  
				      You cannot create facets from a 
				      <code>properties</code> constraint.
				      <pre xml:space="preserve"><![CDATA[
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="sample-property-constraint">
    <properties />
  </constraint>
</options>
					      ]]></pre>
				      For an additional example, see <a href="#prop-constraint">the second example</a> below.
			      </dd>
			      <dt><pre>&lt;geo-*&gt;</pre></dt>
			      <dd>Specifies a geospatial constraint.  Must
				      be one of the following elements: 
				      <code>&lt;geo-attr-pair&gt;</code>,
				      <code>&lt;geo-elem-pair&gt;</code>, or
				      <code>&lt;geo-elem&gt;</code>.  If the 
				      constraint has a 
				      <code>&lt;heatmap&gt;</code> child, then
				      it can be used as a facet, and can 
				      contain 
				      <code>&lt;facet-options&gt;</code>.
				      For example:
  <pre xml:space="preserve"><![CDATA[
<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>

]]></pre>
<p>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 
	<code>my-geo-elem-child:"-12, 5"</code> in your search string. 
</p>
			      </dd>
			                                    <dt>
                                      <pre>&lt;custom&gt;</pre>
                              </dt>
			      <dd>Specifies a custom constraint along with
				      the name of the function implementations 
				      used to evaluate the custom constraint.  
				      
                                      For example:
  <pre xml:space="preserve"><![CDATA[
<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). 
-->
  ]]></pre>
                              </dd>
                              <dt>
      <pre id="term-option">&lt;term-option&gt;</pre>
               </dt>
	      <dd>
	      <p>Specifies the options passed into the search
		      (for example, case-insensitive).  There can be zero or 
		      more <code>term-option</code> elements.  By default, 
		      the search uses the same default options as the 
		      underlying <code>cts:query</code> constructors, and the 
		      defaults change based on your index configuration. 
		      You can use <code>term-option</code> elements as a child
		      of either the <code><a href="#term">term</a></code>
		      element or as a child of the  
		      <code><a href="#constraint">constraint</a></code> 
		      element (except for <code>element-query</code>
		      constraints). </p>
	      <p>Legal term option values are:</p>
	      <p>	      <code>case-sensitive</code><br/>
			      <code>case-insensitive</code><br/>
			      <code>diacritic-sensitive</code><br/>
			      <code>diacritic-insensitive</code><br/>
			      <code>punctuation-sensitive</code><br/>
			      <code>punctuation-insensitive</code><br/>
			      <code>whitespace-sensitive</code><br/>
			      <code>whitespace-insensitive</code><br/>
			      <code>stemmed</code><br/>
			      <code>unstemmed</code><br/>
			      <code>wildcarded</code><br/>
			      <code>unwilcarded</code><br/>
			      <code>exact</code><br/>
			      <code>lang=<em>iso639code</em></code><br/>
		      </p>
		      <p>For example:</p>
  <pre xml:space="preserve"><![CDATA[
<term-option>diacritic-insensitive</term-option>
  ]]></pre>			      </dd>
                      </dl>



              </dd>

              <dt>
                <pre>&lt;debug&gt;</pre>
              </dt>
              <dd>Activates debugging mode. Additional report elements will
                  be present in the output. Set to <code>true</code> to
                activate. The default is <code>false</code>. </dd>

              <dt>
                <pre>&lt;default-suggestion-source&gt;</pre>
              </dt>
	      <dd><p>Defines the content to be used as the default source of
                      suggestions (see
              <a href="#search:suggest"><code>search:suggest</code></a>). 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 <code>word-lexicon</code> (the database-wide
                      word lexicon) is not recommended as best practice;
                      collection and range lexicons will yield the best
		      performance.
	      </p>
                      <p>Each <code>default-suggestion-source</code>  element
                              can optionally have an <code>@collation</code>
                              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.
                      </p>
                      <p>The <code>default-suggestion-source</code>  element
                              can have zero or more of the following
                              child elements:</p>
                      <dl>
                              <dt>
                                      <pre>&lt;collection&gt;</pre>
                              </dt>
                              <dd>Specifies using the collection lexicon
                                      for suggestions.  For example:
  <pre xml:space="preserve"><![CDATA[
<default-suggestion-source>
        <collection/>
</default-suggestion-source>  ]]></pre>
                              </dd>
                              <dt>
                                      <pre>&lt;range&gt;</pre>
                              </dt>
                              <dd>Specifies the element or attribute lexicon
                                      to use for suggestions.  For example:
  <pre xml:space="preserve"><![CDATA[
<default-suggestion-source>
  <range type="xs:string">
    <element ns="my-namespace" name="my-localname"/>
    <attribute ns="" name="my-attribute"/>
   </range>
</default-suggestion-source>  ]]></pre>
                              </dd>
                              <dt>
                                      <pre>&lt;word&gt;</pre>
                              </dt>
                              <dd>Specifies using the word lexicon for
                                      suggestions.  This option might
                                      not scale well for a large database.
                                      For example:
  <pre xml:space="preserve"><![CDATA[
<default-suggestion-source>
        <word/>
</default-suggestion-source>
<default-suggestion-source>
    <word>
        <field name="my-field"/>
    </word>
</default-suggestion-source>
]]></pre>
                              </dd>
                       </dl>
              </dd>
              <dt>
                <pre>&lt;forest&gt;</pre>
              </dt>
              <dd>A single forest ID to pass into <code>cts:search</code>.
                      To specify multiple forests, use multiple
                      <code>forest</code> elements in the options node. 			      <p>The value must be an <code>xs:unsignedLong</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;grammar&gt;</pre>
              </dt>
              <dd> Wrapper element for grammar definition. The default
		      grammar defines "Google-style" parsing.
		      <p> The <code>grammar</code> element has a 
			      <code>quotation</code> 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.
		      </p>
		      <p> The <code>grammar</code> element can have
			      0 or more <code>joiner</code> elements and 
			      0 or more <code>starter</code> elements. </p>
                      <p>The <code>grammar</code>  element
                              should have one or more of each of the following
			      elements.  If the grammer element is present but 
			      empty, then the grammar does nothing, and the
			      search is parsed according to the 
			      <code>term</code> option.
                      </p>
                      <dl>
                              <dt>
                                      <pre>&lt;implicit&gt;</pre>
			      </dt>
			      <dd>Specifies the <code>cts:query</code> 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 
				      <code>cts:or-query</code>
				      instead of a <code>cts:and-query</code>).
				      <p>The following is an example of a 
					      <code>options</code> element
					      with an <code>implicit</code>
					      specification for a 
				      <code>cts:or-query</code>:</p>
			      <pre xml:space="preserve"><![CDATA[
<options xmlns="http://marklogic.com/appservices/search">
  <grammar>
    <implicit>
      <cts:or-query strength="10" xmlns:cts="http://marklogic.com/cts"/>
    </implicit>
  </grammar>
</options>
				      ]]></pre>
			      </dd>
                              <dt>
                                      <pre>&lt;joiner&gt;</pre>
                              </dt>
                              <dd>Specifies what text to use to combine
                                      terms together, and what is the
                                      underlying <code>cts:query</code>
                                      constructor to use to join the terms
				      together.  You specify the function to
				      call for the joiner with the 
				      <code>apply</code> attribute, along with
				      optional <code>ns</code> (for the module 
				      namespace) and
				      <code>at</code> (for the module path)
				      attributes.  Additionally, the 
				      <code>strength</code> attribute determines
				      the order of precedence over other 
				      <code>joiner</code> elements, the optional
				      <code>options</code> attribute specifies
				      a space-separated list of options that 
				      are passed through to the underlying
				      <code>cts:query</code> constructor,
				      and the <code>element</code>
				      attribute specifies the 
				      <code>cts:query</code>
				      element name (for example, 
				      <code>cts:and-query</code>).
                              </dd>
                              <dt>
                                      <pre>&lt;starter&gt;</pre>
                              </dt>
                              <dd>Specifies what text to use to delimit
				      and group terms.  
				      You specify the function to
				      call for the starter with the 
				      <code>apply</code> attribute, along with
				      optional <code>ns</code> (for the module 
				      namespace) and
				      <code>at</code> (for the module path)
				      attributes.  Additionally, the 
				      <code>strength</code> attribute determines
				      the order of precedence over other 
				      <code>starter</code> elements, the 
				      optional
				      <code>options</code> attribute specifies
				      a space-separated list of options that 
				      are passed through to the underlying
				      <code>cts:query</code> constructor, 
				      the <code>element</code>
				      attribute specifies the 
				      <code>cts:query</code>
				      element name (for example, 
				      <code>cts:and-query</code>), and the 
				      <code>delimiter</code> attribute 
				      specifies the string to use as a 
				      delimiter for the starter. 
                              </dd>
                      </dl>
                      <p>The following is an example of a <code>grammar</code>
                      element.</p>
                      <pre xml:space="preserve"><![CDATA[
<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>
]]></pre>

              </dd>

              <dt>
                <pre>&lt;operator&gt;</pre>
              </dt>
              <dd>A named wrapper for one or more <code>state</code>
                      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 <code>state</code> child 
		      with the name "foo" at query runtime, using the option
		      specified on that <code>state</code> element.  
		      Options affecting query
                parsing (such as <code>constraint</code>, <code>grammar</code>,
                <code>term</code>, <code>empty</code>) may not be configured
                via operators.
                <p>An <code>operator</code> element can have one or more
                        <code>state</code> elements.  Each <code>state</code>
                        element can have one of the
                        following elements:</p>
                <dl>
                        <dt><code>additional-query</code></dt>
                        <dt><code>debug</code></dt>
                        <dt><code>forest</code></dt>
                        <dt><code>page-length</code></dt>
                        <dt><code>quality-weight</code></dt>
                        <dt><code>searchable-expression</code></dt>
                        <dt><code>sort-order</code></dt>
                        <dt><code>transform-results</code></dt>
		</dl>
		<p>In the following example, a search for 
		<code>special:hello</code> 
		 constrains the search by the "hello world" query, and a
		 search for <code>special:forest</code> constrains the 
		 search to the forest names "my-forest".  </p>
		<pre xml:space="preserve"><![CDATA[
<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>
]]></pre>
	 
        </dd>

              <dt>
                <pre>&lt;page-length&gt;</pre>
              </dt>
              <dd> Specifies the number of results per page. The default value
                      is 10.
                      <p>The value must be an <code>xs:unsignedInt</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;quality-weight&gt;</pre>
              </dt>
              <dd>Specifies a a weighting factor to use in the query.
                      The default value is 1.0.
                  <p>The value must be an <code>xs:double</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;return-constraints&gt;</pre>
              </dt>
              <dd>Include original constraint definitions in the results. The
                      default is false.
        <p>The value must be an <code>xs:boolean</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;return-facets&gt;</pre>
              </dt>
              <dd>Include resolved facets in the results. The default
                      is <code>true</code>.
                      <p>The value must be an <code>xs:boolean</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;return-metrics&gt;</pre>
              </dt>
              <dd>Include statistics in the results. The default is
                      <code>true</code>.
                      <p>The value must be an <code>xs:boolean</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;return-plan&gt;</pre>
              </dt>
	      <dd>Include <code>xdmp:plan</code> output in the results. 
		      The default is <code>false</code>.  The output
		      is useful in examining the evaluation plan
		      of the search.
                      <p>The value must be an <code>xs:boolean</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;return-qtext&gt;</pre>
              </dt>
              <dd>Include the original query text in the results.
                      The default is <code>true</code>.
                  <p>The value must be an <code>xs:boolean</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;return-query&gt;</pre>
              </dt>
              <dd>Include the XML query representation in the results.
                      The default is <code>false</code>.
                     <p>The value must be an <code>xs:boolean</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;return-results&gt;</pre>
              </dt>
              <dd>Include search results in the output. (Use transform-results
                      to specify how each result should be formatted.) The
                      default is <code>true</code>.
                      <p>The value must be an <code>xs:boolean</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;return-similar&gt;</pre>
              </dt>
              <dd>Include with each search result a list of URLs of similar
                      documents in the database. The default is
                      <code>false</code>.
                      <p>The value must be an <code>xs:boolean</code>
                      type.</p>
              </dd>

              <dt>
                <pre>&lt;search-option&gt;</pre>
              </dt>
              <dd>For advanced users, a single option to be passed in
                      with <code>cts:search</code> calls (for example,
                      <code>filtered</code>, <code>unfiltered</code>,
                      <code>score-logtfidf</code>, and so on). To pass in
                      multiple options, specify multiple
                      <code>search-options</code> elements in the options
                      node. The default is no
                      additional options. For example:
                        <pre xml:space="preserve"><![CDATA[
<search-option>unfiltered</search-option>
<search-option>score-logtf</search-option>
 ]]></pre>
              </dd>

              <dt>
                <pre>&lt;searchable-expression&gt;</pre>
              </dt>
              <dd>An expression to be searched.  Whatever expression is
                      specified is returned from the search.  For example,
                      if you specify <code>//p</code>, then <code>p</code>
                      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 <code>xmlns</code>
                attributes. For example: <pre xml:space="preserve"><![CDATA[
<searchable-expression xmlns:ex="http:example.com"
	xmlns:com="http://company.com">/ex:orders/com:company
</searchable-expression>
        ]]></pre>
       The default value is <code>fn:collection()</code>, which
        searches all documents in the database.
              </dd>

              <dt>
                <pre>&lt;sort-order&gt;</pre>
              </dt>
	      <dd><p>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 <code>search-option</code>. If you are sorting
		      by an element or an attribute, you must specify a
		      <code>type</code> attribute with a value corresponding
		      to the range index type of that element or 
		      attribute (for example, <code>xs:string</code>,
		      <code>xs:dateTime</code>, and so on).  If the
		      corresponding range index is of type 
		      <code>xs:string</code>, then you can optionally
		      specify a <code>collation</code> attribute (otherwise
		      the collation of the query is used). To change the
		      sorting direction, specify an optional
		      <code>direction</code> attribute with a value of 
		      <code>decending</code> (the default) or  
		      <code>ascending</code>.
	      </p>
	      <p>The <code>sort-order</code> element must have either a 
		      single <code>element</code> child or a single 
		      <code>score</code> child.   If there is a   
		      <code>score</code> child, it specifies to
		      sort by the score of the search result.  If there is an 
		      <code>element</code> child it can optionally have an
		      <code>attribute</code> sibling (to specify an attribute
		      of the preceding <code>element</code>).  Both the 
		      <code>element</code> and <code>attribute</code> 
		      elements must have <code>ns</code> and <code>name</code>
		      attributes to specify the namespace and local-name of 
		      the specified element and attribute.  Additionally,
		      the <code>sort-order</code> element can have 0 or more
		      <code>annotation</code> elements (to add comments,
		      for example).
                </p>
		<p>For example, the following specifies a primary
			sort order using the element value for
			<code>my-element</code> (which needs a string
			range index with the specified collation), and
			a secondary sort order of score ascending:</p>
                        <pre xml:space="preserve"><![CDATA[
<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>
 ]]></pre>
                
              </dd>

              <dt>
                <pre>&lt;suggestion-source&gt;</pre>
              </dt>
	      <dd><p>Specifies a constraint source to override  
		      a named constraint when using 
	      <code><a href="#search:suggest">search:suggest</a></code>. 
		      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 <code>suggestion-source</code> 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.
		      </p>
		      <p>Each suggestion source must have a <code>name</code> 
			 attribute corresponding to a named constraint (one 
			 <code>suggestion-source</code> per named constraint).
			 A <code>suggestion-source</code> can have one 
			 of the following child elements: 
			 <code>collection</code>,
			 <code>range</code>,
			 <code>word</code>, or
			 <code>word-lexicon</code>.
		 </p>
		 <p>For example, the following overrides the
			 <code>tag:</code> prefix, using the range index
			 for the attribute <code>shortname</code> instead of
			 the one for <code>name</code> when using 
			 <code>search:suggest</code>:</p>
                        <pre xml:space="preserve"><![CDATA[
 <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 name="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>

 ]]></pre>
              </dd>

              <dt>
		      <pre id="term">&lt;term&gt;</pre>
              </dt>
	      <dd><p>Specifies handling of empty searches and controls options 
		      for how individual terms (that is, terms 
		      <em>not</em> associated with a constraint) will 
		      be represented when parseing the search. 
	      </p>
		      
	      <p>To control how empty searches (that is, the empty
		      string passed into <code>search:search</code>) are 
		      resolved, specify an <code>empty</code> child element 
		      with an <code>apply</code> attribute.  The value of the 
		      <code>apply</code> attribute specifies the behavior
		      for empty searches: a value of <code>all-results</code>
		      specifies that empty searches return everything in the
		      database, a value of <code>no-results</code> (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 
		      <code>cts:query</code> and specify the local-name of 
		      your function in the <code>apply</code> attribute, the
		      namespace of the function library module in the 
		      <code>ns</code> attribute, and the path to the 
		      module in the <code>at</code> attribute.
	      </p>
	      <p>Additionally, you can specify zero or more 
		      <a href="#term-option"><code>term-option</code></a>
		      elements to control the behavior of the search terms.
	      </p>
	      <p>For example:</p>
                        <pre xml:space="preserve"><![CDATA[
 <term>
   <empty apply="no-results" />
   <term-option>diacritic-insensitive</term-option>
   <term-option>unwildcarded</term-option>
 </term>

 ]]></pre>
              </dd>

              <dt>
                <pre>&lt;transform-results&gt;</pre>
              </dt>
	      <dd><p>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. </p>
	      <p>To use a different snippitting function, you must
		      use either <code>search:search</code> or
		       <code>search:resolve</code>; the 
		      <code>search:snippet</code> function always uses the 
		      default snippeting function. 
		      Specify the local-name of the function to pass in as the  
		      value of the <code>apply</code> attribute, the
		      namespace as the value of the <code>ns</code> attribute,
		      and the path to the module as the value of the 
		      <code>at</code> attribute. You can pass in parameters
		      to the function by specifying zero or more 
		      <code>param</code> child elements (the parameters are
		      passed in in the order specified).
	      </p>
	      <p>In addition to the default snippitting function, there
		      are two other built-in snippetting functions:
		      <code>apply="raw"</code> (return the whole node) and  
		      <code>apply="empty-snippet"</code> (return an empty 
		      snippet).
	      </p>
		  <p>The following example specifies a custom snippitting
		      function:</p>
                        <pre xml:space="preserve"><![CDATA[
<transform-results apply="snippet" ns="my-namespace"
                   at="/my-library.xqy"/>

 ]]></pre>
              </dd>
            </dl>
          </blockquote>

      </apidoc:param>
      <apidoc:param name="start" type="xs:unsignedLong?" optional="true">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.
      </apidoc:param>
      <apidoc:param name="page-length" type="xs:unsignedLong?" 
	      optional="true">The maximum number of hits to return. 
	      The default is 10. If the value is 0, no results are returned.
       </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(search:response)</apidoc:return>

     <apidoc:usage>
	    <p>The output of <code>search:search</code> returns a 
		    <code>&lt;response&gt;</code> element, which in turn 
		    contains a <code>total</code> attribute. The value of the
		    <code>total</code> 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. 
	    </p>
    </apidoc:usage>

    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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>
]]>
    </pre>
    </apidoc:example>
    <apidoc:example><a id="prop-constraint"/>
      <pre xml:space="preserve"><![CDATA[
(: 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>

]]>
    </pre>
    </apidoc:example>
  </apidoc:function>

  <apidoc:function name="snippet" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc: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.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="result" type="node()">A node from which 
		    to pull matching snippets from.
	    </apidoc:param>
	    <apidoc:param name="cts-query" type="schema-element(cts:query)">A
		    serialized and annotated <code>cts:query</code>, 
		    typically the result of a call to 
		    <a href="#search:parse"><code>search:parse</code></a>.
	    </apidoc:param>
	    <apidoc:param name="options" type="element(search:options)?" 
		    optional="true">Options to define the search 
		    grammar and control the search. See description for 
		    <a href="#search-options"><code>$options</code></a> for 
		    the function <code>search:search</code>.  Note that 
		    you cannot specify the  <code>apply</code> attribute
		    on the <code>transform-results</code> option with
		    <code>search:snippet</code>; to use a different snippetting
		    function, use 
		    <a href="#search:search"><code>search:search</code></a> or 
		    <a href="#search:resolve"><code>search:resolve</code></a>
		    instead.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(search:snippet)?</apidoc:return>

   
    
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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>
]]>
  </pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="suggest" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns a sequence of suggested text 
		  strings that match a wildcarded search for the 
		  <code>$qtext</code> 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.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="qtext" type="xs:string+">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 suggestons
		    by performing a lexicon match query.
		    The other strings (if any) are parsed as a 
		    <code>cts:query</code>, with the resulting queries 
		    combined with a <code>cts:and-query</code>, and the
		    resulting <code>cts:query</code> is passed as a 
		    constraining query to the lexicon match query, restricting 
		    the suggestions to fragments that match the 
		    <code>cts:query</code>.  Typically, each item in the
		    sequence corresponds to a single text entry box in a 
		    user interface.
	    </apidoc:param>
	    <apidoc:param name="options" type="element(search:options)?" 
		    optional="true">Options to define the search 
		    grammar and control the search. See description for 
		    <a href="#search-options"><code>$options</code></a> for 
		    the function <code>search:search</code>.  In particular, 
		    the <code>default-suggestion-source</code> and 
		    <code>suggestion-source</code> options are specific to
		    <code>search:suggest</code>.
	    </apidoc:param>
	    <apidoc:param name="limit" type="xs:unsignedInt?" 
		    optional="true">The maximum number of
		    suggestions to return. The default is 10.
	    </apidoc:param>
	    <apidoc:param name="cursor-position" type="xs:unsignedInt?" 
		    optional="true">The position of the cursor, from point of 
		    origin, in the text box corresponding to the 
		    <code>$focus</code> 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 
		    <code>$focus</code> string (all of the string).
	    </apidoc:param>
	    <apidoc:param name="focus" type="xs:positiveInteger?" 
		    optional="true">If there are multiple
		    <code>$qtext</code> 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 <code>$qtext</code> string.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:usage>
	     <p>
		    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 <code>search:suggest</code>. Therefore, MarkLogic 
		    recommends using value lexicons for suggestions, not word 
		    lexicons.  
	    </p>
	    <p>
		    The performance of <code>search:suggest</code> 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 <code>search:suggest</code> 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.
	    </p>
	    <p>
		    The output of <code>search:suggest</code> 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  <code>search:suggest</code>
		    is appropriate to pass into the first argument of
		    <code>search:search</code>, 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.
	    </p>
    </apidoc:usage>
    <apidoc:return>xs:string*</apidoc:return>
        <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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
]]>
      </pre>
    </apidoc:example>

     <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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"

]]>
      </pre>
    </apidoc:example>

    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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

]]>
      </pre>
    </apidoc:example>

    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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

]]>
      </pre>
    </apidoc:example>
        <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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
]]>
      </pre>
    </apidoc:example>
  </apidoc:function>
  <apidoc:function name="unparse" lib="search" category="Search"
          bucket="XQuery Library Modules">
	  <apidoc:summary>This function turns a serialized and annotated 
		  <code>cts:query</code> (typically from 
		  <code>search:parse</code>) back into 
		  query text according to the specified rules.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="cts-query" type="schema-element(cts:query)">A
		    serialized and annotated <code>cts:query</code>, 
		    typically the result of a call to 
		    <a href="#search:parse"><code>search:parse</code></a>.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string+</apidoc:return>
    <apidoc:example>
      <pre xml:space="preserve"><![CDATA[
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"
]]>
      </pre>
    </apidoc:example>
  </apidoc:function>
</apidoc:module>
