Loading TOC...

GET /v1/keyvalue

Summary

THIS METHOD IS DEPRECATED; use /v1/search and /v1/qbe instead. Query the database based on the value of a JSON key, XML element, or XML element attribute.

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

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.

Required Privileges

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

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

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

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.