MarkLogic Server 11.0 Product Documentation
GET /v1/suggest

Summary

Retrieve a list of suggested constraint prefixes and/or constraint values that match (complete) the input query text, similar to the XQuery function search:suggest.

URL Parameters
partial-q? The partial search term for which suggestions should be retrieved. Default: The empty string ("").
q* A string query that constrains the returned suggestions. If this parameter appears multiple times, the constraining queries are AND'd together.
limit? The maximum number of suggestions to return. Default: 10.
cursor-position? The position of the cursor within the partial-q query text. That is, in making suggestions, the last position in the input string that should be considered for completion. Default: The length of the input string, so that the whole input query text string is considered.
options? The name of query options previously created via a PUT or POST request to the /v1/config/query service.
database? Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
format? The expected content type of the results. This is equivalent to specifying the format in the Accept header. The format parameter overrides the Accept header if both are present. Accepted value: xml and json. Default: xml.
Request Headers
Accept* The expected MIME type of the information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.
Response Headers
Content-type The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Response

On success, MarkLogic Server responds with a 200 status and a list of suggested completions in the response body. Results are returned as either XML or JSON, depending up on the format request parameter or the Accept header setting. See the examples below for details on the response data.

Required Privileges

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

You can use this service to generate a list of search term completions as a user enters text into a search box. Specify the input string in the partial-q parameter. If the user is typing into the middle of a previously entered search string, use the cursor-position request parameter to identify the end of the text to be matched in the input partial query.

Use the q request parameter to specify zero or more string queries with which to constrain the returned suggestions. These constraints act as filters on the returned suggestions. Use the string query grammar to express these constraints; for details, see Searching Using String Queries in the Search Developer's Guide.

Suggestions are generated from suggestion sources defined through query options. You can use named constraints, collections, value (range) lexicons, or word lexicons as suggestion sources. However, word lexicons are not recommended; collection and value lexicons usually yield the best performance. For details, See the default-suggestion-source and suggestion-source query options.

Query options named in the options request parameter must be pre-installed using the /config/query service. If no query options are specified, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options. To specify options on the fly, use POST /v1/suggest.

For more details, see Generating Search Term Completion Suggestions in the REST Application Developer's Guide.

Example

Assume the following query options are installed with the name "opt-suggest":

<options xmlns="http://marklogic.com/appservices/search">
 <default-suggestion-source>
   <range type="xs:string" facet="true">
      <element ns="" name="name"/>
   </range>
 </default-suggestion-source>
</options>

Then the following command generates search suggestions for the query
text "doc", using the above options:

$ curl --anyauth --user user:password -X GET \
    -H "Accept: application/xml" -i \
    'http://localhost:8000/v1/suggest?partial-q=doc&options=opt-suggest'

==> The values in the element <name/> that begin with the text "doc", as XML.
    MarkLogic Server returns a response similar to the following:

HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 256
Connection: Keep-Alive
Keep-Alive: timeout=5

<search:suggestions xmlns:search="http://marklogic.com/appservices/search">
  <search:suggestion>document-insert</search:suggestion>
  <search:suggestion>document-load</search:suggestion>
  <search:suggestion>document-query</search:suggestion>
</search:suggestions>

Example

Assume the following query options are installed with the name "opt-suggest":

<options xmlns="http://marklogic.com/appservices/search">
 <default-suggestion-source>
   <range type="xs:string" facet="true">
      <element ns="" name="name"/>
   </range>
 </default-suggestion-source>
</options>

$ curl --anyauth --user user:password -X GET \
    -H "Accept: application/json" -i \
    'http://localhost:8000/v1/suggest?partial-q=doc&options=opt-suggest'

==> The values in the element <name/> that begin with the text "doc", as JSON.
    MarkLogic Server returns a response similar to the following:

HTTP/1.1 200 OK
Content-type: application/json
Server: MarkLogic
Content-Length: 68
Connection: Keep-Alive
Keep-Alive: timeout=5

{"suggestions":[ "document-insert", "document-load", "document-query" ] }
Powered by MarkLogic Server | Terms of Use | Privacy Policy