MarkLogic Server 11.0 Product Documentation
GET /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.

URL Parameters
query? A serialized Query By Example. For details, see Searching Using Query By Example in the Search Developer's Guide.
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.
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 results to return. Accepted values: results or structured. Default: For a normal search operation, results (returns the search results); for a multi-document read, none (return matching document content or metadata, but no search results). Use structured to return the combined query representation of your QBE, instead of search results or documents.
format? You can use this parameter in conjunction with or instead of the Accept header to indicate the output content type. The format parameter 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 to include only matches in the named collection. If you specify this parameter multiple times, the collections are OR related.
directory? Filter search results to include only 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 parameter values are passed to the transform named in the transform request 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.
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.
vnd.marklogic.start For a multi-document read operation, the starting index of the results in the response. The header value is always 1 unless you use the start and pageLength parameters to incrementally retrieve results.
vnd.marklogic.pageLength For a multi-document read operation, the number of results in the response. See the pageLength parameter.
vnd.marklogic.result-estimate For a multi-document read operation, an estimate of the total number of matches to the input query. This is equivalent to total in the search:response.

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 is an encapsulation of a query expressed as an annotated example of the target document(s). For details, see Searching Using Query By Example in the Search Developer's Guide. Set the query request parameter to a serialized Query By Example, expressed as either XML or JSON.

Query By Example 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 this representation 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

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.

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

When MarkLogic Server evaluates a QBE, it constructs an equivalent structured query and query options. These query options are generated by merging the options required to realize the QBE with the general options in effect for the request (options specified through the options parameter or the default 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

Assume you URL-encode the following query. This query searches for XML
documents containing an <author/> element containing the value "Mark Twain"
and an <edition/> element whose <code>format</code> parameter has the
value "paperback".
The following QBE matches XML documents containing an <author/> element with
the value "Mark Twain" and an <edition/> element with a <format/> attribute
with the value "paperback". URL-encode the query to use it in a GET request.

<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 searches using the URL-encoded query:

$ curl --anyauth --user user:password -i -X GET \
    -H "Content-type: application/xml" -H "Accept: application/xml" \
    'http://localhost:8000/v1/qbe?query=%3Cq%3Aqbe%20xmlns%3Aq%3D%22http%3A%2F%2Fmarklogic.com%2Fappservices%2Fquerybyexample%22%3E%3Cq%3Aquery%3E%3Cauthor%3EMark%20Twain%3C%2Fauthor%3E%3Cedition%20format%3D%22paperback%22%2F%3E%3C%2Fq%3Aquery%3E%3C%2Fq%3Aqbe%3E'

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". URL-encode the query to use it 
in a GET request.

{ "$query": {
    "author": "Mark Twain",
    "edition": { "format": "paperback" }
} }

The following command searches using the URL-encoded query:

$ curl --anyauth --user user:password -i -X GET \
    -H "Content-type: application/json" -H "Accept: application/json" \
    'http://localhost:8000/v1/qbe?query=%7B%22%24query%22%3A%7B%22author%22%3A%22Mark%20Twain%22%2C%22edition%22%3A%7B%22format%22%3A%22paperback%22%7D%7D%7D'

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 uses the URL-encoded query above to retrieve the
contents of all documents matching the query:

$ curl --anyauth --user user:password -i -X GET \
    -H "Content-type: application/json" \
    -H "Accept: multipart/mixed; boundary=BOUNDARY" \
    'http://localhost:8000/v1/qbe?query=%7B%20%22%24query%22%3A%20%7B%20%22%24word%22%3A%20%22myphrase%22%20%7D%20%7D'

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