MarkLogic 9 Product Documentation
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.

URL 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, metadata-values, 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.
database? Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
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? You can use this parameter in conjunction with or instead of the request Content-type and Accept headers to indicate the input and/or output content type. The Content-type header takes precedence over format in most cases. format takes precedence over the Accept header in most cases. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide. 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. If you specify this parameter multiple times, the collections are OR related.
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).
timestamp? A timestamp returned in the ML-Effective-Timestamp header of a previous request. Use this parameter to iteratively fetch search results based the contents of the database at a fixed point-in-time. For more details, see Performing Point-in-Time Operations 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.
forest-name* The name of forest(s) to which results should be limited. The forest(s) must exist in the database for this request. If you wish to retrieve results from multiple specific forests, specify this parameter once per forest.
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. If the Accept header and format parameter are both present, then format takes precedence if the Accept header is not set to multipart/mixed. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide.
Content-Type* The MIME type of the data in the POST body. Accepted values: application/json, application/xml, or multipart/mixed. When you use multipart/mixed, the first part must contain an XML or JSON QBE and the second part must contain a XML or JSON query options; see Usage Notes for details. The format parameter value is used if Content-type is not set or is set to an incompatible or unknown value.
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.
ML-Effective-Timestamp The system timestamp at which this operation was performed. You can use the value in the timestamp parameter of a subsequent request. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide.

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.

Required Privileges

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

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

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 can 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 always contains at least an XML or JSON QBE, and can also contain query options. For QBE syntax, see Searching Using Query By Example in the Search Developer's Guide. The request body can take one of the following forms:

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.

When MarkLogic Server processes a Query By Example, it constructs an equivalent structured query and query options. These query options are drawn from three sources: Options required to realize the QBE, options in the request body, and default options. The options from these sources are merged together, with the options required to realize the QBE taking precedence over options in the request body, and options in the request body taking precedence over the default options in the event of a conflict.

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

When you use the collection and directory parameters to limit the scope of a search, the effect of these parameters on the search is not reflected in the query returned when you use the return-query query option. If you need to see these constraints reflected in the returned query, use a structured query that includes a collection-query or directory-query instead.

The metadata-values category represents "metadata fields" document metadata. For more details, see Metadata Fields in the Administrator's Guide.

See Also

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 user:password -i -X POST -d @./qbe.xml \
    -H "Content-type: application/xml" -H "Accept: application/xml" \
    http://localhost:8000/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:8000/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:8000/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--
Powered by MarkLogic Server | Terms of Use | Privacy Policy