MarkLogic 9 Product Documentation
search:suggest

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	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	The maximum number of suggestions to return. The default is 10.
cursor-position	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	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	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.

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

MarkLogic 9 Product Documentationsearch:suggest

Summary

Usage Notes

Example

Example

Example

Example

Example

MarkLogic 9 Product Documentation
search:suggest