MarkLogic Server 11.0 Product Documentation
GET /v1/search

Summary

Search the database using a string query, structured query, or cts:query. You can request search results and/or matching documents in the response.

URL Parameters
q? A string query expressed in the Search API grammar. For details, see Automatic Query Text Parsing and Grammar in the Search Developer's Guide and cts:query.
structuredQuery? A structured query or cts:query as a string. That is, a serialized representation of a search:query element or a cts:query. For more details, see Searching Using Structured Queries in the Search Developer's Guide and Composing cts:query Expressions 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.
view? The view of the search results to return in the response. Accepted values: facets, results, metadata, all. Default: all for a normal search, none for a multi-document read.
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.
format? For a normal search operation, you can use format as an Accept header override; it affects the content type of the response search results. For a multi-document read, you can use format to specify the content type of returned metadata and the search results (if requested) in the response; format has no effect on returned document content. Accepted values: json or xml. Default: xml. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide.
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. 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.
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.
timestamp? A timestamp returned in the ML-Effective-Timestamp header of a previous request. Use this parameter to iteratively fetch search results based on 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.
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.
Response Headers
Content-Type The MIME type of the data in the response. For a normal search operation, the results are either XML or JSON, depending upon the value of the format parameter or the Accept header. For a multi-document read, the result is a multipart/mixed response body containing matching content or metadata; see the Usage Notes.
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.
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 a search:reponse node. If JSON output is requested, the response body contains a JSON map with keys that closely correspond to the search:response 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 facets in the response, then the return status is 200 (OK) whether there are matching documents or not.

For a multi-document read, the response body is multipart/mixed data containing content and/or metadata for each document that matches the input query. If you use a view parameter to include search results in the response, the search response, facets, or metadata are 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

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

When performing a multi-document read, use the category parameter to specify whether to return content, metadata, and/or a metadata subset for matching documents. By default, only content is returned. Use the view parameter to include search results and facets in the response. You can also use the view parameter to control results in a normal search operation.

Query options named in the options request parameter must be pre-installed using the /config/query service. If no query options are specified, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options. To pre-configure query options, use the /config/query service. Use a POST request to specify dynamic query options instead of (or in addition to) pre-installing persistent query 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

$ curl --anyauth --user username:password -X GET \
    'http://localhost:8000/v1/search?q=infinite NEAR variety'

==> Search the database for documents where "infinite" appears near
    "variety". MarkLogicServer returns an XML search response similar
    to the following:

<search:response total="1" start="1" page-length="10"
   xmlns="" xmlns:search="http://marklogic.com/appservices/search">
  <search:result index="1" uri="/shakespeare/plays/a_and_c.xml"
     path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)"
     score="46720" confidence="0.434464" fitness="0.50812">
    <search:snippet>
      <search:match path="fn:doc(&quot;/shakespeare/plays/a_and_c.xml&quot;)
        /PLAY/ACT[2]/SCENE[2]/SPEECH[86]/LINE[3]">Her 
        <search:highlight>infinite</search:highlight> 
        <search:highlight>variety</search:highlight>: other women cloy
      </search:match>
    </search:snippet>
  </search:result>
  <search:qtext>infinite NEAR variety</search:qtext>
  <search:metrics>
    <search:query-resolution-time>PT1.11403S</search:query-resolution-time>
    <search:snippet-resolution-time>PT0.907914S</search:snippet-resolution-time>
    <search:total-time>PT2.022321S</search:total-time>
  </search:metrics>
</search:response>

Example

$ curl --anyauth --user username:password -X GET \
  -H "Accept: application/json" \
  'http://localhost:8000/v1/search?q=infinite NEAR variety'

==> Search the database for documents where "infinite" appears near
    "variety". MarkLogicServer returns a JSON search response similar
    to the following:

{
  "snippet-format": "snippet",
  "total": 1,
  "start": 1,
  "page-length": 10,
  "results": [
    {
      "index": 1,
      "uri": "/shakespeare/plays/a_and_c.xml",
      "path": "fn:doc(\"/shakespeare/plays/a_and_c.xml\")",
      "score": 17792,
      "confidence": 0.364254,
      "fitness": 0.480312,
      "matches": [
        {
          "path": "fn:doc(\"/shakespeare/plays/a_and_c.xml\")/PLAY/ACT[2]
          /SCENE[2]/SPEECH[86]/LINE[3]",
          "match-text": [
            "Her ",
            { "highlight": "infinite" },
            " ",
            { "highlight": "variety" },
            ": other women cloy"
          ]
        }
      ]
    }
  ],
  "qtext": "infinite NEAR variety",
  "metrics": {
    "query-resolution-time": "PT0.014055S",
    "facet-resolution-time": "PT0.000082S",
    "snippet-resolution-time": "PT0.064129S",
    "total-time": "PT0.078551S"
  }
}

Example

curl --anyauth --user user:password -X GET -i \
  -H "Accept: multipart/mixed; boundary=BOUNDARY" \
  http://localhost:8000/v1/search?q=myphrase

==> Retrieve all documents that match the query "myphrase". MarkLogic
    Server responds similar to the following:

HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=BOUNDARY
vnd.marklogic.start: 1
vnd.marklogic.pageLength: 10
vnd.marklogic.result-estimate: 3
Server: MarkLogic
Content-Length: 589
Connection: Keep-Alive
Keep-Alive: timeout=5

--BOUNDARY
Content-Type: text/xml
Content-Disposition: attachment; filename=doc1.xml; category=content; 
                     format=xml
Content-Length: 60

<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY
Content-Type: text/xml
Content-Disposition: attachment; filename=doc3.xml; category=content; format=xml
Content-Length: 60

<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc2.json; category=content; 
                     format=json
Content-Length: 19

{"key":"some json"}
--BOUNDARY--

Example

curl --anyauth --user user:password -X GET -i \
  -H "Accept: multipart/mixed; boundary=BOUNDARY" \
  'http://localhost:8000/v1/search?q=myphrase&view=results&category=properties&format=json'

==> Retrieve the search results (view=results) and the properties metadata 
    (category=properties) for all documents matching the query "myphrase".
    The search results are returned in the first part of the multipart
    response. The search results and metadata are returned as JSON because
    of the format=json parameter. MarkLogic responds with output similar
    to the following:

HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=BOUNDARY
vnd.marklogic.start: 1
vnd.marklogic.pageLength: 10
vnd.marklogic.result-estimate: 3
Server: MarkLogic
Content-Length: 1788
Connection: Keep-Alive
Keep-Alive: timeout=5

--BOUNDARY
Content-Type: application/json
Content-Disposition: inline
Content-Length: 1074

{
  "snippet-format": "snippet",
  "total": 3,
  "start": 1,
  "page-length": 10,
  "results": [
    {
      "index": 1,
      "uri": "doc1.xml",
      "path": "fn:doc(\"doc1.xml\")",
      "score": 14336,
      "confidence": 0.3498099,
      "fitness": 0.7490314,
      "href": "/v1/documents?uri=doc1.xml",
      "mimetype": "text/xml",
      "format": "xml",
      "matches": [
        {
          "path": "fn:doc(\"doc1.xml\")/root",
          "match-text": [
            {
              "highlight": "some"
            },
            " xml"
          ]
        }
      ]
    },
    ...
  ],
  "qtext": "some",
  "metrics": {
    "query-resolution-time": "PT0.008052S",
    "snippet-resolution-time": "PT0.003433S",
    "total-time": "PT0.012944S"
  }
}
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc1.xml; category=properties; 
                     format=json
Content-Length: 46

{"properties":{"my-prop":"value1"}}
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc3.xml; category=properties; 
                     format=json
Content-Length: 46

{"properties":{"my-prop":"value2"}}
--BOUNDARY
Content-Type: application/json
Content-Disposition: attachment; filename=doc2.json; category=properties; 
                     format=json
Content-Length: 46

{"properties":{"my-prop":"value3"}}
--BOUNDARY--

Example

curl --anyauth --user admin:admin -X GET 'http://localhost:8000/v1/search?structuredQuery=<query+xmlns%3d%22http%3a//marklogic.com/appservices/search%22><near-query><term-query><text>Yorick</text></term-query><term-query><text>Horatio</text></term-query></near-query></query>'

==> Retrieve the search results of a structured query that looks for
    "Yorick" near "Horatio." MarkLogic responds with output similar
    to the following:

Content-Type: text/html; charset=utf-8
Server: MarkLogic
Content-Length: 209
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 326
Connection: Keep-Alive
Keep-Alive: timeout=5

<search:response snippet-format="snippet" total="0" start="1"
  page-length="10" xmlns:search="http://marklogic.com/appservices/search">
  <search:metrics>
    <search:query-resolution-time>PT0.0011872S</search:query-resolution-time>
    <search:total-time>PT0.001423S</search:total-time>
  </search:metrics>
</search:response>
Powered by MarkLogic Server | Terms of Use | Privacy Policy