MarkLogic Server 11.0 Product DocumentationGET /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, seeSearching Using Query By Example in theSearch 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, andquality. Usemetadata to request all categories exceptcontent. 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, seeSecurity Requirements in theREST Application Developer's Guide. |
| view? | The view of the results to return. Accepted values:results orstructured. 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). Usestructured 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. Theformat parameter takes precedence over the Accept header in most cases; for details, seeControlling Input and Output Content Type in theREST Application Developer's Guide. Accepted values:json orxml. |
| 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, seeTransforming the Search Response in theREST 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 theML-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, seePerforming Point-in-Time Operations in theREST 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 thetransform 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 usemultipart/mixed, the request is a multi-document read rather than just a search; see the Usage Notes. If the Accept header andformat parameter are both present, thenformat takes precedence if the Accept header is not set tomultipart/mixed. For details, seeControlling Input and Output Content Type in theREST 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 theformat parameter (or the Accept header for a normal search operation). For a multi-document read, the result ismultipart/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 thetimestamp parameter of a subsequent request. For more details, seePerforming Point-in-Time Operations in theREST 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 thestart andpageLength parameters to incrementally retrieve results. |
| vnd.marklogic.pageLength | For a multi-document read operation, the number of results in the response. See thepageLength 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 tototal in thesearch: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 asearch:reponse node or asearch:query, depending on the setting of theview request parameter. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to thesearch:response orsearch: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 theview 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 ismultipart/mixed data containing content and/or metadata for each document matching the input query. If you use aview parameter to include search results in the response, the search response is in the first part. For details, seeReading Multiple Documents Matching a Query in theREST Application Developer's Guide.
Required Privileges
This operation requires therest-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, seeSearching Using Query By Example in theSearch Developer's Guide. Set thequery 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 theview=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 theview parameter. A multi-document read is distinguished from a normal search operation by setting the Accept header tomultipart/mixed; for details, seeReading Multiple Documents Matching a Query in theREST Application Developer's Guide
You can combine validation with search by including both theview=validate andview=results request parameters in your search. No otherview values may be used together.
Query options named in theoptions request parameter must be pre-installed using the/config/query service. If no query options are specified in theoptions 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 theoptions parameter or the default options).
When you use thecollection anddirectory 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 thereturn-query query option. If you need to see these constraints reflected in the returned query, use a structured query that includes acollection-query ordirectory-query instead.
Themetadata-values category represents "metadata fields" document metadata. For more details, seeMetadata Fields in theAdministrator's Guide.
See Also
- Using Query By Example to Prototype a Query in theREST Application Developer's Guide
- Searching Using Query By Example in theSearch Developer's Guide
Example
Assume you URL-encode the following query. This query searches for XMLdocuments containing an <author/> element containing the value "Mark Twain"and an <edition/> element whose <code>format</code> parameter has thevalue "paperback".The following QBE matches XML documents containing an <author/> element withthe value "Mark Twain" and an <edition/> element with a <format/> attributewith 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/xmlServer: MarkLogicContent-Length: 211Connection: Keep-AliveKeep-Alive: timeout=5HTTP/1.1 200 OKContent-type: application/xml; charset=utf-8Server: MarkLogicContent-Length: 967Connection: Keep-AliveKeep-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("/books/sawyer.xml")" 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("/books/sawyer.xml")/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 withthe 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/xmlServer: MarkLogicContent-Length: 211Connection: Keep-AliveKeep-Alive: timeout=5HTTP/1.1 200 OKServer: MarkLogicContent-Type: text/plain; charset=UTF-8Content-Length: 706Connection: Keep-AliveKeep-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 thecontents 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 OKContent-type: multipart/mixed; boundary=BOUNDARYvnd.marklogic.start: 1vnd.marklogic.pageLength: 10vnd.marklogic.result-estimate: 1Server: MarkLogicContent-Length: 185Connection: Keep-AliveKeep-Alive: timeout=5--BOUNDARYContent-Type: application/jsonContent-Disposition: attachment; filename=doc2.json; category=content; format=jsonContent-Length: 19{"key":"some json"}--BOUNDARY--
Stack Overflow: Get the most useful answers to questions from the MarkLogic community, orask your own question.