Skip to content
This repository has been archived by the owner on Nov 9, 2022. It is now read-only.

Key Value Query Service

Jump to bottom
isubiker edited this page Nov 18, 2011 · 18 revisions

Key/Value Query Service

The key/value query service is a convenient way to find documents via a simple key/value lookup.

Endpoint Details

  • Endpoint: /kvquery - For querying XML and JSON documents

  • Request type: GET or POST

    • Note: If using POST, the POST body should consist of URL encoded form values. POST variables are supported because structured queries can become quite large and may be more convenient to submit as a POST request.

  • Parameters:

    • key - The JSON key to examine (only useful for querying JSON documents)
    • element - A XML element to examine (can be either an XML element in a XML document or XML that's embedded in a JSON document)
    • attribute - Used in combination with the element paramater to examine an XML attribute
    • value - The value of the key, element or attribute that was specified
    • start (optional, default: 1) - The first result to fetch for pagination, eg: 1
    • length (optional, default: 1) - The number of results to return
    • include - Can specify what you'd like returned in the search results. Multiple include paramaters can be set and accepted values are:
      • content - The original document for the result
      • collections - The collections that the document is in
      • properties - The properties on the document
      • permissions - The permissions on the document
      • quality - The quality set for the document
      • snippet - A search result snippet
      • highlighting - The content will be highlighted with <span class="hit"> elements based on the query
      • confidence - Include the confidence of the search result (a value from 0 to 1.0)
      • all - returns all of the above options
      • none - just returns the metadata section without any actual results
    • extractPath - Either a JSON path or a simplified XPath (depending on the content type) that can be used to limit what part(s) of the document are returned
    • applyTransform - Applies a transform to the content. If an extractPath is also specified, the transform is handed the content specified by the extractPath.
    • collection - Limit the results to a specific collection. If multiple collection paramaters are specified, only documents which are in all of the collections will be returned.
    • underDirectory - Limit the results to documents that are descendants of the specified directory
    • inDirectory - Limit the results to documents that are immediate children of the specified directory
    • outputFormat (optional, default: json) - What format the results should be delivered as. Valid formats are xml or json, default is json.
    • txid (optional) - A pre-existing transaction ID in which the search should be performed. See creating transactions for more info. Note: If running in a clustered environment, search requests must be issued to the same host that created the ticket.

  • Returns

For details on the output format, see the search result format page.

Key/Value Queries with JSON Documents

For example, fetching a document by its ID is a good use case for this endpoint:

/kvquery?key=id&value=123456&contentType=json

This response from this request will look similar to:

{
    "meta":{
        "start":1,
        "end":1,
        "total":1
    },
    "results":[
        {
            "uri":"/users/123456.json",
            "content":{
                "id":"123456"
                "active": true,
                "name": "Noam Chomsky"
             }
         }
     ]
}

By default, if your query matches multiple documents only one of the documents is returned.

Key/Value Queries with XML Documents

The key/value query service for XML documents works just like it does with JSON documents but with some XML flare. With XML documents, the key portion maps to either an element name or an element/attribute pair. For example, let's use the same id example above:

/kvquery?element=id&value=123456&contentType=xml

That request will return the first document that has an <id> element with the value of 123456:

<response xmlns="http://marklogic.com/corona">
    <meta>
        <start>1</start>
        <end>10</end>
        <total>25</total>
    </meta>
    <results>
        <result>
            <uri>/users/123456.xml</uri>
            <content>
                <author>
                    <id>123456</id>
                    <active>true</active>
                    <name>Noam Chomsky</name>
                </author>
            </content>
        </result>
    </results>
</response>

Now let's say our XML documents were formated with the id as an attribute on the author element instead of being an element all on it's own, like this:

<author id="123456">
    <active>true</active>
    <name>Noam Chomsky</name>
</author>

To fetch this document using the key/value query service, we'd issue a request like this:

/kvquery?element=author&attribute=id&value=123456&contentType=xml

Note: To query based off of an attribute, the element that the attribute is attached to must be specified.

If the XML contains a namespace, be sure to declare a prefix for the namespace using the XML namespace management tools first. Then use that prefix in the key:

/kvquery?element=myns:author&attribute=id&value=123456&contentType=xml

Discussion

Should probably point at the search result format page as authoritative.

Clone this wiki locally