MarkLogic Server 11.0 Product Documentation
POST /v1/search

Summary

Search the database using a string query, structured query, a cts:query, or a combined query in the POST body. Returns search results, matching content and/or metadata, or both.

URL Parameters
q? A string query conforming to the Search API grammar. For details, see Automatic Query Text Parsing and Grammar in the Search Developer's Guide This query is AND'd with the query(s) in the request body.
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.
view? The view of the search results to return in the response. Accepted values: facets, results, metadata, all (default) 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? 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. The format parameter always takes precedence over the Accept header. 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 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.
Content-Type* The MIME type of the data in the POST body. Accepted values: application/json or application/xml. 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. 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 and/or metadata; see the Usage Notes.
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 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.

For details, see Reading Multiple Documents Matching a Query in the REST Application Developer's Guide and Querying Documents and Metadata in the REST Application Developer's Guide.

The request body must contain either a structured query (a serialized representation of a search:query), a serialized cts:query, or a combined query (a serialized representation of a search:search), expressed as either XML or JSON. For details, see Searching Using Structured Queries in the Search Developer's Guide and Specifying Dynamic Query Options with Combined Query in the REST Application Developer's Guide.

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.

For a normal search operation, you should usually use the Accept and Content-type headers to control the input and output content type. The format parameter is available as a fallback and as a means to indicate search result and metadata content type on a multi-document read.

Supply query options with the options request parameter or in the request body. If no query options are specified in either the request parameter or the request body, MarkLogic Server uses the configured default options. If no default options are configured, MarkLogic Server uses the default Search API options.

If the body contains a structured or cts query, use the options request parameter to specify custom query options. If the body contains a combined query, use the options request parameter and/or the options component of the combined query.

If query options are supplied in both the options request parameter and the request body, the options are merged together. In cases of conflict, an option definition in the combined query overrides the one in the persistent options. Constraints defined in both option sources are preserved; in the event of a constraint name collision, the constraint defined in the request body takes precedence.

Query options named in the options request parameter must be pre-installed using the /config/query service.

A combined query encapsulates options and query in a single object. A combined query is most often used to specify options plus one or more queries at query time, but you can also specify only options or only one or more queries. The query portion can be a string query; a structured, cts, or QBE query; or both a string query and a structured, cts, or QBE query. For syntax, semantics, and examples, see Specifying Dynamic Query Options with Combined Query in the REST Application Developer's Guide.

The query options within a combined query use the same option syntax as standalone, persistent query options; for details, see Appendix: Query Options Reference in the Search Developer's Guide. Similarly, the sub-queries in a combined query use the syntax of a standalone structured, cts, QBE, or string query.

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

# Search using an XML structured query in the request body

$ cat > s-query.txt
<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:near-query>
    <search:term-query>
      <search:text>infinite</search:text>
    </search:term-query>
    <search:term-query>
      <search:text>variety</search:text>
    </search:term-query>
    <search:distance>3</search:distance>
  </search:near-query>
</search:query>
^D

$ curl --anyauth --user user:password -X POST -d@'./s-query.txt' -i \
  -H "Content-type:application/xml"  -H "Accept: application/xml" \
  http://localhost:8000/v1/search

==> Perform a query for "infinite" occurring within 3 terms of 
    "variety", and receive the search:response XML results in 
    the response body. The response has the following form:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 875
Connection: close

<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="43648" confidence="0.418356" fitness="0.50947">
    <search:snippet>
      <search:match path="...">
        Her <search:highlight>infinite</search:highlight>
        <search:highlight>variety</search:highlight>: other women cloy
      </search:match>
    </search:snippet>
  </search:result>
  <search:metrics>
    <search:query-resolution-time>
      PT1.087968S
    </search:query-resolution-time>
    <search:snippet-resolution-time>
      PT1.028637S
    </search:snippet-resolution-time>
    <search:total-time>PT2.117041S</search:total-time>
  </search:metrics>
</search:response>

Example

# Search using a JSON structured query in the request body

$ cat > s-query.json
{"query": {
  "near-query": {
    "queries": [
      {"term-query": { "text" : "infinite"}},
      {"term-query": { "text" : "variety" }}
    ],
    "distance": 3
  }
}}
^D

$ curl --anyauth --user user:password -X POST -d@'./s-query.json' -i \
  -H "Content-type:application/json"  -H "Accept: application/json" \
  http://localhost:8000/v1/search

==> Perform a query for "infinite" occurring within 3 terms of 
    "variety", and receive the JSON results in the response body. The 
    response has the following form:

Content-Type: application/json; charset=utf-8
Content-Length: 104
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
ML-Effective-Timestamp: 14964190204445650
Server: MarkLogic
Content-Length: 696
Connection: Keep-Alive
Keep-Alive: timeout=5

{ "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": 47744,
      "confidence": 0.43916,
      "fitness": 0.513595,
      "href": "/v1/documents?uri=%2Fshakespeare%2Fplays%2Fa_and_c.xml&database=bill",
      "mimetype": "application\/xml",
      "format": "xml",
      "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"
          ]
      } ]
  } ],
  "metrics": {
    "query-resolution-time": "PT0.001632S",
    "snippet-resolution-time": "PT0.448131S",
    "total-time": "PT0.450721S"
  }
}

Example

# Search using a cts:query in the request body

$ cat > cts-query.txt
<cts:near-query distance="3" xmlns:cts="http://marklogic.com/cts">
  <cts:word-query>
    <cts:text xml:lang="en">infinite</cts:text>
  </cts:word-query>
  <cts:word-query>
    <cts:text xml:lang="en">variety</cts:text>
  </cts:word-query>
</cts:near-query>
^D

$ curl --anyauth --user user:password -X POST -d@'./cts-query.txt' -i \
  -H "Content-type:application/xml"  http://localhost:8000/v1/search

==> Perform a query for "infinite" occurring within 3 terms of 
    "variety", and receive the search:response XML results in 
    the response body. The response has the following form:

Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close

HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 875
Connection: close

<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="43648" confidence="0.418356" fitness="0.50947">
    <search:snippet>
      <search:match path="...">
        Her <search:highlight>infinite</search:highlight>
        <search:highlight>variety</search:highlight>: other women cloy
      </search:match>
    </search:snippet>
  </search:result>
  <search:metrics>
    <search:query-resolution-time>
      PT1.087968S
    </search:query-resolution-time>
    <search:snippet-resolution-time>
      PT1.028637S
    </search:snippet-resolution-time>
    <search:total-time>PT2.117041S</search:total-time>
  </search:metrics>
</search:response>

# The following is the equivalent JSON cts:query serialization:
{"ctsquery":{
  "nearQuery":{
    "queries":[
      {"wordQuery":{"text":["infinite"], "options":["lang=en"]}},
      {"wordQuery":{"text":["variety"], "options":["lang=en"]}}
    ],
    "distance":3
  }}
}

Example

# Search using a combined query in the request body

$ cat ./combined-query.xml
<search xmlns="http://marklogic.com/appservices/search">
  <qtext>alas</qtext>
  <query>
    <near-query>
      <term-query>
        <text>Yorick</text>
      </term-query>
      <term-query>
        <text>Horatio</text>
      </term-query>
    </near-query>
  </query>
  <options>
    <return-results>false</return-results>
    <return-metrics>false</return-metrics>
  </options>
</search>
$ curl --anyauth --user user:password -X POST -d@./combined-query.xml \
    -i -H "content-type: application/xml" http://localhost:8000/v1/search

==> Perform a query for "Yorick" near "Horatio", using a combined query.
    Dynamic options in the POST body disable returning results and metrics.
    The response has the following form:

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 189
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"/>

The following is the equivalent combined query request body as JSON:
{
  "search": {
    "qtext" : "alas",
    "query" : {
      "near-query" : {
        "term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
      }
    },
    "options" : {
      "return-results" : false,
      "return-metrics" : false
    }
  }
}
Powered by MarkLogic Server | Terms of Use | Privacy Policy