POST /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. All occurrences of this query are AND'd together with any queries in the POST body.
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. See the Usage Notes for details on how these options are combined with options in the POST body.
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? You can use this parameter in conjunction with or instead of the request Content-type and Accept headers to indicate the input and/or output content type. The Content-type header takes precedence over format in most cases. The format parameter takes precedence over the Accept header in most cases. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide. Accepted values: json or 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.
Content-type The MIME type of the data in the request. Allowed values: application/json or application/xml. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide.
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.

The request body must contain a combined query (a serialized representation of a search:search), expressed as either XML or JSON. For details, see POST /v1/search and Specifying Dynamic Query Options with Combined Query in the REST Application Developer's Guide.

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

If a request includes both q parameters and a combined query, they are combined to constrain the results.

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.

Supply query options with the options request parameter or in the combined query in the request body. If no query options are specified in either the request parameter or the request body, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options.

If query options are supplied in both the options request parameter and the request body, the options are merged together. In cases of conflict, an option definition in the combined query overrides the one in the persistent options. Constraints defined in both option sources are preserved; in the event of a constraint name collision, the constraint defined in the request body takes precedence.

Query options named in the options request parameter must be pre-installed using the /config/query service. For details, see Configuring Query Options in the REST Application Developer's Guide.

The format parameter always overrides the Accept header and can be used as a fallback for the Content-type header. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide. If you not use the format parameter or an Accept header, the response data is XML.

For more details, see Generating Search Term Completion Suggestions in the REST Application Developer's Guide and the XQuery function search:suggest.

Example

$ cat combined-query.xml
<search xmlns="http://marklogic.com/appservices/search" >
  <qtext>document</qtext>
  <query>
    <container-query>
      <element ns="" name="category"/>
      <term-query><text>xdmp</text></term-query>
    </container-query>
  </query>
  <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>
</search>
    
$ curl --anyauth --user user:password -X POST -d @./combined-query.xml \
    -H "Content-type: application/xml" -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", 
    occurring in documents containing the query text "document" and
    a <category/> element containing the term "xdmp". 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:suggestions>
  

Example

$ cat combined-query.json
{ "search": {
    "qtext": [ "document" ],
    "query": {
      "container-query": {
        "element": {
          "ns": "",
          "name": "category"
        },
        "term-query": {
          "text": [ "xdmp" ]
        }
      }
    },
    "options": {
      "default-suggestion-source": {
        "range": {
          "type": "xs:string",
          "facet": true,
          "element": {
            "ns": "",
            "name": "name"
          }
        }
      }
    }
} }

$ curl --anyauth --user user:password -X POST -d @./combined-query.json \
    -H "Content-type: application/json" -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", 
    occurring in documents containing the query text "document" and
    a <category/> element containing the term "xdmp". MarkLogic Server
    returns a response similar to the following:

HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 51
Connection: Keep-Alive
Keep-Alive: timeout=5

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