This page was generated
January  28,  2016
4:07  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Client API - Search Functions

Use the interfaces in this section to perform query operations such searching using string, structured, combined, or Query By Example; key-value searches; lexicon browsing; and search suggestion generation. For details, see 'Using and Configuring Query Features' in the REST Application Developer's Guide.
REST Resource Summary
GET /v1/keyvalue Query the database based on the value of a JSON key, XML element, or XML element attribute.
GET /v1/qbe Search the database using a Query By Example or perform a multi-document read for documents that match a Query By Example.
POST /v1/qbe Search the database using a Query By Example or perform a multi-document read for documents that match a Query By Example.
DELETE /v1/search Remove documents in a collection or directory, or clear the database.
GET /v1/search Search the database using a string and/or structured query, returning search results and/or matching documents.
POST /v1/search Search the database using a structured query, supplied in the POST body; or search the database using a string or structured query with the query options and query combined in the POST body.
GET /v1/suggest 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.
POST /v1/suggest 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.
GET /v1/values Retrieve a list of lexicon configurations available for use with GET /v1/values/{name}.
GET /v1/values/{name} Query the values in a lexicon or range index, or find co-occurrences of values in multiple range indexes.
POST /v1/values/{name} Query the values in a lexicon or range index, or find co-occurrences of values in multiple range indexes.
REST Resource Detail
GET /v1/keyvalue
Summary:

Query the database based on the value of a JSON key, XML element, or XML element attribute.

Parameters:
key? : The name of a key in JSON content. The search is constrained to JSON key-value pairs with the specified key and a value matching the string passed in the value parameter. For searching XML content, use element and, optionally, attribute instead of key. Use of key precludes the use of the element or attribute parameters.
element? : The name of an XML element. The search is constrained to XML elements with a name matching the supplied string. For JSON content, use the key parameter instead. Use of element precludes use of the key parameter.
attribute? : Identifies the name of an XML attribute on the element named by the element parameter. This parameter constrains the search to attributes with the specified name found on elements matching the supplied element. If you use this parameter, you must also set the element parameter and may not use the key parameter.
value : The value of the key, element, or element attribute to match.
start? : The index of the first result to return. Results are numbered beginning with 1. Default: 1.
pageLength? : The maximum number of results to return in this request. Default: 10, or the length configured by the query options.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
view? : The view of the search results to return in the response. Accepted values: facets, results, metadata, all. Default: all.
format? : The type of the search 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.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection* : Filter search results so they include only matches in the named collection(s).
directory? : Filter search results so they only include matches from documents in the specified database directory.

Request Headers:
Accept*: The expected MIME type of the response. Accepted values: application/json or application/XML. Default: XML.

Response Headers:
Content-Type: The MIME type of the data in the response. The results will be in either XML or JSON, depending upon the value of the format parameter or the Accept header.

Required Privilege:

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

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


Response:

MarkLogic Server returns a 200 (OK) status, whether there are search matches or not. If XML output is requested, the response body contains a search:reponse node. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to the search:response elements.

Usage Notes:

Use the key and value parameters to query JSON documents inserted into the database using the /documents service. Use the element and attribute parameters with value to search XML documents.

The expected response type can be specified using either the format parameter or Accept header. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence.

Query options must be pre-installed using the /config/query service. If no query options are specified with the options parameter, the global default options are used.

For more details, see 'Querying Documents and Metadata' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET -i \
  'http://localhost:8003/v1/keyvalue?element=TITLE&value=Cymbeline'

==> A search:result for all documents occurrences of a TITLE element 
    with a value of "Cymbeline". MarkLogic Server returns the following:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 858
Connection: close

<search:response total="1" start="1" page-length="10" xmlns="" 
    xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/shakespeare/plays/cymbelin.xml" 
      path="fn:doc(&quot;/shakespeare/plays/cymbelin.xml&quot;)" 
      score="17920" confidence="0.336069" fitness="0.336069">
    <search:snippet>
      <search:match 
         path="fn:doc(&quot;/shakespeare/plays/cymbelin.xml&quot;)/PLAY">
        <search:highlight>Cymbeline</search:highlight>
      </search:match>
    </search:snippet>
  </search:result>
  <search:metrics>
    <search:query-resolution-time>PT0.015515S</search:query-resolution-time>
    <search:facet-resolution-time>PT0.000118S</search:facet-resolution-time>
    <search:snippet-resolution-time>PT0.027884S</search:snippet-resolution-time>
    <search:total-time>PT0.044953S</search:total-time>
  </search:metrics>
</search:response>
  
Example:
$ curl --anyauth --user user:password -X GET -i \
  -H "Accept: application/json" \
  http://localhost:8003/v1/keyvalue?element=TITLE&value=Cymbeline

==> A search:result for all documents occurrences of a TITLE element 
    with a value of "Cymbeline". MarkLogic Server returns the following
    (whitespace added for clarity):

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Content-type: application/json
Server: MarkLogic
Content-Length: 500
Connection: close

{
  "snippet-format": "snippet",
  "total": 1,
  "start": 1,
  "page-length": 10,
  "results": [
    {
      "index": 1,
      "uri": "/shakespeare/plays/cymbelin.xml",
      "path": "fn:doc(\"/shakespeare/plays/cymbelin.xml\")",
      "score": 15360,
      "confidence": 0.338445,
      "fitness": 0.338445,
      "matches": [
        {
          "path": "fn:doc(\"/shakespeare/plays/cymbelin.xml\")/PLAY",
          "match-text": [
            "\n",
            {
              "highlight": "Cymbeline"
            },
            "\n"
          ]
        }
      ]
    }
  ],
  "metrics": {
    "query-resolution-time": "PT0.009748S",
    "facet-resolution-time": "PT0.000087S",
    "snippet-resolution-time": "PT0.022979S",
    "total-time": "PT0.033092S"
  }
}
  

GET /v1/qbe
Summary:

Search the database using a Query By Example or perform a multi-document read for documents that match a Query By Example.

Parameters:
query? : A serialized Query By Example. For details, see 'Searching Using Query By Example' in the Search Developer's Guide.
start? : The index of the first result to return. Results are numbered beginning with 1. Default: 1.
pageLength? : The maximum number of results to return in this request. Default: 10, or the length configured by the query options.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
category* : The category of data to fetch about the matching documents. Category can be specified multiple times to retrieve any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to request all categories except content. You can only use this parameter when making a multi-document read request.
view? : The view of the results to return. Accepted values: results or structured. Default: For a normal search operation, results (returns the search results); for a multi-document read, none (return matching document content or metadata, but no search results). Use structured to return the combined query representation of your QBE, instead of search results or documents.
format? : The expected content type of the search results and document metadta if any are included in the response. For a normal search operation, setting format is equivalent to specifying the format in the Accept header and overrides the Accept header if both are present. For a multi-document read, use this parameter to control the format of returned metadata and the search response (if requested); format has no effect on returned document contents. Accepted value: xml and json. Default: xml.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection* : Filter search results to include only matches in the named collection(s).
directory? : Filter search results to include only matches from documents in the specified database directory.
transform? : Names a search result transformation previously installed via the /transforms service. If a search response is returned, the transformation is applied to the <search:response/> after applying user-defined transforms defined in the query options using <transform-results>. For details, see 'Transforming the Search Response' in the REST Application Developer's Guide. On a multi-document read request, the transform is applied to each returned document as well as the search response (if a search response is requested).
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1. Transform parameter values are passed to the transform named in the transform request parameter.

Request Headers:
Accept: The expected MIME type of the response. Accepted values: application/json, application/xml, multipart/mixed. Default: application/xml. When you use multipart/mixed, the request is a multi-document read rather than just a search; see the Usage Notes.

Response Headers:
Content-Type: The MIME type of the data in the response. Search results and metadata will be in either XML or JSON, depending upon the value of the format parameter (or the Accept header for a normal search operation). For a multi-document read, the result is multipart/mixed response containing content and/or metadata, and optionally containing a search response.
vnd.marklogic.start: For a multi-document read operation, the starting index of the results in the response. The header value is always 1 unless you use the start and pageLength parameters to incrementally retrieve results.
vnd.marklogic.pageLength: For a multi-document read operation, the number of results in the response. See the pageLength parameter.
vnd.marklogic.result-estimate: For a multi-document read operation, an estimate of the total number of matches to the input query. This is equivalent to total in the search:response.

Required Privilege:

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

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


Response:

For a normal search operation, MarkLogic Server returns a 200 (OK) status, whether there are search matches or not. If XML output is requested, the response body contains either a search:reponse node or a search:query, depending on the setting of the view request parameter. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to the search:response or search:query elements.

For a multi-document read, by default MarkLogic Server returns status 200 (OK) only if there are matching documents and a 404 (Not Found) if there are no matching documents. If you use the view request parameter to include search results or a structured query in the response, then the return status is 200 (OK) whether there are matching documents or not.

For a multi-document read, the default response body is multipart/mixed data containing content and/or metadata for each document matching the input query. If you use a view parameter to include search results in the response, the search response is in the first part. For details, see 'Reading Multiple Documents Matching a Query' in the REST Application Developer's Guide.


Usage Notes:

A Query By Example is an encapsulation of a query expressed as an annotated example of the target document(s). For details, see 'Searching Using Query By Example' in the Search Developer's Guide. Set the query request parameter to a serialized Query By Example, expressed as either XML or JSON.

Query By Example is intended primarily for rapid prototyping. Once you are satisfied with your query characteristics, you can use the view=structured request parameter to retrieve the structured query representation of your QBE, and use this representation with the /search or /values services for best performance.

You can use this request as a simple database search operation that returns search results, or a multi-document read of content and/or metadata matching a QBE. A multi-document read can also return search results, but does not do so by default; see the view parameter. A multi-document read is distinguished from a normal search operation by setting the Accept header to multipart/mixed; for details, see 'Reading Multiple Documents Matching a Query' in the REST Application Developer's Guide

You can combine validation with search by including both the view=validate and view=results request parameters in your search. No other view values may be used together.

Query options named in the options request parameter must be pre-installed using the /config/query service. If no query options are specified in the options request parameter, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options.

When MarkLogic Server evaluates a QBE, it constructs an equivalent structured query and query options. These query options are generated by merging the options required to realize the QBE with the general options in effect for the request (options specified through the options parameter or the default options).

For more details, see 'Using Query By Example to Prototype a Query' in the REST Application Developer's Guide.


Example:
Assume you URL-encode the following query. This query searches for XML
documents containing an <author/> element containing the value "Mark Twain"
and an <edition/> element whose <code>format</code> parameter has the
value "paperback".
The following QBE matches XML documents containing an <author/> element with
the value "Mark Twain" and an <edition/> element with a <format/> attribute
with the value "paperback". URL-encode the query to use it in a GET request.

<q:qbe xmlns:q="http://marklogic.com/appservices/querybyexample">
  <q:query>
    <author>Mark Twain</author>
    <edition format="paperback"/>
  </q:query>
</q:qbe>

The following command searches using the URL-encoded query:

$ curl --anyauth --user admin:adm1n -i -X GET \
    -H "Content-type: application/xml" -H "Accept: application/xml" \
    'http://localhost:8003/v1/qbe?query=%3Cq%3Aqbe%20xmlns%3Aq%3D%22http%3A%2F%2Fmarklogic.com%2Fappservices%2Fquerybyexample%22%3E%3Cq%3Aquery%3E%3Cauthor%3EMark%20Twain%3C%2Fauthor%3E%3Cedition%20format%3D%22paperback%22%2F%3E%3C%2Fq%3Aquery%3E%3C%2Fq%3Aqbe%3E'

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 967
Connection: Keep-Alive
Keep-Alive: timeout=5

<search:response snippet-format="snippet" total="1" start="1" page-length="10" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns=""
    xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/books/sawyer.xml" 
      path="fn:doc(&quot;/books/sawyer.xml&quot;)" score="50176" 
      confidence="0.646346" fitness="0.683733" 
      href="/v1/documents?uri=%2Fbooks%2Fsawyer.xml" 
      mimetype="text/xml" format="xml">
    <search:snippet>
      <search:match path="fn:doc(&quot;/books/sawyer.xml&quot;)/book">  
        <search:highlight>Mark Twain</search:highlight>  
      </search:match>
    </search:snippet>
  </search:result>
  <search:metrics>
    <search:query-resolution-time>PT0.007064S</search:query-resolution-time>
    <search:facet-resolution-time>PT0.000095S</search:facet-resolution-time>
    <search:snippet-resolution-time>PT0.001345S</search:snippet-resolution-time>
    <search:total-time>PT0.010017S</search:total-time>
  </search:metrics>
</search:response>
  
Example:
The following QBE matches JSON documents containing an "author" key with
the value "Mark Twain" and an "edition" key-value pair that contains a
"format" key with the value "paperback". URL-encode the query to use it 
in a GET request.

{ "$query": {
    "author": "Mark Twain",
    "edition": { "format": "paperback" }
} }

The following command searches using the URL-encoded query:

$ curl --anyauth --user user:password -i -X GET \
    -H "Content-type: application/json" -H "Accept: application/json" \
    'http://localhost:8003/v1/qbe?query=%7B%22%24query%22%3A%7B%22author%22%3A%22Mark%20Twain%22%2C%22edition%22%3A%7B%22format%22%3A%22paperback%22%7D%7D%7D'

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

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

{
  "snippet-format": "snippet",
  "total": 1,
  "start": 1,
  "page-length": 10,
  "results": [ {
      "index": 1,
      "uri": "/books/sawyer.json",
      "path": "fn:doc(\"/books/sawyer.json\")",
      "score": 50176,
      "confidence": 0.646346,
      "fitness": 0.683733,
      "href": "/v1/documents?uri=%2Fbooks%2Fsawyer.json",
      "mimetype": "application/json",
      "format": "text",
      "matches": [
        {
          "path": "fn:doc(\"/books/sawyer.json\")/*:json/*:book/*:author",
          "match-text": [ { "highlight": "Mark Twain" } ]
        },
        {
          "path": "fn:doc(\"/books/sawyer.json\")/*:json/*:book/*:edition/*:json[1]/*:format", 
          "match-text": [ { "highlight": "paperback" } ]
        }
      ]
  } ],
  "metrics": {
    "query-resolution-time": "PT0.003687S",
    "facet-resolution-time": "PT0.00007S",
    "snippet-resolution-time": "PT0.001083S",
    "total-time": "PT0.007423S"
  }
}
  
Example:
The following QBE matches JSON documents containing "myphrase". URL encode 
the query to use it in a GET request.

{ "$query": { "$word": "myphrase" } }

The following command uses the URL-encoded query above to retrieve the
contents of all documents matching the query:

$ curl --anyauth --user user:password -i -X GET \
    -H "Content-type: application/json" \
    -H "Accept: multipart/mixed; boundary=BOUNDARY" \
    'http://localhost:8003/v1/qbe?query=%7B%20%22%24query%22%3A%20%7B%20%22%24word%22%3A%20%22myphrase%22%20%7D%20%7D'

HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=BOUNDARY
vnd.marklogic.start: 1
vnd.marklogic.pageLength: 10
vnd.marklogic.result-estimate: 1
Server: MarkLogic
Content-Length: 185
Connection: Keep-Alive
Keep-Alive: timeout=5

--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc2.json; category=content; 
                     format=json
Content-Length: 19

{"key":"some json"}
--BOUNDARY--
  

POST /v1/qbe
Summary:

Search the database using a Query By Example or perform a multi-document read for documents that match a Query By Example. The QBE is passed in the request body.

Parameters:
start? : The index of the first result to return. The first result is index 1. Default: 1.
pageLength? : The maximum number of results to return in this request. Default: 10, or the length configured by the query options.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
category* : The category of data to fetch about the matching documents. Category can be specified multiple times to retrieve any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to request all categories except content. You can only use this parameter when making a multi-document read request.
view* : The view of the search results to return. Accepted values: result, validate, or structured. Default: For a normal search operation, result, which returns the search results; for a multi-document read, none (return matching document content and/or metadata, but no search results). Use structured to return the combined query representation of your QBE, instead of search results or content. Use validate alone to validate your query without performing a search. Combine validate and result to validate your query and proceed with the search only if the query is valid. For details, see the Usage Notes.
format? : The MIME type of the search results and returned metadata. For a normal search operation, this is equivalent to specifying the format in the Accept header, and it overrides the Accept header if both are present. For a multi-document read, use this parameter to control the format of returned metadata and the search response (if requested); format has no effect on returned document content. Accepted values: json or xml. Default: xml. If this parameter is present, the data in the POST body must also use this format.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection* : Filter search results so they include only matches in the named collection(s).
directory? : Filter search results so they only include matches from documents in the specified database directory.
transform? : Names a search result transformation previously installed via the /transforms service. If a search response is returned, the transformation is applied to the <search:response/> after applying user-defined transforms defined in the query options using <transform-results>. For details, see 'Transforming the Search Response' in the REST Application Developer's Guide. On a multi-document read request, the transform is applied to each returned document as well as the search response (if a search response is requested).
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1. Transform parameters are passed to the transform named in the transform parameter.

Request Headers:
Accept: The expected MIME type of the response. Accepted values: application/json or application/XML. Default: XML.
Content-Type: The MIME type of the data in the POST body. Accepted values: application/json or application/XML.

Response Headers:
Content-Type: The MIME type of the data in the response. Search results and metadata will be in either XML or JSON, depending upon the value of the format parameter (or the Accept header for a normal search operation). For a multi-document read, the result is multipart/mixed response containing content and/or metadata, and optionally containing a search response.

Required Privilege:

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

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


Response:

For a normal search operation, MarkLogic Server returns a 200 (OK) status, whether there are search matches or not. If XML output is requested, the response body contains either a search:reponse node or a search:query, depending on the setting of the view request parameter. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to the search:response or search:query elements.

For a multi-document read, by default MarkLogic Server returns status 200 (OK) only if there are matching documents and a 404 (Not Found) if there are no matching documents. If you use the view request parameter to include search results or a structured query in the response, then the return status is 200 (OK) whether there are matching documents or not.

For a multi-document read, the default response body is multipart/mixed data containing content and/or metadata for each document matching the input query. If you use a view parameter to include search results in the response, the search response is in the first part. For details, see 'Reading Multiple Documents Matching a Query' in the REST Application Developer's Guide.


Usage Notes:

A Query By Example (QBE) is an encapsulation of a query expressed as an annotated example of the target document(s). Selected portions of the query may be modified by embedded query options. For details, see 'Searching Using Query By Example' in the Search Developer's Guide.

QBE is intended primarily for rapid prototyping. Once you are satisfied with your query characteristics, you can use the view=structured request parameter to retrieve the structured query representation of your QBE and use the structured query with the /search or /values services for best performance.

You can use this request as a simple database search operation that returns search results, or a multi-document read of content and/or metadata matching a QBE. A multi-document read can also return search results, but does not do so by default; see the view parameter. A multi-document read is distinguished from a normal search operation by setting the Accept header to multipart/mixed; for details, see 'Reading Multiple Documents Matching a Query' in the REST Application Developer's Guide

The request body must contain a QBE, expressed in either XML or JSON. Set the Content-Type header appropriately. For query syntax, see 'Searching Using Query By Example' in the Search Developer's Guide.

You can combine validation with search by including both the view=validate and view=results request parameters in your search. No other view values may be used together. If you use view=validate alone, no search is performed, and the request returns validation results.

Query options named in the options request parameter must be pre-installed using the /config/query service. If no query options are specified in the options request parameter, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options.

When MarkLogic Server processes a Query By Example, it constructs an equivalent structured query and query options. These query options are generated by merging the options required to realize the QBE with the general options in effect for the request (options specified through the options parameter or the default options).

For more details, see 'Using Query By Example to Prototype a Query' in the REST Application Developer's Guide.


Example:
The following QBE matches XML documents containing an <author/> element 
that contain the value "Mark Twain" and an <edition/> element whose 
<code>format</code> attribute has the value "paperback".

$ cat qbe.xml
<q:qbe xmlns:q="http://marklogic.com/appservices/querybyexample">
  <q:query>
    <author>Mark Twain</author>
    <edition format="paperback"/>
  </q:query>
</q:qbe>

The following command performs a search by passing the above query in 
the POST body:

$ curl --anyauth --user admin:adm1n -i -X POST -d @./qbe.xml \
    -H "Content-type: application/xml" -H "Accept: application/xml" \
    http://localhost:8003/v1/qbe

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 967
Connection: Keep-Alive
Keep-Alive: timeout=5

<search:response snippet-format="snippet" total="1" start="1" page-length="10" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema" 
    xmlns="" xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/books/sawyer.xml" 
      path="fn:doc(&quot;/books/sawyer.xml&quot;)" score="50176" 
      confidence="0.646346" fitness="0.683733" 
      href="/v1/documents?uri=%2Fbooks%2Fsawyer.xml" 
      mimetype="text/xml" format="xml">
    <search:snippet>
      <search:match path="fn:doc(&quot;/books/sawyer.xml&quot;)/book">
        <search:highlight>Mark Twain</search:highlight>  
      </search:match>
    </search:snippet>
  </search:result>
  <search:metrics>
    <search:query-resolution-time>PT0.007064S</search:query-resolution-time>
    <search:facet-resolution-time>PT0.000095S</search:facet-resolution-time>
    <search:snippet-resolution-time>PT0.001345S</search:snippet-resolution-time>
    <search:total-time>PT0.010017S</search:total-time>
  </search:metrics>
</search:response>
  
Example:
The following QBE matches JSON documents containing an "author" key with
the value "Mark Twain" and an "edition" key-value pair that contains a
"format" key with the value "paperback". 

$ cat qbe.json
{ "$query": {
    "author": "Mark Twain",
    "edition": { "format": "paperback" }
} }

The following command performs a search by passing the above QBE in the
POST body:

$ curl --anyauth --user user:password -i -X POST -d @./qbe.json \
    -H "Content-type: application/json" -H "Accept: application/json" \
    http://localhost:8003/v1/qbe

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

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

{
  "snippet-format": "snippet",
  "total": 1,
  "start": 1,
  "page-length": 10,
  "results": [ {
      "index": 1,
      "uri": "/books/sawyer.json",
      "path": "fn:doc(\"/books/sawyer.json\")",
      "score": 50176,
      "confidence": 0.646346,
      "fitness": 0.683733,
      "href": "/v1/documents?uri=%2Fbooks%2Fsawyer.json",
      "mimetype": "application/json",
      "format": "text",
      "matches": [
        {
          "path": "fn:doc(\"/books/sawyer.json\")/*:json/*:book/*:author",
          "match-text": [ { "highlight": "Mark Twain" } ]
        },
        {
          "path": "fn:doc(\"/books/sawyer.json\")/*:json/*:book/*:edition/*:json[1]/*:format", 
          "match-text": [ { "highlight": "paperback" } ]
        }
      ]
  } ],
  "metrics": {
    "query-resolution-time": "PT0.003687S",
    "facet-resolution-time": "PT0.00007S",
    "snippet-resolution-time": "PT0.001083S",
    "total-time": "PT0.007423S"
  }
}
  
Example:
The following QBE matches JSON documents containing "myphrase". URL encode 
the query to use it in a GET request.

{ "$query": { "$word": "myphrase" } }

The following command passes the query above in the POST body
to retrieve the contents of all documents matching the query:

$ curl --anyauth --user user:password -i -X POST -d @./qbe.json \
    -H "Content-type: application/json" \
    -H "Accept: multipart/mixed; boundary=BOUNDARY" \
    'http://localhost:8003/v1/qbe'

HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=BOUNDARY
vnd.marklogic.start: 1
vnd.marklogic.pageLength: 10
vnd.marklogic.result-estimate: 1
Server: MarkLogic
Content-Length: 185
Connection: Keep-Alive
Keep-Alive: timeout=5

--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc2.json; category=content; 
                     format=json
Content-Length: 19

{"key":"some json"}
--BOUNDARY--
  

DELETE /v1/search
Summary:

Remove documents in a collection or directory, or clear the database.

Parameters:
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection? : Remove documents in the named collection.
directory? : Remove documents in the named directory.

Required Privilege:

Deleting a directory or collection requires the rest-writer role, or the following privileges:

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

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

Clearing the database requires the rest-admin role, or the following privileges:

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

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

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


Response:

Upon success, MarkLogic Server returns a status 204.

Usage Notes:

A request with no parameters removes all documents in all non-replica forests attached to the content database. The rest-admin role is required for this operation. If the requesting user does not have the required role, a 400 status is returned.

All other requests must supply either one directory or one collection. All matching documents in the directory or collection are deleted.

A request to remove selected documents, rather than a full database clear, requires the rest-writer role, and must include at least one collection or directory parameter.


Example:
  

GET /v1/search
Summary:

Search the database using a string and/or structured query, returning search results and/or matching documents.

Parameters:
q? : A string query. For details, see 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide and cts:query.
structuredQuery? : A structured search query string. That is, a serialized representation of a search:query element. See 'Searching Using Structured Queries' in the Search Developer's Guide.
start? : The index of the first result to return. Results are numbered beginning with 1. Default: 1.
pageLength? : The maximum number of results to return in this request. Default: 10, or the length configured by the query options.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
view? : The view of the search results to return in the response. Accepted values: facets, results, metadata, all. Default: all for a normal search, none for a multi-document read.
category* : The category of data to fetch about the matching documents. Category can be specified multiple times to retrieve any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to request all categories except content. You can only use this parameter when making a multi-document read request.
format? : The content type of the request body, the response search results, and any metadata returned by a multi-document read. For a normal search operation, setting format is equivalent to setting the Accept and Content-type headers. The format parameter overrides the Accept and Content-type headers for a normal search operation. For a multi-document read, use this parameter to control the format of returned metadata and the search response (if requested); format has no effect on returned content. Accepted values: json or xml (default). For details, see 'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection* : Filter search results to include only matches in the named collection(s).
directory? : Filter search results to include only matches from documents in the specified database directory.
transform? : Names a search result transformation previously installed via the /transforms service. The transformation is applied to the <search:response/> after applying user-defined transforms defined in the query options using <transform-results>. For details, see 'Transforming the Search Response' in the REST Application Developer's Guide.
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1. Transform parameters are passed to the transform named in the transform parameter.

Request Headers:
Accept: The expected MIME type of the response. Accepted values: application/json, application/xml, multipart/mixed. Default: application/xml. When you use multipart/mixed, the request is a multi-document read rather than just a search; see the Usage Notes.

Response Headers:
Content-Type: The MIME type of the data in the response. For a normal search operation, the results are either XML or JSON, depending upon the value of the format parameter or the Accept header. For a multi-document read, the result is a multipart/mixed response body containing matching content or metadata; see the Usage Notes.
vnd.marklogic.start: For a multi-document read operation, the starting index of the results in the response. The header value is always 1 unless you use the start and pageLength parameters to incrementally retrieve results.
vnd.marklogic.pageLength: For a multi-document read operation, the number of results in the response. See the pageLength parameter.
vnd.marklogic.result-estimate: For a multi-document read operation, an estimate of the total number of matches to the input query. This is equivalent to total in the search:response.

Required Privilege:

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

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


Response:

For a normal search operation, MarkLogic Server returns a 200 (OK) status, whether there are search matches or not. If XML output is requested, the response body contains a search:reponse node. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to the search:response elements.

For a multi-document read, by default MarkLogic Server returns status 200 (OK) only if there are matching documents and a 404 (Not Found) if there are no matching documents. If you use the view request parameter to include search results or facets in the response, then the return status is 200 (OK) whether there are matching documents or not.

For a multi-document read, the response body is multipart/mixed data containing content and/or metadata for each document that matches the input query. If you use a view parameter to include search results in the response, the search response, facets, or metadata are in the first part. For details, see 'Reading Multiple Documents Matching a Query' in the REST Application Developer's Guide.


Usage Notes:

You can use this request as a simple database search operation that returns search results, or a multi-document read of content and/or metadata matching a query. A multi-document read can also return search results, but does not do so by default; see the view parameter. A multi-document read is distinguished from a normal search operation by setting the Accept header to multipart/mixed.

For details, see 'Reading Multiple Documents Matching a Query' in the REST Application Developer's Guide and 'Querying Documents and Metadata' in the REST Application Developer's Guide.

When performing a multi-document read, use the category parameter to specify whether to return content, metadata, and/or a metadata subset for matching documents. By default, only content is returned. Use the view parameter to include search results and facets in the response. You can also use the view parameter to control results in a normal search operation.

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 pre-configure query options, use the /config/query service. Use a POST request to specify dynamic query options instead of (or in addition to) pre-installing persistent query options.


Example:
$ curl --anyauth --user username:password -X GET \
    'http://localhost:8003/v1/search?q=infinite NEAR variety'

==> Search the database for documents where "infinite" appears near
    "variety". MarkLogicServer returns an XML search response similar
    to the following:

<search:response total="1" start="1" page-length="10"
   xmlns="" xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/shakespeare/plays/a_and_c.xml"
     path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)"
     score="46720" confidence="0.434464" fitness="0.50812">
    <search:snippet>
      <search:match path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)
        /PLAY/ACT[2]/SCENE[2]/SPEECH[86]/LINE[3]">Her 
        <search:highlight>infinite</search:highlight> 
        <search:highlight>variety</search:highlight>: other women cloy
      </search:match>
    </search:snippet>
  </search:result>
  <search:qtext>infinite NEAR variety</search:qtext>
  <search:metrics>
    <search:query-resolution-time>PT1.11403S</search:query-resolution-time>
    <search:snippet-resolution-time>PT0.907914S</search:snippet-resolution-time>
    <search:total-time>PT2.022321S</search:total-time>
  </search:metrics>
</search:response>
  
Example:
$ curl --anyauth --user username:password -X GET \
  -H "Accept: application/json" \
  'http://localhost:8003/v1/search?q=infinite NEAR variety

==> Search the database for documents where "infinite" appears near
    "variety". MarkLogicServer returns a JSON search response similar
    to the following:

{
  "snippet-format": "snippet",
  "total": 1,
  "start": 1,
  "page-length": 10,
  "results": [
    {
      "index": 1,
      "uri": "/shakespeare/plays/a_and_c.xml",
      "path": "fn:doc(\"/shakespeare/plays/a_and_c.xml\")",
      "score": 17792,
      "confidence": 0.364254,
      "fitness": 0.480312,
      "matches": [
        {
          "path": "fn:doc(\"/shakespeare/plays/a_and_c.xml\")/PLAY/ACT[2]
          /SCENE[2]/SPEECH[86]/LINE[3]",
          "match-text": [
            "Her ",
            {
              "highlight": "infinite"
            },
            " ",
            {
              "highlight": "variety"
            },
            ": other women cloy"
          ]
        }
      ]
    }
  ],
  "qtext": "infinite NEAR variety",
  "metrics": {
    "query-resolution-time": "PT0.014055S",
    "facet-resolution-time": "PT0.000082S",
    "snippet-resolution-time": "PT0.064129S",
    "total-time": "PT0.078551S"
  }
}
  
Example:
curl --anyauth --user user:password -X GET -i \
  -H "Accept: multipart/mixed; boundary=BOUNDARY" \
  http://localhost:8003/v1/search?q=myphrase

==> Retrieve all documents that match the query "myphrase". MarkLogic
    Server responds similar to the following:

HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=BOUNDARY
vnd.marklogic.start: 1
vnd.marklogic.pageLength: 10
vnd.marklogic.result-estimate: 3
Server: MarkLogic
Content-Length: 589
Connection: Keep-Alive
Keep-Alive: timeout=5

--BOUNDARY
Content-Type: text/xml
Content-Disposition: attachment; filename=doc1.xml; category=content; 
                     format=xml
Content-Length: 60

<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY
Content-Type: text/xml
Content-Disposition: attachment; filename=doc3.xml; category=content; format=xml
Content-Length: 60

<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc2.json; category=content; 
                     format=json
Content-Length: 19

{"key":"some json"}
--BOUNDARY--
  
Example:
curl --anyauth --user user:password -X GET -i \
  -H "Accept: multipart/mixed; boundary=BOUNDARY" \
  'http://localhost:8003/v1/search?q=myphrase&view=results&category=properties&format=json'

==> Retrieve the search results (view=results) and the properties metadata 
    (category=properties) for all documents matching the query "myphrase".
    The search results are returned in the first part of the multipart
    response. The search results and metadata are returned as JSON because
    of the format=json parameter. MarkLogic responds with output similar
    to the following:

HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=BOUNDARY
vnd.marklogic.start: 1
vnd.marklogic.pageLength: 10
vnd.marklogic.result-estimate: 3
Server: MarkLogic
Content-Length: 1788
Connection: Keep-Alive
Keep-Alive: timeout=5

--BOUNDARY
Content-Type: application/json
Content-Disposition: inline
Content-Length: 1074

{
  "snippet-format": "snippet",
  "total": 3,
  "start": 1,
  "page-length": 10,
  "results": [
    {
      "index": 1,
      "uri": "doc1.xml",
      "path": "fn:doc(\"doc1.xml\")",
      "score": 14336,
      "confidence": 0.3498099,
      "fitness": 0.7490314,
      "href": "/v1/documents?uri=doc1.xml",
      "mimetype": "text/xml",
      "format": "xml",
      "matches": [
        {
          "path": "fn:doc(\"doc1.xml\")/root",
          "match-text": [
            {
              "highlight": "some"
            },
            " xml"
          ]
        }
      ]
    },
    ...
  ],
  "qtext": "some",
  "metrics": {
    "query-resolution-time": "PT0.008052S",
    "snippet-resolution-time": "PT0.003433S",
    "total-time": "PT0.012944S"
  }
}
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc1.xml; category=properties; 
                     format=json
Content-Length: 46

{"properties":{"my-prop":"value1"}}
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc3.xml; category=properties; 
                     format=json
Content-Length: 46

{"properties":{"my-prop":"value2"}}
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc2.json; category=properties; 
                     format=json
Content-Length: 46

{"properties":{"my-prop":"value3"}}
--BOUNDARY--
  

POST /v1/search
Summary:

Search the database using a structured query, supplied in the POST body; or search the database using a string or structured query with the query options and query combined in the POST body. Returns search results, matching content and/or metadata, or both.

Parameters:
q? : A string query. For details, see 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide and cts:query. This query is AND'd with the query(s) in the request body.
start? : The index of the first result to return. The first result is index 1. Default: 1.
pageLength? : The maximum number of results to return in this request. Default: 10, or the length configured by the query options.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
view? : The view of the search results to return in the response. Accepted values: facets, results, metadata, uris, all (default) for a normal search, none for a multi-document read.
category* : The category of data to fetch about the matching documents. Category can be specified multiple times to retrieve any combination of content and metadata. Valid categories: content (default), metadata, collections, permissions, properties, and quality. Use metadata to request all categories except content. You can only use this parameter when making a multi-document read request.
format? : The content type of the request body, the response search results, and any metadata returned by a multi-document read. For a normal search operation, setting format is equivalent to setting the Accept and Content-type headers. The format parameter overrides the Accept and Content-type headers for a normal search operation. For a multi-document read, use this parameter to control the format of returned metadata and the search response (if requested); format has no effect on returned content. Accepted values: json or xml. Default: xml.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
collection* : Filter search results so they include only matches in the named collection(s).
directory? : Filter search results so they only include matches from documents in the specified database directory.
transform? : Names a search result transformation previously installed via the /transforms service. If a search response is returned, the transformation is applied to the <search:response/> after applying user-defined transforms defined in the query options using <transform-results>. For details, see 'Transforming the Search Response' in the REST Application Developer's Guide. On a multi-document read request, the transform is applied to each returned document as well as the search response (if a search response is requested).
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1. Transform parameter values are passed to the transform named in the transform request parameter.

Request Headers:
Accept: The expected MIME type of the response. Accepted values: application/json, application/xml, multipart/mixed. Default: application/xml. When you use multipart/mixed, the request is a multi-document read rather than just a search; see the Usage Notes.
Content-Type*: The MIME type of the data in the POST body. Accepted values: application/json or application/XML. Setting the format parameter value overrides this header.

Response Headers:
Content-Type: The MIME type of the data in the response. For a normal search operation, the results are either XML or JSON, depending upon the value of the format parameter or the Accept header. For a multi-document read, the result is a multipart/mixed response body containing matching content or metadata; see the Usage Notes.
vnd.marklogic.start: For a multi-document read operation, the starting index of the results in the response. The header value is always 1 unless you use the start and pageLength parameters to incrementally retrieve results.
vnd.marklogic.pageLength: For a multi-document read operation, the number of results in the response. See the pageLength parameter.
vnd.marklogic.result-estimate: For a multi-document read operation, an estimate of the total number of matches to the input query. This is equivalent to total in the search:response.

Required Privilege:

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

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


Response:

For a normal search operation, MarkLogic Server returns a 200 (OK) status, whether there are search matches or not. If XML output is requested, the response body contains a search:reponse node. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to the search:response elements.

For a multi-document read, by default MarkLogic Server returns status 200 (OK) only if there are matching documents and a 404 (Not Found) if there are no matching documents. If you use the view request parameter to include search results or facets in the response, then the return status is 200 (OK) whether there are matching documents or not.

For a multi-document read, the response body is multipart/mixed data containing content and/or metadata for each document that matches the input query. If you use a view parameter to include search results in the response, the search response, facets, or metadata are in the first part. For details, see 'Reading Multiple Documents Matching a Query' in the REST Application Developer's Guide.


Usage Notes:

You can use this request as a simple database search operation that returns search results, or a multi-document read of content and/or metadata matching a query. A multi-document read can also return search results, but does not do so by default; see the view parameter. A multi-document read is distinguished from a normal search operation by setting the Accept header to multipart/mixed.

For details, see 'Reading Multiple Documents Matching a Query' in the REST Application Developer's Guide and 'Querying Documents and Metadata' in the REST Application Developer's Guide.

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

When performing a multi-document read, use the category parameter to specify whether to return content, metadata, and/or a metadata subset for matching documents. By default, only content is returned. Use the view parameter to include search results and facets in the response. You can also use the view parameter to control results in a normal search operation.

For a normal search operation, the format parameter always overrides the Content-type and Accept headers. If you want the request and response bodies to use different content types, you must use the headers instead of the format parameter. If you do not use the format parameter or an Accept header, the response data is XML.

For a multi-document read, the format parameter overrides the request Content-type header and determines the format of the search response, if one is included, and any returned document metadata. With a multi-document read, you cannot specify different formats for the request body and response database because the Accept header must be multipart/mixed.

Supply query options with the options request parameter or 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 the body contains a structured query, use the options request parameter to specify custom query options. If the body contains a combined query, use the options request parameter and/or the options component of the combined query.

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.

A combined query encapsulates options and query in a single object. A combined query can contain just options, just a structured query, just a string query, or any combination of the three.

Use the following template to construct a combined query in XML:

<search:search xmlns:search="http://marklogic.com/appservices/search">
  <!-- Include a structured query and/or a string query -->
  <search:query>
    <!-- structured query using same syntax as standalone search:query -->
  </search:query>
  <search:qtext>your string query</search:qtext>
  <search:options>
    <!-- options using same syntax as standalone search:options -->
  </search:options>
</search:search> 

Use the following template to construct a combined query in JSON:

{"search": {
  "query": { same syntax as a standalone structured query },
  "qtext": { "your string query here" },
  "options": { same syntax as standalone query options }
}} 

The query options within a combined query use the same option syntax as standalone, persistent query options; for details, see 'Appendix A: JSON Query Options Reference' in the REST Application Developer's Guide or 'Appendix B: XML Query Options Reference' in the REST Application Developer's Guide. Similarly, the sub-queries in a combined query use the syntax of a standalone structured or string query. For details, see 'Searching Using Structured Queries' in the Search Developer's Guide or 'Searching Using String Queries' in the Search Developer's Guide.

For more details, see 'Querying Documents and Metadata' in the REST Application Developer's Guide.


Example:
$ cat > s-query.txt
<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:near-query>
    <search:term>
      <search:text>infinite</search:text>
    </search:term>
    <search:term>
      <search:text>variety</search:text>
    </search:term>
    <search:distance>3</search:distance>
  </search:near-query>
</search:query>
^D

$ curl --anyauth --user user:password -X POST -d@'./s-query.txt' -i \
  -H "Content-type:application/xml"  http://localhost:8003/v1/search

==> Perform a query for "infinite" occurring within 3 terms of 
    "variety", and receive the search:response XML results in 
    the response body. The response has the following form:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 875
Connection: close

<search:response total="1" start="1" page-length="10" 
    xmlns="" xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/shakespeare/plays/a_and_c.xml" 
       path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)" 
       score="43648" confidence="0.418356" fitness="0.50947">
    <search:snippet>
      <search:match path="...">
        Her <search:highlight>infinite</search:highlight> 
        <search:highlight>variety</search:highlight>: other women cloy
      </search:match>
    </search:snippet>
  </search:result>
  <search:metrics>
    <search:query-resolution-time>
      PT1.087968S
    </search:query-resolution-time>
    <search:snippet-resolution-time>
      PT1.028637S
    </search:snippet-resolution-time>
    <search:total-time>PT2.117041S</search:total-time>
  </search:metrics>
</search:response>
  
Example:
$ cat ./combined-query.xml
<search xmlns="http://marklogic.com/appservices/search">
  <qtext>alas</qtext>
  <query>
    <near-query>
      <term-query>
        <text>Yorick</text>
      </term-query>
      <term-query>
        <text>Horatio</text>
      </term-query>
    </near-query>
  </query>
  <options>
    <return-results>false</return-results>
    <return-metrics>false</return-metrics>
  </options>
</search>
$ curl --anyauth --user user:password -X POST -d@./combined-options \
    -i -H "content-type: application/xml" http://localhost:8003/v1/search

==> Perform a query for "Yorick" near "Horatio", using a combined query.
    Dynamic options in the POST body disable returning results and metrics.
    The response has the following form:

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 189
Connection: Keep-Alive
Keep-Alive: timeout=5

<search:response snippet-format="snippet" total="1" start="1" page-length="10" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  xmlns="" xmlns:search="http://marklogic.com/appservices/search"/>

The following is the equivalent combined query request body as JSON:
{
  "search": {
    "qtext" : "alas",
    "query" : {
      "near-query" : {
        "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
      }
    },
    "options" : {
      "return-results" : false,
      "return-metrics" : false
    }
  }
}
  

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.

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.
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.

Required Privilege:

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

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


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.

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:8003/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:8003/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" ] }
  

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.

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.
format? : The content type of the request body and the response. This is equivalent to setting Accept and Content-type headers. The format parameter overrides the Accept and Content-type headers. Allowed values: json, 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. Ignored if the request includes a format parameter.

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.

Required Privilege:

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

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


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.

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 Content-type and Accept headers. You must use the headers intead of the format parameter to specify different MIME types for the request body and the response. 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:8003/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:8003/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"]}
  

GET /v1/values
Summary:

Retrieve a list of lexicon configurations available for use with GET /v1/values/{name}.

Parameters:
format? : Specifies the MIME type of the response content, as an alternative to specifying format via the Accept header. Accepted values: json and xml (default). If there is no format parameter, the format must be specified in the Accept header.
options? : The query options for which to list available lexicon configurations.

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.

Required Privilege:

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

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


Response:

Upon success, MarkLogic Server returns a 200 status, with an XML or JSON listing of available named lexicon configurations in the response body.

MarkLogic Server returns a 400 (Bad Request) if no query options match the value of the options parameter.


Usage Notes:

Query options named in the options request parameter must be pre-installed using the /config/query service. If no options parameter is given, this method lists available <values> and <tuples> from the configured default options. If there are no default options, the global Search API options are used. Use the /config/query/{name} service to create named query options.

The expected response type can be specified using either the format parameter or Accept header. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence.

For more information on defining queryable lexicons and indexes, see 'Identifying Lexicon and Range Index Values in Query Options' in the REST Application Developer's Guide.


Example:
Given the following query options are installed under the name "ex-values":

<options xmlns="http://marklogic.com/appservices/search">
  <values name="speaker">
    <range type="xs:string">
      <element ns="" name="SPEAKER"/>
    </range>
  </values>
  <tuples name="speaker-title">
    <range type="xs:string">
      <element ns="" name="SPEAKER"/>
    </range>
    <range type="xs:string">
      <path-index>/PLAY/ACT/SCENE/TITLE</path-index>
    </range>
  </tuples>
</options>

$ curl --anyauth --user user:password -X GET \
    -H "Accept: application/xml" \
    http://localhost:8004/v1/values?options=ex-values

==> An XML report of the lexicon queries available through /v1/values/{name}:

<rapi:values-list xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:values>
    <rapi:name>speaker</rapi:name>
    <rapi:uri>/v1/values/speaker?options=values</rapi:uri>
  </rapi:values>
  <rapi:values>
    <rapi:name>speaker-title</rapi:name>
    <rapi:uri>/v1/values/speaker-title?options=values</rapi:uri>
  </rapi:values>
</rapi:values-list>
  
Example:
Given the following query options installed under the name "ex-values":

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": {
            "ns": "",
            "name": "SPEAKER"
          }
        }
      }
    ],
    "tuples": [
      {
        "name": "speaker-title",
        "range": [
          {
            "type": "xs:string",
            "element": {
              "ns": "",
              "name": "SPEAKER"
            }
          },
          {
            "type": "xs:string",
            "path-index": {
              "text": "/PLAY/ACT/SCENE/TITLE"
            }
          }
        ]
      }
    ]
  }
}

$ curl --anyauth --user user:password -X GET \
    -H "Accept: application/json" \
    http://localhost:8004/v1/values?options=ex-values

==> A JSON report of the lexicon queries available through /v1/values/{name}:
{
  "values-list": {
    "values": [
      {
        "name": "speaker",
        "uri": "/v1/values/speaker?options=values"
      },
      {
        "name": "speaker-title",
        "uri": "/v1/values/speaker-title?options=values"
      }
    ]
  }
}
  

GET /v1/values/{name}
Summary:

Query the values in a lexicon or range index, or find co-occurrences of values in multiple range indexes. Optionally apply an aggregate function to the values or co-occurrences.

Parameters:
q? : A string query. For details, see 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide and cts:query.
structuredQuery? : A structured search query string. That is, a serialized representation of a search:query element. See 'Searching Using Structured Queries' in the Search Developer's Guide.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
view? : The view of the query results to return in the response. Accepted values: values, aggregate, all. Default: all.
format? : The type of the search 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.
collection* : Filter results to include only matches in the named collection(s).
directory? : Filter results to include only matches from documents in the specified database directory.
direction? : The sort order of returned results. Accepted values: ascending or descending. The default direction depends on the sort order defined in the options. The default is ascending for item-order and descending for frequency-order.
frequency? : The method of calculating frequency. Accepted values: item (default) or fragment. Fragment frequency returns the number of fragments with an included value. Item frequency returns the total number occurrences of an included value.
limit? : The maximum number of values or tuples to retrieve from the lexicon. Default: No limit.
start? : The index of the first result to return from the subset defined by limit. Results are numbered beginning with 1. Default: 1.
pageLength? : The number of values to return within the subset of values defined by limit, beginning with the value selected by start. Default: Return all selected values.
aggregate? : The name of a built-in or user-defined aggregate function to run against the lexicon. If the function is not a built-in aggregate, you must also supply aggregatePath. The supported builtin aggregate functions are: sum, avg, min, max, median, count, stddev, stddev-population, correlation, covariance, covariance-population, variance, variance-population.
aggregatePath? : The path to the native plugin library containing the implementation of the function named by the aggregate function. If the path is empty or is not specified, a built-in aggregate is assumed.
transform? : Names a search result transformation previously installed via the /transforms service. The transformation is applied to the <search:response/> after applying user-defined transforms defined in the query options using <transform-results>. For details, see 'Transforming the Search Response' in the REST Application Developer's Guide.
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1. Transform parameters are passed to the transform named in the transform parameter.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.

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.

Required Privilege:

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

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


Response:

On success, MarkLogic Server responds with a 200 status and the query results in the response body.

If you use an aggregate function and the target lexicon type does not support the chosen operation, such as stddev on a string valued lexicon, or if the aggregate function does not exist, MarkLogic Server responds with a 400 (Bad Request) status, with additional error information in the response body.


Usage Notes:

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 configure query options, use the /config/query service.

When you apply a builtin or user defined aggregate function, the output is dependent on the function. For details, see 'Analyzing Lexicons and Range Indexes With Aggregate Functions' in the REST Application Developer's Guide.

For more details, see 'Querying Lexicons and Range Indexes' in the REST Application Developer's Guide.


Example:
Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ curl --anyauth --user user:password -X GET \
    http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, as XML.

<values-response name="speaker" type="xs:string" \
    xmlns="http://marklogic.com/appservices/search" \
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <distinct-value frequency="1">[GOWER]</distinct-value>
  <distinct-value frequency="1">[PROSPERO]</distinct-value>
  ...
</values-response>
  
Example:
Assume the following query options are installed with the name "index-options":

{
  "options": {
    "values": [
      {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": { "ns": "", "name": "SPEAKER" }
        }
      }
    ]
  }
}

$ curl --anyauth --user user:password -X GET \
    http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, as JSON.
{
  "values-response": {
    "name": "speaker",
    "type": "xs:string",
    "distinct-value": [
      {
        "frequency": 1,
        "_value": "[GOWER]"
      },
      {
        "frequency": 1,
        "_value": "[PROSPERO]"
      },
      ...
    ],
    "metrics": {
      "values-resolution-time": "PT0.016665S",
      "aggregate-resolution-time": "PT0.00001S",
      "total-time": "PT0.018102S"
    }
  }
}
  
Example:
Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ curl --anyauth --user user:password -X GET \
    'http://localhost:8003/v1/values/speaker?options=index-options&limit=10&start=4&pageLength=3'

==> The 4th through the 6th distinct values of the SPEAKER element in 
    element range index, as XML.

<values-response name="speaker" type="xs:string" \
    xmlns="http://marklogic.com/appservices/search" \
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <distinct-value frequency="1">A Lord</distinct-value>
  <distinct-value frequency="2">A Patrician</distinct-value>
  <distinct-value frequency="1">A Player</distinct-value>
  <metrics>
    <values-resolution-time>PT0.000258S</values-resolution-time>
    <total-time>PT0.002038S</total-time>
  </metrics>
</values-response>
  

POST /v1/values/{name}
Summary:

Query the values in a lexicon or range index, or find co-occurrences of values in multiple range indexes. Optionally apply an aggregate function to the values or co-occurrences. Query and query options are passed in the POST body.

Parameters:
q? : A string query. For details, see 'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide and cts:query. This query is AND'd with the query(s) in the request body.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
view? : The view of the query results to return in the response. Accepted values: values, aggregate, all. Default: all.
format? : The content type of the request body and the response. This is equivalent to setting Accept and Content-type headers. The format parameter overrides the Accept and Content-type headers. Accepted values: json or xml.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions service to create and manage multi-statement transactions.
direction? : The sort order of returned results. Accepted values: ascending or descending. The default direction depends on the sort order defined in the options. The default is ascending for item-order and descending for frequency-order.
directory? : Filter results to include only matches from documents in the specified database directory.
frequency? : The method of calculating frequency. Accepted values: item (default) or fragment. Fragment frequency returns the number of fragments with an included value. Item frequency returns the total number occurrences of an included value.
limit? : The maximum number of values or tuples to retrieve from the lexicon. Default: No limit.
start? : The index of the first result to return from the subset defined by limit. Results are numbered beginning with 1. Default: 1.
pageLength? : The number of values to return within the subset of values defined by limit, beginning with the value selected by start. Default: Return all selected values.
aggregate? : The name of a built-in or user-defined aggregate function to run against the lexicon. If the function is not a built-in aggregate, you must also supply aggregatePath. The supported builtin aggregate functions are: sum, avg, min, max, median, count, stddev, stddev-population, correlation, covariance, covariance-population, variance, variance-population.
aggregatePath? : The path to the native plugin library containing the implementation of the function named by the aggregate function. If the path is empty or is not specified, a built-in aggregate is assumed.
transform? : Names a search result transformation previously installed via the /transforms service. The transformation is applied to the <search:response/> after applying user-defined transforms defined in the query options using <transform-results>. For details, see 'Transforming the Search Response' in the REST Application Developer's Guide.
trans:{name}* : A transform parameter name and value. For example, trans:myparam=1. Transform parameters are passed to the transform named in the transform parameter.

Request Headers:
Accept*: The expected MIME type of the data in the response. Accepted types: application/json or application/xml. Setting the format parameter overrides this header.
Content-Type: The MIME type of the data in the POST body. Accepted values: application/json or application/XML. Setting the format parameter overrides this header.

Response Headers:
Content-type: The MIME type of the data in the response. The results will be in either XML or JSON, depending upon the value of the format parameter or the Accept header.

Required Privilege:

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

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


Response:

On success, MarkLogic Server responds with a 200 status and the query results in the response body.

If you use an aggregate function and the target lexicon type does not support the chosen operation, such as stddev on a string valued lexicon, or if the aggregate function does not exist, MarkLogic Server responds with a 400 (Bad Request) status, with additional error information in the response body.


Usage Notes:

Use a query in the q request parameter and/or the request body to limit the returned values to those occurring in fragments that match the query. For details, see 'Using a Query to Constrain Results' in the REST Application Developer's Guide.

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

The format parameter always overrides the Content-type and Accept headers. If you want the request and response bodies to use different content types, you must use the headers instead of the format parameter. If you do not use the format parameter or an Accept header, an XML response is returned.

Supply query options with the options request parameter or 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 the body contains a structured query, use the options request parameter to specify custom query options. If the body contains a combined query, use the options request parameter and/or the options component of the combined query.

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 on using a combined query, see POST /v1/search.

When you apply a builtin or user defined aggregate function, the output is dependent on the function. For details, see 'Analyzing Lexicons and Range Indexes With Aggregate Functions' in the REST Application Developer's Guide.

For more details, see 'Querying Lexicons and Range Indexes' in the REST Application Developer's Guide.


Example:
Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ cat query.xml
<query xmlns="http://marklogic.com/appservices/search">
  <near-query>
    <term-query>
      <text>Yorick</text>
    </term-query>
    <term-query>
      <text>Horatio</text>
    </term-query>
  </near-query>
</query>

$ curl --anyauth --user user:password -X POST -d@./query.xml \
    -H "Content-type: application/xml" -i \
    http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as a
    structured query in the POST body. The results are returned as XML.

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

<values-response name="speaker" type="xs:string" 
    xmlns="http://marklogic.com/appservices/search" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  ...
  <distinct-value frequency="1">HAMLET</distinct-value>
  <distinct-value frequency="1">HORATIO</distinct-value>
  <distinct-value frequency="1">KING CLAUDIUS</distinct-value>
  ...
  <metrics>
    <values-resolution-time>PT0.001943S</values-resolution-time>
    <total-time>PT0.003052S</total-time>
  </metrics>
</values-response>
  
Example:
Assume the following query options are installed with the name "index-options":

{ "options": {
    "values": [ {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": { "ns": "", "name": "SPEAKER" }
        }
    } ]
} }

$ cat query.json
{ "query" : {
    "near-query" : {
      "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
    }
} }

$ curl --anyauth --user user:password -X POST -d@./query.json -i \
    -H "Content-type: application/json" -H "Accept: application/json" \
    http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as a
    JSON structured query in the POST body. The results are returned as JSON.

{
  "values-response": {
    "name": "speaker",
    "type": "xs:string",
    "distinct-value": [
      ...
      {
        "frequency": 1,
        "_value": "HAMLET"
      },
      {
        "frequency": 1,
        "_value": "HORATIO"
      },
      {
        "frequency": 1,
        "_value": "KING CLAUDIUS"
      },
      ...
    ],
    "metrics": {
      "values-resolution-time": "PT0.002033S",
      "total-time": "PT0.004128S"
    }
  }
}
  
Example:
Assume the following query options are installed with the name "index-options":

<options xmlns="http://marklogic.com/appservices/search">
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
</options>

$ cat query.xml
<search xmlns="http://marklogic.com/appservices/search">
  <query>
    <near-query>
      <term-query>
        <text>Yorick</text>
      </term-query>
      <term-query>
        <text>Horatio</text>
      </term-query>
    </near-query>
  </query>
  <options>
    <return-metrics>false</return-metrics>
  </options>
</search>

$ curl --anyauth --user user:password -X POST -d@./query.xml \
    -H "Content-type: application/xml" -i \
    'http://localhost:8003/v1/values/speaker?options=index-options

==> The distinct values of the SPEAKER element in element range index, for
    fragments that match the query "Yorick NEAR Horatio", expressed as an
    XML combined query in the POST body. Dynamic options in the combined
    query disable including metrics in the results. The results are returned 
    as XML.

<values-response name="speaker" type="xs:string" 
    xmlns="http://marklogic.com/appservices/search" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  ...
  <distinct-value frequency="1">HAMLET</distinct-value>
  <distinct-value frequency="1">HORATIO</distinct-value>
  <distinct-value frequency="1">KING CLAUDIUS</distinct-value>
  <distinct-value frequency="1">LAERTES</distinct-value>
  <distinct-value frequency="1">QUEEN GERTRUDE</distinct-value>
  <distinct-value frequency="1">Second Clown</distinct-value>
</values-response>

The following is the same combined query, expressed as JSON:

{
  "search" : {
    "query" : {
      "near-query" : {
        "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
      }
    },
    "options" : {
      "return-metrics" : false
    }
  }
}
  
Example:
$ cat combined-query.xml
<search xmlns="http://marklogic.com/appservices/search">
  <options xmlns="http://marklogic.com/appservices/search">
    <constraint name="title">
      <word>
        <element ns="" name="TITLE" />
      </word>
    </constraint>
    <values name="speaker">
        <range type="xs:string">
            <element ns="" name="SPEAKER"/>
        </range>
    </values>
    <return-metrics>false</return-metrics>
  </options>
  <query xmlns="http://marklogic.com/appservices/search">
    <word-constraint-query>
      <constraint-name>title</constraint-name>
      <text>hamlet</text>
    </word-constraint-query>
  </query>
</search>

$ curl --anyauth --user user:password -X POST -d@./combined-query.xml \
    'http://localhost:8003/v1/values/speaker?limit=10&start=4&pageLength=3'

==> The 4th through the 6th values from the set of 10 distinct values
    retrieved from the SPEAKER lexicon, as XML. The results retrieved
    from the lexicon are constrained to those in documents with the word
    "hamlet" in the title.

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

<values-response name="speaker" type="xs:string" 
    xmlns="http://marklogic.com/appservices/search" 
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <distinct-value frequency="1">CORNELIUS</distinct-value>
  <distinct-value frequency="1">Danes</distinct-value>
  <distinct-value frequency="1">First Ambassador</distinct-value>
</values-response>

The following is the equivalent POST body as JSON:

{ "search": {
    "query": {
      "word-constraint-query": {
        "constraint-name": "title",
        "text": "hamlet"
    } },
    "options": {
      "values": {
        "name": "speaker",
        "range": {
          "type": "xs:string",
          "element": { "name": "SPEAKER", "ns": ""}
        }
      },
      "constraint": {
        "name": "title",
        "word": {
          "element": { "name": "TITLE", "ns": "" }
        }
      },
      "return-metrics": false
    }
} }