This page was generated
June  25,  2015
8:20  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Client API - Search Functions

REST Resource Summary
GET /v1/keyvalue Query the database based on the value of a JSON key, XML element, or XML element attribute.
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.
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/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 rang indexes.
POST /v1/values/{name} Query the values in a lexicon or range index, or find co-occurrences of values in multiple rang 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 endpoint.
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 endpoint 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.

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.

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 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 \
  'http://localhost:8003/v1/keyvalue?element=TITLE&value=Cymbeline&format=json'

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

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.

Parameters:
q? : A Search API search query string. 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:structured-query element. See 'Using Structured Search as an Alternate to cts:query' 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 endpoint.
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.
txid? : The transaction identifier of the multi-statement transaction in which to service this request. Use the /transactions endpoint 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.

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 respond to the search:response elements.

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.

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


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

==> An XML search:response for all text where "infinite" appears
    near "variety". For example:

<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 \
  'http://localhost:8003/v1/search?q=infinite NEAR variety&format=json'

==> A JSON search:response for all text where "infinite" appears
    near "variety". For example:

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

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.

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).
format? : The content type of the request body and the response body. 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.
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 data in the response. Accepted values: 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:

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:

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

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 'Automatic Query Text Parsing and Grammar' 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" 
    using a structured query, 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="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: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/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:

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 "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 \
    'http://localhost:8004/v1/values?options=ex-values&format=xml'

==> An XML report of the lexicon queries available through /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 \
    'http://localhost:8004/v1/values?options=ex-values&format=json'

==> A JSON report of the lexicon queries available through /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 rang indexes. Optionally apply an aggregate function to the values or co-occurrences.

Parameters:
q? : A Search API search query string. 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:structured-query element. See 'Using Structured Search as an Alternate to cts:query' 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 endpoint.
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.
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.
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.
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.

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

POST /v1/values/{name}
Summary:

Query the values in a lexicon or range index, or find co-occurrences of values in multiple rang 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 expected content type of the data in the response. Setting format is equivalent to setting the Accept and Content-type headers. The format parameter overrides the Accept and Content-type headers. Accepted values: json or xml.
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.
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.
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.
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.

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 POST body. Accepted values: 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:

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

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 \
    -H "Content-type: application/json" -i \
    'http://localhost:8003/v1/values/speaker?options=index-options&format=json'

==> 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
    }
  }
}