MarkLogic 12 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.

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

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:

• An XML QBE. Set the Content-type header to application/xml.
• A JSON QBE. Set the Content-type header to application/json.
• A multipart part body, with an XML or JSON QBE in the first part and XML or JSON query options in the second part. The two parts need not use the same MIME type. Set the request Content-type header to multipart/mixed and set the Content-type header for each part to either application/xml or application/json.

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

• Using Query By Example to Prototype a Query in the REST Application Developer's Guide.
• Searching Using Query By Example in the Search Developer's Guide.

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