MarkLogic Server 11.0 Product Documentation

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.

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

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"]}