|
|
|
 |
Summary:
Query the database based on the value of a JSON key, XML element, or
XML element attribute.
|
Parameters:
key?
:
The name of a key in JSON content. The search is constrained to
JSON key-value pairs with the specified key and a value matching
the string passed in the value parameter.
For searching XML content, use element and, optionally,
attribute instead of key. Use of
key precludes the use of the element
or attribute parameters.
|
element?
:
The name of an XML element. The search is constrained to
XML elements with a name matching the supplied string. For JSON
content, use the key parameter instead. Use of
element precludes use of the key parameter.
|
attribute?
:
Identifies the name of an XML attribute on the element named by the
element parameter. This parameter constrains the search
to attributes with the specified name found on elements matching the
supplied element. If you use this parameter, you
must also set the element parameter and may not use
the key parameter.
|
value
:
The value of the key, element, or element attribute to match.
|
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.
|
format?
:
The type of the search results. This is equivalent to specifying
the format in the Accept header. The format parameter
overrides the Accept header if both are present. Accepted value:
xml and json. Default: 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(s).
|
directory?
:
Filter search results so they only include matches from documents in
the specified database directory.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. Accepted values:
application/json or application/XML.
Default: XML.
|
|
Response Headers:
Content-Type:
The MIME type of the data in the response. The results will be in
either XML or JSON, depending upon the value of the format
parameter or the Accept header.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
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.
|
Usage Notes:
Use the key and value parameters to query
JSON documents inserted into the database using the /documents
service. Use the element and attribute
parameters with value to search XML documents.
The expected response type can be specified using either the
format parameter or Accept header. One or
the other must be supplied. If both are supplied and are different,
the format parameter takes precedence.
Query options must be pre-installed using the
/config/query service. If no query options are specified
with the options parameter, the global default options are
used.
For more details, see
'Querying Documents and Metadata' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET -i \
'http://localhost:8003/v1/keyvalue?element=TITLE&value=Cymbeline'
==> A search:result for all documents occurrences of a TITLE element
with a value of "Cymbeline". MarkLogic Server returns the following:
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: 858
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/cymbelin.xml"
path="fn:doc("/shakespeare/plays/cymbelin.xml")"
score="17920" confidence="0.336069" fitness="0.336069">
<search:snippet>
<search:match
path="fn:doc("/shakespeare/plays/cymbelin.xml")/PLAY">
<search:highlight>Cymbeline</search:highlight>
</search:match>
</search:snippet>
</search:result>
<search:metrics>
<search:query-resolution-time>PT0.015515S</search:query-resolution-time>
<search:facet-resolution-time>PT0.000118S</search:facet-resolution-time>
<search:snippet-resolution-time>PT0.027884S</search:snippet-resolution-time>
<search:total-time>PT0.044953S</search:total-time>
</search:metrics>
</search:response>
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/json" \
http://localhost:8003/v1/keyvalue?element=TITLE&value=Cymbeline
==> A search:result for all documents occurrences of a TITLE element
with a value of "Cymbeline". MarkLogic Server returns the following
(whitespace added for clarity):
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
Content-type: application/json
Server: MarkLogic
Content-Length: 500
Connection: close
{
"snippet-format": "snippet",
"total": 1,
"start": 1,
"page-length": 10,
"results": [
{
"index": 1,
"uri": "/shakespeare/plays/cymbelin.xml",
"path": "fn:doc(\"/shakespeare/plays/cymbelin.xml\")",
"score": 15360,
"confidence": 0.338445,
"fitness": 0.338445,
"matches": [
{
"path": "fn:doc(\"/shakespeare/plays/cymbelin.xml\")/PLAY",
"match-text": [
"\n",
{
"highlight": "Cymbeline"
},
"\n"
]
}
]
}
],
"metrics": {
"query-resolution-time": "PT0.009748S",
"facet-resolution-time": "PT0.000087S",
"snippet-resolution-time": "PT0.022979S",
"total-time": "PT0.033092S"
}
}
|
|
|
|
|
 |
Summary:
Search the database using a Query By Example or perform a multi-document
read for documents that match a Query By Example.
|
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, 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.
|
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?
:
The expected content type of the search results and document metadta
if any are included in the response. For a normal search operation,
setting format is equivalent to specifying
the format in the Accept header and overrides the Accept header if
both are present. For a multi-document read, use this parameter to
control the format of returned metadata and
the search response (if requested); format has
no effect on returned document contents. Accepted value:
xml and json. Default: 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(s).
|
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).
|
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.
|
|
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. 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.
|
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.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
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.
|
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).
For more details, see
'Using Query By Example to Prototype a Query' in the REST Application Developer's Guide.
|
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 admin:adm1n -i -X GET \
-H "Content-type: application/xml" -H "Accept: application/xml" \
'http://localhost:8003/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("/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 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:8003/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:8003/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--
|
|
|
|
|
 |
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.
|
Parameters:
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.
|
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, 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.
|
view*
:
The view of the search results to return. Accepted values:
result, validate, or structured.
Default: For a normal search operation, result, which
returns the search results; for a multi-document read, none
(return matching document content and/or metadata, but no search results).
Use structured to return the combined query representation
of your QBE, instead of search results or content. Use
validate alone to validate your query without performing
a search. Combine validate and result to
validate your query and proceed with the search only if the query is
valid. For details, see the Usage Notes.
|
format?
:
The MIME type of the search results and returned metadata. For a normal
search operation, this is equivalent to specifying the format in the
Accept header, and it overrides the Accept header if both are present.
For a multi-document read, use this parameter to control the format
of returned metadata and the search response (if requested);
format has no effect on returned document content.
Accepted values: json or xml. Default:
xml. If this parameter is present, the data in the POST
body must also use this format.
|
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(s).
|
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).
|
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.
|
|
Request Headers:
Accept:
The expected MIME type of the response. Accepted values:
application/json or application/XML.
Default: XML.
|
Content-Type:
The MIME type of the data in the POST body. Accepted values:
application/json or application/XML.
|
|
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.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
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.
|
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 may 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 must contain a QBE, expressed in either XML or
JSON. Set the Content-Type header appropriately. For query syntax, see
'Searching Using Query By Example' in the Search 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. If you use view=validate alone, no
search is performed, and the request returns validation results.
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 processes a Query By Example, 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).
For more details, see
'Using Query By Example to Prototype a Query' in the REST Application 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 admin:adm1n -i -X POST -d @./qbe.xml \
-H "Content-type: application/xml" -H "Accept: application/xml" \
http://localhost:8003/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("/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 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:8003/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:8003/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--
|
|
|
|
|
 |
Summary:
Remove documents in a collection or directory, or clear the database.
|
Parameters:
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?
:
Remove documents in the named collection.
|
directory?
:
Remove documents in the named directory.
|
|
Required Privilege:
Deleting a directory or collection requires the rest-writer
role, or the following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
Clearing the database requires the rest-admin role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-admin
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server returns a status 204.
|
Usage Notes:
A request with no parameters removes all documents in all non-replica
forests attached to the content database. The rest-admin
role is required for this operation. If the requesting user does not
have the required role, a 400 status is returned.
All other requests must supply either one directory or one collection.
All matching documents in the directory or collection are deleted.
A request to remove selected documents, rather than a full database
clear, requires the rest-writer role, and must include
at least one collection or directory parameter.
|
Example:
|
|
|
|
|
 |
Summary:
Search the database using a string and/or structured query, returning
search results and/or matching documents.
|
Parameters:
q?
:
A string query. For details, see
'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide
and cts:query.
|
structuredQuery?
:
A structured search query string. That is, a serialized representation
of a search:query element. See
'Searching Using Structured Queries' 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, 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.
|
format?
:
The content type of the request body, the response search results,
and any metadata returned by a multi-document read.
For a normal search operation, setting format is
equivalent to setting the Accept and Content-type headers. The
format parameter overrides the Accept and Content-type
headers for a normal search operation. For a multi-document read,
use this parameter to control the format of returned metadata and
the search response (if requested); format has no
effect on returned content. Accepted values: json
or xml (default). 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(s).
|
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.
|
|
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.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
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.
|
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.
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.
|
Example:
$ curl --anyauth --user username:password -X GET \
'http://localhost:8003/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("/shakespeare/plays/a_and_c.xml")"
score="46720" confidence="0.434464" fitness="0.50812">
<search:snippet>
<search:match path="fn:doc("/shakespeare/plays/a_and_c.xml")
/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:8003/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:8003/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:8003/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--
|
|
|
|
|
 |
Summary:
Search the database using a structured query, supplied in the POST body;
or search the database using a string or structured query with the
query options and query combined in the POST body. Returns search
results, matching content and/or metadata, or both.
|
Parameters:
q?
:
A string query. For details, see
'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide
and cts:query. 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, uris, 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, 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.
|
format?
:
The content type of the request body, the response search results,
and any metadata returned by a multi-document read.
For a normal search operation, setting format is
equivalent to setting the Accept and Content-type headers. The
format parameter overrides the Accept and Content-type
headers for a normal search operation. For a multi-document read,
use this parameter to control the format of returned metadata and
the search response (if requested); format has no
effect on returned content. Accepted values: json
or xml. Default: 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(s).
|
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).
|
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.
|
|
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.
|
Content-Type*:
The MIME type of the data in the POST body. Accepted values:
application/json or application/XML.
Setting the format parameter value overrides this header.
|
|
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.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
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.
|
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) 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, the format parameter always
overrides the Content-type and Accept headers. If you want the request
and response bodies to use different content types, you must use the
headers instead of the format parameter. If you do not use
the format parameter or an Accept header, the response data
is XML.
For a multi-document read, the format parameter overrides
the request Content-type header and determines the format of the
search response, if one is included, and any returned document metadata.
With a multi-document read, you cannot specify different formats for
the request body and response database because the Accept header must
be multipart/mixed.
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 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 can contain just options, just a structured query,
just a string query, or any combination of the three.
Use the following template to construct a combined query in XML:
<search:search xmlns:search="http://marklogic.com/appservices/search">
<!-- Include a structured query and/or a string query -->
<search:query>
<!-- structured query using same syntax as standalone search:query -->
</search:query>
<search:qtext>your string query</search:qtext>
<search:options>
<!-- options using same syntax as standalone search:options -->
</search:options>
</search:search>
Use the following template to construct a combined query in JSON:
{"search": {
"query": { same syntax as a standalone structured query },
"qtext": { "your string query here" },
"options": { same syntax as standalone query options }
}}
The query options within a combined query use the same option syntax
as standalone, persistent query options; for details, see
'Appendix A: JSON Query Options Reference' in the REST Application Developer's Guide
or
'Appendix B: XML Query Options Reference' in the REST Application Developer's Guide.
Similarly, the sub-queries in a combined query use the syntax of a
standalone structured or string query. For details, see
'Searching Using Structured Queries' in the Search Developer's Guide
or
'Searching Using String Queries' in the Search Developer's Guide.
For more details, see
'Querying Documents and Metadata' in the REST Application Developer's Guide.
|
Example:
$ cat > s-query.txt
<search:query xmlns:search="http://marklogic.com/appservices/search">
<search:near-query>
<search:term>
<search:text>infinite</search:text>
</search:term>
<search:term>
<search:text>variety</search:text>
</search:term>
<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" http://localhost:8003/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("/shakespeare/plays/a_and_c.xml")"
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:
$ 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-options \
-i -H "content-type: application/xml" http://localhost:8003/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
}
}
}
|
|
|
|
|
 |
Summary:
Retrieve a list of suggested constraint prefixes and/or constraint
values that match (complete) the input query text, similar to the
XQuery function search:suggest.
|
Parameters:
partial-q?
:
The partial search term for which suggestions should be retrieved.
Default: The empty string ("").
|
q*
:
A string query that constrains the returned suggestions. If this
parameter appears multiple times, the constraining queries are
AND'd together.
|
limit?
:
The maximum number of suggestions to return. Default: 10.
|
cursor-position?
:
The position of the cursor within the partial-q query
text. That is, in making suggestions, the last position in the
input string that should be considered for completion. Default: The
length of the input string, so that the whole input query text string
is considered.
|
options?
:
The name of query options previously created via a PUT or POST
request to the /v1/config/query service.
|
format?
:
The expected content type of the results. This is equivalent to specifying
the format in the Accept header. The format parameter
overrides the Accept header if both are present. Accepted value:
xml and json. Default: xml.
|
|
Request Headers:
Accept*:
The expected MIME type of the information in the response.
Accepted types: application/json or
application/xml. Ignored if the request includes a
format parameter value.
|
|
Response Headers:
Content-type:
The MIME type of the data in the response, either
application/json or application/xml,
depending upon the MIME type requested through the format
parameter or Accept header on the request.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
On success, MarkLogic Server responds with a 200 status and a list of
suggested completions in the response body. Results are returned as
either XML or JSON, depending up on the format request
parameter or the Accept header setting. See the examples below for
details on the response data.
|
Usage Notes:
You can use this service to generate a list of search term completions
as a user enters text into a search box. Specify the input string in
the partial-q parameter. If the user is typing into the
middle of a previously entered search string, use the
cursor-position request parameter to identify the end of
the text to be matched in the input partial query.
Use the q request parameter to specify zero or more
string queries with which to constrain the returned suggestions. These
constraints act as filters on the returned suggestions. Use the string
query grammar to express these constraints; for details, see
'Searching Using String Queries' in the Search Developer's Guide.
Suggestions are generated from suggestion sources defined through
query options. You can use named constraints, collections, value (range)
lexicons, or word lexicons as suggestion sources. However, word lexicons
are not recommended; collection and value lexicons usually yield the best
performance. For details, See the default-suggestion-source
and suggestion-source query options.
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 specify options on the fly,
use POST /v1/suggest.
For more details, see
'Generating Search Term Completion Suggestions' in the REST Application Developer's Guide.
|
Example:
Assume the following query options are installed with the name "opt-suggest":
<options xmlns="http://marklogic.com/appservices/search">
<default-suggestion-source>
<range type="xs:string" facet="true">
<element ns="" name="name"/>
</range>
</default-suggestion-source>
</options>
Then the following command generates search suggestions for the query
text "doc", using the above options:
$ curl --anyauth --user user:password -X GET \
-H "Accept: application/xml" -i \
'http://localhost:8003/v1/suggest?partial-q=doc&options=opt-suggest'
==> The values in the element <name/> that begin with the text "doc", as XML.
MarkLogic Server returns a response similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 256
Connection: Keep-Alive
Keep-Alive: timeout=5
<search:suggestions xmlns:search="http://marklogic.com/appservices/search">
<search:suggestion>document-insert</search:suggestion>
<search:suggestion>document-load</search:suggestion>
<search:suggestion>document-query</search:suggestion>
</search:suggestions>
|
Example:
Assume the following query options are installed with the name "opt-suggest":
<options xmlns="http://marklogic.com/appservices/search">
<default-suggestion-source>
<range type="xs:string" facet="true">
<element ns="" name="name"/>
</range>
</default-suggestion-source>
</options>
$ curl --anyauth --user user:password -X GET \
-H "Accept: application/json" -i \
'http://localhost:8003/v1/suggest?partial-q=doc&options=opt-suggest'
==> The values in the element <name/> that begin with the text "doc", as JSON.
MarkLogic Server returns a response similar to the following:
HTTP/1.1 200 OK
Content-type: application/json
Server: MarkLogic
Content-Length: 68
Connection: Keep-Alive
Keep-Alive: timeout=5
{"suggestions":[ "document-insert", "document-load", "document-query" ] }
|
|
|
|
|
 |
Summary:
Retrieve a list of suggested constraint prefixes and/or constraint
values that match (complete) the input query text, similar to the
XQuery function search:suggest.
|
Parameters:
partial-q?
:
The partial search term for which suggestions should be retrieved.
Default: The empty string ("").
|
q*
:
A string query that constrains the returned suggestions. All
occurrences of this query are AND'd together with any queries in
the POST body.
|
limit?
:
The maximum number of suggestions to return. Default: 10.
|
cursor-position?
:
The position of the cursor within the partial-q query
text. That is, in making suggestions, the last position in the
input string that should be considered for completion. Default: The
length of the input string, so that the whole input query text string
is considered.
|
options?
:
The name of query options previously created via a PUT or POST
request to the /v1/config/query service. See the
Usage Notes for details on how these options are combined with
options in the POST body.
|
format?
:
The content type of the request body and the response. This is
equivalent to setting Accept and Content-type headers. The
format parameter overrides the Accept and Content-type
headers. Allowed values: json, xml.
|
|
Request Headers:
Accept*:
The expected MIME type of the information in the response.
Accepted types: application/json or
application/xml. Ignored if the request includes a
format parameter value.
|
Content-type:
The MIME type of the data in the request. Allowed values:
application/json or application/xml.
Ignored if the request includes a format parameter.
|
|
Response Headers:
Content-type:
The MIME type of the data in the response, either
application/json or application/xml,
depending upon the MIME type requested through the format
parameter or Accept header on the request.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
On success, MarkLogic Server responds with a 200 status and a list of
suggested completions in the response body. Results are returned as
either XML or JSON, depending up on the format request
parameter or the Accept header setting. See the examples below for
details on the response data.
|
Usage Notes:
You can use this service to generate a list of search term completions
as a user enters text into a search box. Specify the input string in
the partial-q parameter. If the user is typing into the
middle of a previously entered search string, use the
cursor-position request parameter to identify the end of
the text to be matched in the input partial query.
The request body must contain a combined query (a serialized representation
of a search:search), expressed as either XML or JSON.
For details, see
POST /v1/search and
'Specifying Dynamic Query Options with Combined Query' in the REST Application Developer's Guide.
Use the combined query in the request body and/or the q
request parameter to specify zero or more queries with which to
constrain the returned suggestions. These constraints act as filters on
the returned suggestions. Use the string query grammar to construct the
value of the q parameter; for details, see
'Searching Using String Queries' in the Search Developer's Guide.
If a request includes both q parameters and a combined
query, they are combined to constrain the results.
Suggestions are generated from suggestion sources defined through
query options. You can use named constraints, collections, value (range)
lexicons, or word lexicons as suggestion sources. However, word lexicons
are not recommended; collection and value lexicons usually yield the best
performance. For details, See the default-suggestion-source
and suggestion-source query options.
Supply query options with the options request parameter
or in the combined query 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 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. For details, see
'Configuring Query Options' in the REST Application Developer's Guide.
The format parameter always overrides the Content-type
and Accept headers. You must use the headers intead of the
format parameter to specify different MIME types for
the request body and the response. If you not use the format
parameter or an Accept header, the response data is XML.
For more details, see
'Generating Search Term Completion Suggestions' in the REST Application Developer's Guide
and the XQuery function search:suggest.
|
Example:
$ cat combined-query.xml
<search xmlns="http://marklogic.com/appservices/search" >
<qtext>document</qtext>
<query>
<container-query>
<element ns="" name="category"/>
<term-query><text>xdmp</text></term-query>
</container-query>
</query>
<options xmlns="http://marklogic.com/appservices/search">
<default-suggestion-source>
<range type="xs:string" facet="true">
<element ns="" name="name"/>
</range>
</default-suggestion-source>
</options>
</search>
$ curl --anyauth --user user:password -X POST -d @./combined-query.xml \
-H "Content-type: application/xml" -H "Accept: application/xml" -i \
'http://localhost:8003/v1/suggest?partial-q=doc&options=opt-suggest'
==> The values in the element <name/> that begin with the text "doc",
occurring in documents containing the query text "document" and
a <category/> element containing the term "xdmp". MarkLogic Server
returns a response similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 256
Connection: Keep-Alive
Keep-Alive: timeout=5
<search:suggestions xmlns:search="http://marklogic.com/appservices/search">
<search:suggestion>document-insert</search:suggestion>
<search:suggestion>document-load</search:suggestion>
</search:suggestions>
|
Example:
$ cat combined-query.json
{ "search": {
"qtext": [ "document" ],
"query": {
"container-query": {
"element": {
"ns": "",
"name": "category"
},
"term-query": {
"text": [ "xdmp" ]
}
}
},
"options": {
"default-suggestion-source": {
"range": {
"type": "xs:string",
"facet": true,
"element": {
"ns": "",
"name": "name"
}
}
}
}
} }
$ curl --anyauth --user user:password -X POST -d @./combined-query.json \
-H "Content-type: application/json" -H "Accept: application/json" -i \
'http://localhost:8003/v1/suggest?partial-q=doc&options=opt-suggest'
==> The values in the element <name/> that begin with the text "doc",
occurring in documents containing the query text "document" and
a <category/> element containing the term "xdmp". MarkLogic Server
returns a response similar to the following:
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 51
Connection: Keep-Alive
Keep-Alive: timeout=5
{"suggestions":["document-insert","document-load"]}
|
|
|
|
|
 |
Summary:
Retrieve a list of lexicon configurations available for use with
GET /v1/values/{name}.
|
Parameters:
format?
:
Specifies the MIME type of the response content, as an alternative to
specifying format via the Accept header. Accepted values:
json and xml (default). If there is no
format parameter, the format must be specified in the Accept header.
|
options?
:
The query options for which to list available lexicon configurations.
|
|
Request Headers:
Accept*:
The expected MIME type of the information in the response.
Accepted types: application/json or
application/xml. Ignored if the request includes a
format parameter value.
|
|
Response Headers:
Content-type:
The MIME type of the data in the response, either
application/json or application/xml,
depending upon the MIME type requested through the format
parameter or Accept header on the request.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server returns a 200 status, with an XML or JSON
listing of available named lexicon configurations in the response body.
MarkLogic Server returns a 400 (Bad Request) if no query options
match the value of the options parameter.
|
Usage Notes:
Query options named in the options request parameter must
be pre-installed using the /config/query service.
If no options parameter is given, this method lists
available <values> and <tuples>
from the configured default options. If there are no default options,
the global Search API options are used. Use the
/config/query/{name} service to create named query options.
The expected response type can be specified using either the
format parameter or Accept header. One or
the other must be supplied. If both are supplied and are different,
the format parameter takes precedence.
For more information on defining queryable lexicons and indexes, see
'Identifying Lexicon and Range Index Values in Query Options' in the REST Application Developer's Guide.
|
Example:
Given the following query options are installed under the name "ex-values":
<options xmlns="http://marklogic.com/appservices/search">
<values name="speaker">
<range type="xs:string">
<element ns="" name="SPEAKER"/>
</range>
</values>
<tuples name="speaker-title">
<range type="xs:string">
<element ns="" name="SPEAKER"/>
</range>
<range type="xs:string">
<path-index>/PLAY/ACT/SCENE/TITLE</path-index>
</range>
</tuples>
</options>
$ curl --anyauth --user user:password -X GET \
-H "Accept: application/xml" \
http://localhost:8004/v1/values?options=ex-values
==> An XML report of the lexicon queries available through /v1/values/{name}:
<rapi:values-list xmlns:rapi="http://marklogic.com/rest-api">
<rapi:values>
<rapi:name>speaker</rapi:name>
<rapi:uri>/v1/values/speaker?options=values</rapi:uri>
</rapi:values>
<rapi:values>
<rapi:name>speaker-title</rapi:name>
<rapi:uri>/v1/values/speaker-title?options=values</rapi:uri>
</rapi:values>
</rapi:values-list>
|
Example:
Given the following query options installed under the name "ex-values":
{
"options": {
"values": [
{
"name": "speaker",
"range": {
"type": "xs:string",
"element": {
"ns": "",
"name": "SPEAKER"
}
}
}
],
"tuples": [
{
"name": "speaker-title",
"range": [
{
"type": "xs:string",
"element": {
"ns": "",
"name": "SPEAKER"
}
},
{
"type": "xs:string",
"path-index": {
"text": "/PLAY/ACT/SCENE/TITLE"
}
}
]
}
]
}
}
$ curl --anyauth --user user:password -X GET \
-H "Accept: application/json" \
http://localhost:8004/v1/values?options=ex-values
==> A JSON report of the lexicon queries available through /v1/values/{name}:
{
"values-list": {
"values": [
{
"name": "speaker",
"uri": "/v1/values/speaker?options=values"
},
{
"name": "speaker-title",
"uri": "/v1/values/speaker-title?options=values"
}
]
}
}
|
|
|
|
|
 |
Summary:
Query the values in a lexicon or range index, or find co-occurrences
of values in multiple range indexes. Optionally apply an aggregate function
to the values or co-occurrences.
|
Parameters:
q?
:
A string query. For details, see
'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide
and cts:query.
|
structuredQuery?
:
A structured search query string. That is, a serialized representation
of a search:query element. See
'Searching Using Structured Queries' in the Search Developer's Guide.
|
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 query results to return in the response. Accepted
values: values, aggregate, all. Default: all.
|
format?
:
The type of the search results. This is equivalent to specifying
the format in the Accept header. The format parameter
overrides the Accept header if both are present. Accepted value:
xml and json. Default: xml.
|
collection*
:
Filter results to include only matches in the named collection(s).
|
directory?
:
Filter results to include only matches from documents in the
specified database directory.
|
direction?
:
The sort order of returned results. Accepted values:
ascending or descending. The default direction
depends on the sort order defined in the options. The
default is ascending for item-order and
descending for frequency-order.
|
frequency?
:
The method of calculating frequency. Accepted values: item
(default) or fragment. Fragment frequency returns the
number of fragments with an included value. Item frequency returns
the total number occurrences of an included value.
|
limit?
:
The maximum number of values or tuples to retrieve from the lexicon.
Default: No limit.
|
start?
:
The index of the first result to return from the subset defined
by limit. Results are numbered beginning with 1. Default: 1.
|
pageLength?
:
The number of values to return within the subset of values
defined by limit, beginning with the value selected
by start. Default: Return all selected values.
|
aggregate?
:
The name of a built-in or user-defined aggregate function to run
against the lexicon. If the function is not a built-in aggregate,
you must also supply aggregatePath. The supported
builtin aggregate functions are: sum, avg,
min, max, median,
count, stddev, stddev-population,
correlation, covariance,
covariance-population, variance,
variance-population.
|
aggregatePath?
:
The path to the native plugin library containing the implementation of
the function named by the aggregate function. If the
path is empty or is not specified, a built-in aggregate is assumed.
|
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.
|
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.
|
|
Request Headers:
Accept*:
The expected MIME type of the information in the response.
Accepted types: application/json or
application/xml. Ignored if the request includes a
format parameter value.
|
|
Response Headers:
Content-type:
The MIME type of the data in the response, either
application/json or application/xml,
depending upon the MIME type requested through the format
parameter or Accept header on the request.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
On success, MarkLogic Server responds with a 200 status and the query
results in the response body.
If you use an aggregate function and the target lexicon type does not
support the chosen operation, such as stddev on a string
valued lexicon, or if the aggregate function does not exist,
MarkLogic Server responds with a 400 (Bad Request) status, with
additional error information in the response body.
|
Usage Notes:
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 configure query options,
use the /config/query service.
When you apply a builtin or user defined aggregate function, the
output is dependent on the function. For details, see
'Analyzing Lexicons and Range Indexes With Aggregate Functions' in the REST Application Developer's Guide.
For more details, see
'Querying Lexicons and Range Indexes' in the REST Application Developer's Guide.
|
Example:
Assume the following query options are installed with the name "index-options":
<options xmlns="http://marklogic.com/appservices/search">
<values name="speaker">
<range type="xs:string">
<element ns="" name="SPEAKER"/>
</range>
</values>
</options>
$ curl --anyauth --user user:password -X GET \
http://localhost:8003/v1/values/speaker?options=index-options
==> The distinct values of the SPEAKER element in element range index, as XML.
<values-response name="speaker" type="xs:string" \
xmlns="http://marklogic.com/appservices/search" \
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<distinct-value frequency="1">[GOWER]</distinct-value>
<distinct-value frequency="1">[PROSPERO]</distinct-value>
...
</values-response>
|
Example:
Assume the following query options are installed with the name "index-options":
{
"options": {
"values": [
{
"name": "speaker",
"range": {
"type": "xs:string",
"element": { "ns": "", "name": "SPEAKER" }
}
}
]
}
}
$ curl --anyauth --user user:password -X GET \
http://localhost:8003/v1/values/speaker?options=index-options
==> The distinct values of the SPEAKER element in element range index, as JSON.
{
"values-response": {
"name": "speaker",
"type": "xs:string",
"distinct-value": [
{
"frequency": 1,
"_value": "[GOWER]"
},
{
"frequency": 1,
"_value": "[PROSPERO]"
},
...
],
"metrics": {
"values-resolution-time": "PT0.016665S",
"aggregate-resolution-time": "PT0.00001S",
"total-time": "PT0.018102S"
}
}
}
|
Example:
Assume the following query options are installed with the name "index-options":
<options xmlns="http://marklogic.com/appservices/search">
<values name="speaker">
<range type="xs:string">
<element ns="" name="SPEAKER"/>
</range>
</values>
</options>
$ curl --anyauth --user user:password -X GET \
'http://localhost:8003/v1/values/speaker?options=index-options&limit=10&start=4&pageLength=3'
==> The 4th through the 6th distinct values of the SPEAKER element in
element range index, as XML.
<values-response name="speaker" type="xs:string" \
xmlns="http://marklogic.com/appservices/search" \
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<distinct-value frequency="1">A Lord</distinct-value>
<distinct-value frequency="2">A Patrician</distinct-value>
<distinct-value frequency="1">A Player</distinct-value>
<metrics>
<values-resolution-time>PT0.000258S</values-resolution-time>
<total-time>PT0.002038S</total-time>
</metrics>
</values-response>
|
|
|
|
|
 |
Summary:
Query the values in a lexicon or range index, or find co-occurrences
of values in multiple range indexes. Optionally apply an aggregate function
to the values or co-occurrences. Query and query options are passed in
the POST body.
|
Parameters:
q?
:
A string query. For details, see
'Automatic Query Text Parsing and Grammar' in the Search Developer's Guide
and cts:query. This query is AND'd with the query(s) in
the request body.
|
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 query results to return in the response. Accepted
values: values, aggregate, all. Default: all.
|
format?
:
The content type of the request body and the response. This is
equivalent to setting Accept and Content-type headers. The
format parameter overrides the Accept and Content-type
headers. 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.
|
direction?
:
The sort order of returned results. Accepted values:
ascending or descending. The default direction
depends on the sort order defined in the options. The
default is ascending for item-order and
descending for frequency-order.
|
directory?
:
Filter results to include only matches from documents in the
specified database directory.
|
frequency?
:
The method of calculating frequency. Accepted values: item
(default) or fragment. Fragment frequency returns the
number of fragments with an included value. Item frequency returns
the total number occurrences of an included value.
|
limit?
:
The maximum number of values or tuples to retrieve from the lexicon.
Default: No limit.
|
start?
:
The index of the first result to return from the subset defined
by limit. Results are numbered beginning with 1. Default: 1.
|
pageLength?
:
The number of values to return within the subset of values
defined by limit, beginning with the value selected
by start. Default: Return all selected values.
|
aggregate?
:
The name of a built-in or user-defined aggregate function to run
against the lexicon. If the function is not a built-in aggregate,
you must also supply aggregatePath. The supported
builtin aggregate functions are: sum, avg,
min, max, median,
count, stddev, stddev-population,
correlation, covariance,
covariance-population, variance,
variance-population.
|
aggregatePath?
:
The path to the native plugin library containing the implementation of
the function named by the aggregate function. If the
path is empty or is not specified, a built-in aggregate is assumed.
|
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.
|
|
Request Headers:
Accept*:
The expected MIME type of the data in the response.
Accepted types: application/json or
application/xml. Setting the format
parameter overrides this header.
|
Content-Type:
The MIME type of the data in the POST body. Accepted values:
application/json or application/XML.
Setting the format parameter overrides this header.
|
|
Response Headers:
Content-type:
The MIME type of the data in the response. The results will be in
either XML or JSON, depending upon the value of the format
parameter or the Accept header.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
On success, MarkLogic Server responds with a 200 status and the query
results in the response body.
If you use an aggregate function and the target lexicon type does not
support the chosen operation, such as stddev on a string
valued lexicon, or if the aggregate function does not exist,
MarkLogic Server responds with a 400 (Bad Request) status, with
additional error information in the response body.
|
Usage Notes:
Use a query in the q request parameter and/or the request
body to limit the returned values to those occurring in fragments that
match the query. For details, see
'Using a Query to Constrain Results' in the REST Application Developer's Guide.
The request body must contain either a structured query (a serialized
representation of a search: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.
The format parameter always overrides the Content-type
and Accept headers. If you want the request and response bodies to
use different content types, you must use the headers instead of the
format parameter. If you do not use the format
parameter or an Accept header, an XML response is returned.
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 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.
For details on using a combined query, see
POST /v1/search.
When you apply a builtin or user defined aggregate function, the
output is dependent on the function. For details, see
'Analyzing Lexicons and Range Indexes With Aggregate Functions' in the REST Application Developer's Guide.
For more details, see
'Querying Lexicons and Range Indexes' in the REST Application Developer's Guide.
|
Example:
Assume the following query options are installed with the name "index-options":
<options xmlns="http://marklogic.com/appservices/search">
<values name="speaker">
<range type="xs:string">
<element ns="" name="SPEAKER"/>
</range>
</values>
</options>
$ cat query.xml
<query xmlns="http://marklogic.com/appservices/search">
<near-query>
<term-query>
<text>Yorick</text>
</term-query>
<term-query>
<text>Horatio</text>
</term-query>
</near-query>
</query>
$ curl --anyauth --user user:password -X POST -d@./query.xml \
-H "Content-type: application/xml" -i \
http://localhost:8003/v1/values/speaker?options=index-options
==> The distinct values of the SPEAKER element in element range index, for
fragments that match the query "Yorick NEAR Horatio", expressed as a
structured query in the POST body. The results are returned as XML.
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 827
Connection: Keep-Alive
Keep-Alive: timeout=5
<values-response name="speaker" type="xs:string"
xmlns="http://marklogic.com/appservices/search"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
...
<distinct-value frequency="1">HAMLET</distinct-value>
<distinct-value frequency="1">HORATIO</distinct-value>
<distinct-value frequency="1">KING CLAUDIUS</distinct-value>
...
<metrics>
<values-resolution-time>PT0.001943S</values-resolution-time>
<total-time>PT0.003052S</total-time>
</metrics>
</values-response>
|
Example:
Assume the following query options are installed with the name "index-options":
{ "options": {
"values": [ {
"name": "speaker",
"range": {
"type": "xs:string",
"element": { "ns": "", "name": "SPEAKER" }
}
} ]
} }
$ cat query.json
{ "query" : {
"near-query" : {
"term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
}
} }
$ curl --anyauth --user user:password -X POST -d@./query.json -i \
-H "Content-type: application/json" -H "Accept: application/json" \
http://localhost:8003/v1/values/speaker?options=index-options
==> The distinct values of the SPEAKER element in element range index, for
fragments that match the query "Yorick NEAR Horatio", expressed as a
JSON structured query in the POST body. The results are returned as JSON.
{
"values-response": {
"name": "speaker",
"type": "xs:string",
"distinct-value": [
...
{
"frequency": 1,
"_value": "HAMLET"
},
{
"frequency": 1,
"_value": "HORATIO"
},
{
"frequency": 1,
"_value": "KING CLAUDIUS"
},
...
],
"metrics": {
"values-resolution-time": "PT0.002033S",
"total-time": "PT0.004128S"
}
}
}
|
Example:
Assume the following query options are installed with the name "index-options":
<options xmlns="http://marklogic.com/appservices/search">
<values name="speaker">
<range type="xs:string">
<element ns="" name="SPEAKER"/>
</range>
</values>
</options>
$ cat query.xml
<search xmlns="http://marklogic.com/appservices/search">
<query>
<near-query>
<term-query>
<text>Yorick</text>
</term-query>
<term-query>
<text>Horatio</text>
</term-query>
</near-query>
</query>
<options>
<return-metrics>false</return-metrics>
</options>
</search>
$ curl --anyauth --user user:password -X POST -d@./query.xml \
-H "Content-type: application/xml" -i \
'http://localhost:8003/v1/values/speaker?options=index-options
==> The distinct values of the SPEAKER element in element range index, for
fragments that match the query "Yorick NEAR Horatio", expressed as an
XML combined query in the POST body. Dynamic options in the combined
query disable including metrics in the results. The results are returned
as XML.
<values-response name="speaker" type="xs:string"
xmlns="http://marklogic.com/appservices/search"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
...
<distinct-value frequency="1">HAMLET</distinct-value>
<distinct-value frequency="1">HORATIO</distinct-value>
<distinct-value frequency="1">KING CLAUDIUS</distinct-value>
<distinct-value frequency="1">LAERTES</distinct-value>
<distinct-value frequency="1">QUEEN GERTRUDE</distinct-value>
<distinct-value frequency="1">Second Clown</distinct-value>
</values-response>
The following is the same combined query, expressed as JSON:
{
"search" : {
"query" : {
"near-query" : {
"term-query" : [ {"text" : "Yorick"}, {"text":"Horatio" } ]
}
},
"options" : {
"return-metrics" : false
}
}
}
|
Example:
$ cat combined-query.xml
<search xmlns="http://marklogic.com/appservices/search">
<options xmlns="http://marklogic.com/appservices/search">
<constraint name="title">
<word>
<element ns="" name="TITLE" />
</word>
</constraint>
<values name="speaker">
<range type="xs:string">
<element ns="" name="SPEAKER"/>
</range>
</values>
<return-metrics>false</return-metrics>
</options>
<query xmlns="http://marklogic.com/appservices/search">
<word-constraint-query>
<constraint-name>title</constraint-name>
<text>hamlet</text>
</word-constraint-query>
</query>
</search>
$ curl --anyauth --user user:password -X POST -d@./combined-query.xml \
'http://localhost:8003/v1/values/speaker?limit=10&start=4&pageLength=3'
==> The 4th through the 6th values from the set of 10 distinct values
retrieved from the SPEAKER lexicon, as XML. The results retrieved
from the lexicon are constrained to those in documents with the word
"hamlet" in the title.
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 341
Connection: Keep-Alive
Keep-Alive: timeout=5
<values-response name="speaker" type="xs:string"
xmlns="http://marklogic.com/appservices/search"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<distinct-value frequency="1">CORNELIUS</distinct-value>
<distinct-value frequency="1">Danes</distinct-value>
<distinct-value frequency="1">First Ambassador</distinct-value>
</values-response>
The following is the equivalent POST body as JSON:
{ "search": {
"query": {
"word-constraint-query": {
"constraint-name": "title",
"text": "hamlet"
} },
"options": {
"values": {
"name": "speaker",
"range": {
"type": "xs:string",
"element": { "name": "SPEAKER", "ns": ""}
}
},
"constraint": {
"name": "title",
"word": {
"element": { "name": "TITLE", "ns": "" }
}
},
"return-metrics": false
}
} }
|
|
|