-
Notifications
You must be signed in to change notification settings - Fork 9
Key Value Query Service
The key/value query service is a convenient way to find documents via a simple key/value lookup.
-
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
- A 200 response with the body being a set of search results
For details on the output format, see the search result format page.
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.
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
Should probably point at the search result format page as authoritative.