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
Stack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.