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

Built-In: Extension - Search Functions

The search extension functions complement the Search Built-in functions.

Function Summary
xdmp:diacritic-less Returns the specified string, converting all of the characters with diacritics to characters without diacritics.
xdmp:estimate Returns the number of fragments selected by an expression.
xdmp:exists Returns true if any fragment is selected by an expression, false if no fragments are selected.
xdmp:plan Returns an XML element recording information about how the given expression will be processed by the index.
xdmp:plannable Returns a boolean showing whether the given expression is suitable to use with xdmp:plan.
xdmp:request-timestamp Returns the system timestamp for this request if the request is a query statement.
Function Detail
xdmp:diacritic-less(
$string as xs:string
)  as   xs:string
Summary:

Returns the specified string, converting all of the characters with diacritics to characters without diacritics.

Parameters:
$string : The string to convert.

Example:
xdmp:diacritic-less("José")
=> Jose 

xdmp:estimate(
$expression as item()*,
[$maximum as xs:double?]
)  as   xs:integer
Summary:

Returns the number of fragments selected by an expression. This can be used as a fast estimate of the number of items in a sequence.

Parameters:
$expression : The expression to estimate. This must be a partially searchable XPath expression or a cts:search() expression.
$maximum (optional): The maximum value to return. Stop selecting fragments if this number is reached.

Usage Notes:

Queries that use xdmp:estimate require that the XPath expression searched is partially searchable. A partially searchable XPath expression is one whose first step is searchable. You can use xdmp:query-trace() to determine if a step is searchable. If there are no entries in the xdmp:query-trace() output indicating that the first step is unsearchable, then the expression is partially searchable and you can perform an xdmp:estimate operation on it.

Example:
  xdmp:estimate(collection())
   => 10476

xdmp:exists(
$expression as item()*
)  as   xs:boolean
Summary:

Returns true if any fragment is selected by an expression, false if no fragments are selected. This can be used as a fast existence check.

Parameters:
$expression : The expression to check. This must be a partially searchable XPath expression or a cts:search() expression.

Usage Notes:

Queries that use xdmp:exists require that the XPath expression searched is partially searchable. A partially searchable XPath expression is one whose first step is searchable. You can use xdmp:query-trace() to determine if a step is searchable. If there are no entries in the xdmp:query-trace() output indicating that the first step is unsearchable, then the expression is partially searchable and you can perform an xdmp:exists operation on it.

Calling xdmp:exists on an expression is the same as calling xdmp:estimate on the expression with a maximum of 1. For example, the following are equivalent:

     xdmp:exists(cts:search(collection(), "foo"))
   
       is equivalent to:
   
     xs:boolean(xdmp:estimate(cts:search(collection(), "foo"), 1)) 


Example:
  xdmp:exists(collection())
   => true

xdmp:plan(
$expression as item()*,
[$maximum as xs:double?]
)  as   element()
Summary:

Returns an XML element recording information about how the given expression will be processed by the index. The information is a structured representation of the information provided in the error log when query trace is enabled. The query will be processed up to the point of getting an estimate of the number of fragments returned by the index.

Parameters:
$expression : The expression to estimate. This must be a partially searchable XPath expression or a cts:search() expression.
$maximum (optional): The maximum value to return. Stop selecting fragments if this number is reached.

Required Privilege:

http://marklogic.com/xdmp/privileges/xdmp-plan

Usage Notes:

The output from xdmp:plan will vary depending on various index settings.

Running an xdmp:plan on a search is similar to running an xdmp:estimate on a search, but it returns a report on the search instead of just an estimate. As part of the report, the qry:result element includes the estimate. If the search expression argument cannot be run in the plan because it is not partially searchable, then an XDMP-UNSEARCHABLE exception is returned as part of the xdmp:plan output.

If you are running a search using the search API (for example, search:search), use the option <return-plan>true</return-plan> in your search API options node.


Example:
xquery version "1.0-ml";

xdmp:plan(cts:search(fn:doc(),cts:word-query("cat")))
   =>
<qry:query-plan xmlns:qry="http://marklogic.com/cts/query">
  <qry:info-trace>xdmp:eval("xquery version &amp;quot;1.0-ml&amp;quot;;&amp;
     #10;&amp;#10;xdmp:plan(cts:search...", (), &lt;options 
     xmlns="xdmp:eval"&gt;&lt;database&gt;8855151527276563827&lt;/database&gt;
     &lt;isolation&gt;different-tra...&lt;/options&gt;)
  </qry:info-trace>
  <qry:info-trace>Analyzing path for search: fn:doc()</qry:info-trace>
  <qry:info-trace>Step 1 is searchable: fn:doc()</qry:info-trace>
  <qry:info-trace>Path is fully searchable.</qry:info-trace>
  <qry:info-trace>Gathering constraints.</qry:info-trace>
  <qry:word-trace text="cat">
    <qry:key>12545744176132597186</qry:key>
  </qry:word-trace>
    <qry:info-trace>Search query contributed 1 constraint: 
        cts:word-query("cat", ("lang=en"), 1)
    </qry:info-trace>
  <qry:partial-plan>
    <qry:term-query weight="1">
      <qry:key>12545744176132597186</qry:key>
      <qry:annotation>word("cat")</qry:annotation>
    </qry:term-query>
  </qry:partial-plan>
  <qry:info-trace>Executing search.</qry:info-trace>
  <qry:final-plan>
    <qry:and-query>
      <qry:term-query weight="1">
        <qry:key>12545744176132597186</qry:key>
        <qry:annotation>word("cat")</qry:annotation>
      </qry:term-query>
    </qry:and-query>
  </qry:final-plan>
  <qry:info-trace>Selected 1 fragment to filter</qry:info-trace>
  <qry:result estimate="1"/>
</qry:query-plan>

Example:
xquery version "1.0-ml" ;

xdmp:plan(
 cts:search(/document,
   cts:word-query("cut?",
    ("unstemmed", "wildcarded") ) ) )
(:
The <qry:expansion-trace> element indicates that a
lexicon expansion occurred on the wildcarded query
(word searches, three character searches and
a codepoint lexicon are enabled in the database
configuration for wildcard queries).  The
<qry:expansion> element shows what term(s) the
lexicon expansion found.  In this case, "cut?"
expands to "cute".
:)
=>
<qry:query-plan xmlns:qry="http://marklogic.com/cts/query">
  <qry:info-trace>Analyzing path for search: fn:collection()/document
  </qry:info-trace>
  <qry:info-trace>Step 1 is searchable: fn:collection()</qry:info-trace>
  <qry:info-trace>Step 2 is searchable: document</qry:info-trace>
  <qry:info-trace>Path is fully searchable.</qry:info-trace>
  <qry:info-trace>Gathering constraints.</qry:info-trace>
  <qry:expansion-trace type="full" elapsed-time="PT0.000381S" text="cut?" 
  counts="1">
    <qry:interval lowerbound="CUT" upperbound="C??"/>
    <qry:interval lowerbound="cUT" upperbound="c??"/>
    <qry:interval lowerbound="}UT" upperbound="???"/>
    <qry:expansion text="cute"/>
  </qry:expansion-trace>
  <qry:word-trace text="cute">
    <qry:key>16588943567160478160</qry:key>
  </qry:word-trace>
  <qry:info-trace>Search query contributed 1 constraint: 
  cts:word-query("cut?", ("unstemmed","wildcarded","lang=en"), 1)
  </qry:info-trace>
  <qry:partial-plan>
    <qry:term-query weight="1">
      <qry:key>16588943567160478160</qry:key>
      <qry:annotation>word("cute")</qry:annotation>
    </qry:term-query>
  </qry:partial-plan>
  <qry:info-trace>Executing search.</qry:info-trace>
  <qry:final-plan>
    <qry:and-query>
      <qry:or-two-queries>
	<qry:term-query weight="0">
	  <qry:key>3998944933214536873</qry:key>
	  <qry:annotation>doc-root(element(document),doc-kind(document)) 
	</qry:annotation>
	</qry:term-query>
	<qry:term-query weight="0">
	  <qry:key>13616698357625443361</qry:key>
	  <qry:annotation>link-child(descendant(doc-root(element(document),
	     doc-kind(document)) ))
	</qry:annotation>
	</qry:term-query>
      </qry:or-two-queries>
      <qry:term-query weight="1">
	<qry:key>16588943567160478160</qry:key>
	<qry:annotation>word("cute")</qry:annotation>
      </qry:term-query>
    </qry:and-query>
  </qry:final-plan>
  <qry:info-trace>Selected 1 fragment to filter</qry:info-trace>
  <qry:result estimate="1"/>
</qry:query-plan>

xdmp:plannable(
$expression as item()
)  as   xs:boolean
Summary:

Returns a boolean showing whether the given expression is suitable to use with xdmp:plan. Expressions that are fully searchable are "plannable"; that is, they will return query plan output when used with xdmp:plan.

Parameters:
$expression : The expression to determine if it is plannable.

Usage Notes:

Behaves the same as "Analyzing path for search" in xdmp:plan. When true is returned, the expression could be planned by xdmp:plan, otherwise the expression would throw an XDMP-UNSEARCHABLE exception when run in xdmp:plan.


Example:
  xdmp:plannable(cts:search(fn:doc(),cts:word-query("cat")))
   => true
Example:
  xdmp:plannable(/foo/descendant::bar="baz")
   => false

xdmp:request-timestamp(  ) as  xs:unsignedLong?
Summary:

Returns the system timestamp for this request if the request is a query statement. Returns the empty sequence if the current request is an update statement.

Usage Notes:

The xdmp:request-timestamp function returns the system timestamp that is in effect for current query. This timestamp will remain unchanged for the duration of the query. If you want to get the most recent system timestamp external to the current running context during an update statement (for example, if your query takes a long time to run, and there are other updates occurring in your database while your update statement is running), you can use xdmp:eval to evaluate a separate query statement that returns the system timestamp at the time the xdmp:eval query is evaluated.

Example:
  xdmp:request-timestamp()
   => 1234567