|
|
|
 |
Summary:
Retrieve a list of rules (including the rule metadata) that match
documents identified by a query or a list of URIs.
|
Parameters:
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.
|
uri*
:
Specifies the URI of a document to check for rule matches. This
parameter can be specified mutiple times. You cannot use this parameter
with the q or structuredQuery parameters.
For details, see
'Identifying Input Documents Using URIs' in the REST Application Developer's Guide.
|
q?
:
A string query. For details, see
'Identifying Input Documents Using a Query' in the REST Application Developer's Guide.
You cannot use this parameter with the uri parameter.
|
structuredQuery?
:
A structured query with which to select documents to compare to the rules.
The query must be a serialized representation of a
search:query element or a JSON equivalent. For details, see
'Identifying Input Documents Using a Query' in the REST Application Developer's Guide.
You cannot use this parameter with the uri parameter.
|
options?
:
The name of query options previously created via a PUT or POST
request to the /v1/config/query service.
|
rule*
:
The name of an alerting rule previously installed using
PUT /v1/alert/rules/{name}. This options may be
given multiple times. If no rule is supplied, all installed rules
are considered.
|
start?
:
The index of the first result returned by the document selection query
to be considered when matching rules. This parameter and the
pageLength parameter are used to limit the document search
exactly as with /search, prior to applying search matches.
Default: 1. You cannot use this parameter with the uri
parameter.
|
pageLength?
:
The maximum number of documents to return from the document selection
query. This parameter and the start
parameter limit the document selection query results exactly as with
/search. This limits the number of documents tested for
rule matches. Default: 10, or the length configured by the query options.
You cannot use this parameter with the uri parameter.
|
|
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 status 200 and a list of
matching rules in the request body. For rule definition syntax, see
'Defining an Alerting Rule' in the REST Application Developer's Guide.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
For best performance, enable "fast reverse searches" on the database.
Also, if selecting documents using a query, the query should either
return a small number of documents or the number of results returned by
the query should be limited using the start and/or
pageLength request parameters.
Select the documents to consider for rule matches either by specifying
a document selection query using the q and/or
structuredQuery parameters, or by specifying one or more
document URIs using the uri parameter. Additional methods
are available using POST /v1/alerts/match.
If you specify both a string query and a structured
query, they are AND'd together to form the final search query.
When the set of documents to check for rule matches is determined by
a query, you can specify query options using the options
parameter. The options must have been previously installed using the
/config/query service.
To specify a query in the request body instead of using request
parameters, or to specify query options without pre-installing them,
use POST /v1/alerts/match.
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 details, see
'Testing for Matches to Alerting Rules' in the REST Application Developer's Guide and
'Creating Alerting Applications' in the Search Developer's Guide.
|
Example:
$ curl --anyauth --user admin:adm1n -X GET -i -H "Accept: application/xml" \
'http://localhost:8003/v1/alert/match?q=xdmp AND load'
==> The definitions of any rules matching the documents selected by
the string query "xdmp AND load". MarkLogic Server responds with
output similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 1033
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
<rapi:rule>
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
</rapi:rules>
|
Example:
$ curl --anyauth --user admin:adm1n -X GET -i -H "Accept: application/json" \
'http://localhost:8003/v1/alert/match?q=xdmp AND load'
==> The definitions of any rules matching the documents selected by
the string query "xdmp AND load". MarkLogic Server responds with
output similar to the following:
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 378
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "rules": [
{ "rule": {
"name": "example",
"description": "An example rule.",
"search": {
"qtext": [ "xdmp" ],
"options": {
"term": { "term-option": [ "case-sensitive" ] }
}
},
"rule-metadata": {
"author": "me"
}
} }
] }
|
|
|
|
|
 |
Summary:
Retrieve a list of rules (including the rule metadata) that match
either documents in the database identified by a document selection
query defined in the request body or a transient document supplied in the
request body.
|
Parameters:
format?
:
The expected content type of the results. This is equivalent to specifying
the MIME type in the Accept header. The format parameter
overrides the Accept header if both are present. Accepted value:
xml and json. Default: xml.
|
options?
:
The name of query options previously created via a PUT or POST
request to the /v1/config/query service. You can only use
this parameter if the request body contains a structured or combined
query.
|
start?
:
The index of the first result returned by the document selection query
to be considered when matching rules. This parameter and the
pageLength parameter are used to limit the document search
exactly as with /search, prior to applying search matches.
Default: 1. You can only use this parameter if the request body contains
a structured or combined query.
|
pageLength?
:
The maximum number of documents to return from the document selection
query. This parameter and the start
parameter limit the document selection query results exactly as with
/search. This limits the number of documents tested for
rule matches. Default: 10, or the length configured by the query options.
You can only use this parameter if the request body contains a structured
or combined query.
|
|
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 POST body. Accepted values:
application/json or application/XML.
|
|
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 status 200 and a list of
matching rules in the request body. The response body contains XML or
JSON rule definitions.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
For best performance, enable "fast reverse searches" on the database.
Also, if selecting documents using a query, the query should either
return a small number of documents or the number of results returned by
the query should be limited using the start and/or
pageLength request parameters.
Select the documents to consider for rule matches either by specifying
a document selection query in the request body, or by supplying a
single transient document in the request body. The latter allows you
compare a document to stored rules before inserting it into the database.
For other forms of rule matching, use GET /v1/alert/match.
To select documents using a query, construct a request body containing
either a structured query (search:query) or a combined
query and options (search:search), as described in
POST /v1/search. You can
specify document selection query using either JSON or XML; set the
Content-Type header appropriately.
When the set of documents to check for rule matches is determined by
a query, you can use the start and pageLength
parameters to constrain the query results to compare to the rules.
To test a transient document for rule matches, supply an XML or JSON
document in the request body and set the Content-Type header to either
application/xml or application/json.
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 details, see
'Testing for Matches to Alerting Rules' in the REST Application Developer's Guide and
'Creating Alerting Applications' in the Search Developer's Guide.
|
Example:
$ cat match-body.xml
<search xmlns="http://marklogic.com/appservices/search">
<qtext>load</qtext>
<options>
<term>
<term-option>case-sensitive</term-option>
</term>
</options>
</search>
$ curl --anyauth --user user:password -X POST -d @./match-body.xml -i \
-H "Content-type: application/xml" -H "Accept: application/xml" \
'http://localhost:8003/v1/alert/match
==> The definitions of rules that match the documents selected by the
combined query in the request body. MarkLogic Server responds with
output similar to the following.
HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 1033
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
<rapi:rule>
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
</rapi:rules>
|
Example:
$ cat ./transient.xml
<function>
<prefix>xdmp</prefix>
<name>document-delete</name>
</function>
$ curl --anyauth --user user:password -X POST -d @./match-body.xml -i \
-H "Content-type: application/xml" -H "Accept: application/xml" \
'http://localhost:8003/v1/alert/match
==> The definitions of rules that match the transient XML document in
the request body. The results are as JSON, as indicated by the
Accept header. MarkLogic Server responds with output similar to the
following.
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 378
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "rules": [
{ "rule": {
"name": "example",
"description": "An example rule.",
"search": {
"qtext": [ "xdmp" ],
"options": {
"term": { "term-option": [ "case-sensitive" ] }
}
},
"rule-metadata": {
"author": "me"
}
} }
] }
|
|
|
|
|
 |
Summary:
Retrieve the definition of all alert rules previously installed in this
REST API instance using the /v1/alert/{name} service.
|
Parameters:
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 values:
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. The data in
the response body is definitions of all installed rules. Results can
be returned as either XML or JSON, depending up on the format
request parameter or the Accept header setting. For details on the
format of rule definitions, see
'Defining an Alerting Rule' in the REST Application Developer's Guide.
If the Alerting API is not enabled, MarkLogic Server returns status
403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
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.
|
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/xml" \
'http://localhost:8003/v1/alert/rules'
==> The definitions of all installed rules, as XML. MarkLogic Server
responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 542
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
<rapi:rule>
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
</rapi:rules>
|
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/json" \
'http://localhost:8003/v1/alert/rules'
==> The definitions of all installed rules, as JSON. MarkLogic Server
responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 190
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "rules": [
{ "rule": {
"name": "example",
"description": "An example rule.",
"search": {
"qtext": [ "xdmp" ],
"options": {
"term": { "term-option": [ "case-sensitive" ] }
}
},
"rule-metadata": { "author": "me" }
} }
] }
|
|
|
|
DELETE /v1/alert/rules/{name}
|
|
 |
Summary:
Delete an alerting rule previously installed using
PUT /v1/alert/rules/{name}.
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
MarkLogic Server responds with status 204 (Deleted), even if
there is no rule installed with the given name.
If the Alerting API is not enabled, MarkLogic Server returns status 403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
For details, see
'Alerting' in the REST Application Developer's Guide and
'Creating Alerting Applications' in the Search Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
'http://localhost:8003/v1/alert/rules/example'
==> The rule installed under the name "example" is deleted. MarkLogic
Server responds with output similar to the following:
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
GET /v1/alert/rules/{name}
|
|
 |
Summary:
Retrieve the alerting rule definition installed with the given name.
|
Parameters:
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 the requested
rule definition in the response body. Results are returned as
either XML or JSON, depending up on the format request
parameter or the Accept header setting.
If no rule matching {name} is installed, MarkLogic Server
returns status code 404.
If the Alerting API is not enabled, MarkLogic Server returns status
403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
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 the alerting features of the REST API, see
'Alerting' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/xml" \
http://localhost:8003/v1/alert/rules/example
==> The definition of the rule installed under the name "example", in XML.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 499
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
|
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/json" \
http://localhost:8003/v1/alert/rules/example
==> The definition of the rule installed under the name "example", in JSON.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 178
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "rule": {
"name": "example",
"description": "An example rule.",
"search": {
"qtext": [ "xdmp" ],
"options": {
"term": { "term-option": [ "case-sensitive" ] }
}
},
"rule-metadata": { "author": "me" }
} }
|
|
|
|
HEAD /v1/alert/rules/{name}
|
|
 |
Summary:
Test for the existence of a rule with the given name.
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
If a rule with the given name was previously installed using
PUT /v1/alert/rules/{name}, MarkLogic Server returns
status 200. If no such rule exists, status 404 is returned.
If the Alerting API is not enabled, MarkLogic Server returns status
403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
For more information, see
'Alerting' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X HEAD -i \
'http://localhost:8003/v1/alert/rules/json-example'
==> If the rule exists, MarkLogic Server responds with status code 200.
If the rule does not exist, MarkLogic Server responds with status 404.
A unsuccessful test returns output similar to the following:
HTTP/1.1 404 Not Found
Content-type: application/xml
Server: MarkLogic
Content-Length: 365
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:error xmlns:rapi="http://marklogic.com/rest-api">
<rapi:status-code>404</rapi:status-code>
<rapi:status>Not Found</rapi:status>
<rapi:message-code>RESTAPI-NODOCUMENT</rapi:message-code>
<rapi:message>RESTAPI-NODOCUMENT: (err:FOER0000) Resource or document
does not exist: category: alert-rules message: Rule named 'example'
not found
</rapi:message>
</rapi:error>
|
|
|
|
PUT /v1/alert/rules/{name}
|
|
 |
Summary:
Install an alerting rule under the given name.
|
Parameters:
format?
:
The content type of the data in the request body.
Specifying a format overrides the Content-Type request header value.
|
|
Request Headers:
Content-type:
The MIME type of the data in the request body, either
application/json or application/xml.
If the format request parameter is given, it takes
precedence over this header.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
Upon success, MarkLogic Server returns status 201 (Created) or
204 (Updated), depending on whether or not the named rule already exists.
If the payload is invalid, MarkLogic Server responds with status 400
by default. If no rule matching {name} is installed,
MarkLogic Server returns status code 404.
If the Alerting API is not enabled, MarkLogic Server returns status 403.
|
Usage Notes:
Alerting applications require a valid alerting license key. The license
key is required to use the reverse index and to use the Alerting API.
After installing one or more rules, use the /alert/match
service to poll for documents that match rules. This allows you to
create an alerting application using a pull model. To use a push model,
you must use an XQuery implementation in MarkLogic Server, as described in
'Creating Alerting Applications' in the Search Developer's Guide.
For more information, see
'Defining an Alerting Rule' in the REST Application Developer's Guide.
|
Example:
|
Example:
$ cat ./rule.xml
<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
<rapi:name>example</rapi:name>
<rapi:description>An example rule.</rapi:description>
<search:search xmlns:search="http://marklogic.com/appservices/search">
<search:qtext>xdmp</search:qtext>
<search:options>
<search:term>
<search:term-option>case-sensitive</search:term-option>
</search:term>
</search:options>
</search:search>
<rapi:rule-metadata>
<author>me</author>
</rapi:rule-metadata>
</rapi:rule>
$ curl --anyauth --user user:password -X PUT -d @./rule.xml -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/alert/rules/example
==> The rule defined in the file ./rule.xml is installed under the
name "example". MarkLogic Server responds with output similar
to the following:
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
Example:
$ curl --anyauth --user user:password -X PUT -d @./rule.xml -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/alert/rules/json-example
==> The rule defined in the file ./rule.xml is installed under the
name "example". MarkLogic Server responds with output similar
to the following:
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
$ cat ./rule.json
{ "rule": {
"name" : "json-example",
"search" : {
"qtext" : "xdmp",
"options" : { "term" : { "term-option" : "case-sensitive" } }
},
"description": "A JSON example rule.",
"rule-metadata" : { "author" : "me" }
}}
|
|
|
|
|
 |
Summary:
Request a report on whether or not the database configuration includes
index configurations that satisfy all installed query options.
|
Parameters:
format?
:
The format of the content returned by by the request, either
xml (default), json, or html. The
format parameter overrides any format specified in the Accept header.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. Accepted values:
application/json, application/html, or
text/XML (the default). If the format
parameter is set, the Accept header is ignored in favor of the
format parameter.
|
|
Response Headers:
Content-Type:
The MIME type of the content returned in the response body, one of
application/xml, application/json, or
text/html.
|
|
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 responds with status 200 and the
index report in the response body.
|
Usage Notes:
Use this service to determine whether the database attached to
your REST API instance includes all the indexes required
to support the installed query options (created using the
/config/query service).
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 details, see
'Checking Index Availability' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET \
-H "Accept: application/xml" \
http://localhost:8004/v1/config/indexes
==> MarkLogic server responds with a 200 status and the requested
report, as XML. For example, this report shows one missing
path range index:
<rapi:index-summaries xmlns:rapi="http://marklogic.com/rest-api">
<rapi:index-count>2</rapi:index-count>
<rapi:complete>false</rapi:complete>
<rapi:index-summary>
<rapi:name>/v1/config/query/default</rapi:name>
<rapi:complete>true</rapi:complete>
</rapi:index-summary>
<rapi:index-summary>
<rapi:name>/v1/config/query/tuples</rapi:name>
<rapi:complete>false</rapi:complete>
<range type="xs:string" xmlns="http://marklogic.com/appservices/search">
<path-index>/PLAY/ACT/SCENE/TITLE</path-index>
</range>
</rapi:index-summary>
</rapi:index-summaries>
|
Example:
$ curl --anyauth --user user:password -X GET \
-H "Accept: application/json" \
http://localhost:8004/v1/config/indexes
==> MarkLogic server responds with a 200 status and the requested
report, as JSON. For example, this report shows one missing
path range index:
{
"index-summaries": {
"index-summary": [
{
"name": "/v1/config/query/default",
"complete": "true"
},
{
"name": "/v1/config/query/tuples",
"complete": "false",
"range": {
"type": "xs:string",
"path-index": "/PLAY/ACT/SCENE/TITLE"
}
}
],
"index-count": "2",
"complete": "false"
}
}
|
|
|
|
GET /v1/config/indexes/{name}
|
|
 |
Summary:
Request a report on whether or not the database configuration includes
index configurations that satisfy these named query options.
|
Parameters:
format?
:
The format of the content returned by by the request, either
xml (default), json, or html. The
format parameter overrides any format specified in the Accept header.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. Accepted values:
application/json, application/html, or
text/XML (the
default). If the format parameter is set, the Accept
header is ignored in favor of the format parameter.
|
|
Response Headers:
Content-Type:
The MIME type of the content returned in the response body, one of
application/xml, application/json, or
text/html.
depending on the type requested by the format value
or Accept header.
|
|
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 responds with status 200 and the
index report in the response body.
|
Usage Notes:
Use this service to determine whether the database attached to
your REST API instance includes all the indexes required
to support the named query options (created using the
/config/query service).
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 details, see
'Checking Index Availability' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET \
-H "Accept: application/xml" \
http://localhost:8004/v1/config/index/tuples
==> MarkLogic server responds with a 200 status and the requested
report, as XML. For example, this report shows one missing
path range index:
<rapi:index-summaries xmlns:rapi="http://marklogic.com/rest-api">
<rapi:index-count>1</rapi:index-count>
<rapi:complete>false</rapi:complete>
<rapi:index-summary>
<rapi:name>/v1/config/query/tuples</rapi:name>
<rapi:complete>false</rapi:complete>
<range type="xs:string" xmlns="http://marklogic.com/appservices/search">
<path-index>/PLAY/ACT/SCENE/TITLE</path-index>
</range>
</rapi:index-summary>
</rapi:index-summaries>
|
Example:
$ curl --anyauth --user user:password -X GET \
-H "Accept: application/json" \
http://localhost:8004/v1/config/index/tuples
==> MarkLogic server responds with a 200 status and the requested
report, as JSON. For example, this report shows one missing
path range index:
{
"index-summaries": {
"index-summary": [
{
"name": "/v1/config/query/tuples",
"complete": "false",
"range": {
"type": "xs:string",
"path-index": "/PLAY/ACT/SCENE/TITLE"
}
}
],
"index-count": "1",
"complete": "false"
}
}
|
|
|
|
DELETE /v1/config/namespaces
|
|
 |
Summary:
Remove all installed namespace bindings.
|
Required Privilege:
This operation 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:
MarkLogic Server responds with 204 (Deleted).
|
Usage Notes:
To remove a specific binding, use
DELETE /v1/config/namespaces/{prefix}.
For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
http://localhost:8003/v1/config/namespaces
==> MarkLogic Server removes all namespace bindings for the REST
service on port 8003. MarkLogic Server returns the following headers:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
GET /v1/config/namespaces
|
|
 |
Summary:
List all namespace bindings configured for use in queries,
ordered alphabetically by prefix.
|
Parameters:
format?
:
The format of the content returned by by the request, either
xml or json. The format parameter overrides
any format specified in the Accept header.
|
|
Request Headers:
Accept*:
The expected MIME type of the response, either
application/json or application/XML (the
default). If the format parameter is set, the Accept
header is ignored in favor of the format parameter.
|
|
Response Headers:
Content-Type:
The MIME type of the content returned in the response body, one of
application/xml or application/json,
depending on the type requested by the format value
or Accept header.
|
|
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 status 200 (OK) and the
response body contains the requested information.
When requesting XML results, the response body contains data of the
following form for each namespace binding:
<namespace xmlns="http://marklogic.com/sdmp/group">
<prefix>the-prefix</prefix>
<namespace-uri>the-uri</namespace-uri>
</namespace>
When requesting JSON results, the response body contains data of the
following form for each namespace binding:
{ "prefix" : "the-prefix", "uri" : "the-uri" }
|
Usage Notes:
For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.
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.
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/xml" \
http://localhost:8004/v1/config/namespaces
==> MarkLogic server responds with a 200 status and the requested
namespace binding information as XML. For example, the following
data is returned for a single binding of the prefix "bill" to
http://makrlogic.com/examples/shakespeare:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 225
Connection: close
<rapi:namespace-bindings xmlns:rapi="http://marklogic.com/rest-api">
<rapi:namespace>
<rapi:prefix>bill</rapi:prefix>
<rapi:uri>http://marklogic.com/examples/shakespeare</rapi:uri>
</rapi:namespace>
</rapi:namespace-bindings>
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/json" \
http://localhost:8004/v1/config/namespaces
==> MarkLogic server responds with a 200 status and the requested
namespace binding information as JSON. For example, the following
data is returned for a single binding of the prefix "bill" to
http://makrlogic.com/examples/shakespeare:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 92
Connection: close
{"namespace-bindings":[
{
"prefix":"bill",
"uri":"http://marklogic.com/examples/shakespeare"
}
]}
|
|
|
|
POST /v1/config/namespaces
|
|
 |
Summary:
Create or append to namespace bindings that can be used in
subsequent query operations.
|
Parameters:
format?
:
The format of the content in the request body, either
xml or json. The format parameter
overrides any format specified in the Accept header.
|
|
Request Headers:
Content-Type?:
The MIME type of the data in the request body, either
application/xml or application/json.
Ignored if a format parameter is present.
|
|
Required Privilege:
This operation 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 responds with a status 201 (Content
Created). MarkLogic Server responds with a status 400 (Bad Request)
if the request contains a bad binding or attempts to replace an
existing binding with a new value.
|
Usage Notes:
For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.
This method appends to existing namespace bindings. To replace a
binding, use the PUT method.
The content type can be specified using either the
format parameter or Content-type header. One
or the other must be supplied. If both are supplied and are different,
the format parameter takes precedence.
If a binding already exists for the prefix and this request does not
bind the prefix to the same namespace URI, MarkLogic server responds
with status 400 (Bad Request). To change the namespace associated with
prefix, use PUT /v1/config/namespaces/{prefix}.
The request body must have the following format when sending XML:
<rapi:namespace-bindings xmlns="http://marklogic.com/rest-api">
<rapi:prefix>the-prefix</rapi:prefix>
<rapi:uri>the-uri</rapi:uri>
</rapi:namespace-bindings>
The request body must have the following format when sending JSON:
{ "prefix" : "the-prefix", "uri" : "the-uri" }
|
Example:
$ cat ns-xml
<namespace-bindings xmlns="http://marklogic.com/rest-api">
<namespace>
<prefix>bill</prefix>
<uri>http://marklogic.com/examples/shakespeare</uri>
</namespace>
</namespace-bindings>
$ curl --anyauth --user user:password -X POST -d@'./ns-xml' -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/config/namespaces
==> MarkLogic Server creates or appends the namespace binding between
the prefix "bill" and the namespace URI
"http://marklogic.com/examples/shakespeare. MarkLogic Server
returns the following headers:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
Example:
$ cat ns-json
{
"namespace-bindings": [
{
"prefix": "will",
"uri": "http://marklogic.com/examples/shakespeare"
}
]
}
$ curl --anyauth --user user:password -X POST -d@'./ns-json' -i \
-H "Content-type: application/json" \
http://localhost:8003/v1/config/namespaces
==> MarkLogic Server creates or appends the namespace binding between
the prefix "will" and the namespace URI
"http://marklogic.com/examples/shakespeare. MarkLogic Server
returns the following headers.
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
PUT /v1/config/namespaces
|
|
 |
Summary:
Create or replace namespace bindings that can be used in subsequent
query operations.
|
Parameters:
format?
:
The format of the content in the request body, either
xml or json. The format parameter
overrides any format specified in the Accept header.
|
|
Request Headers:
Content-Type?:
The MIME type of the data in the request body, either
application/xml or application/json.
Ignored if a format parameter is present.
|
|
Required Privilege:
This operation 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 responds with a status 204 (Content
Updated). MarkLogic Server responds with a status 400 (Bad Request)
if the request contains a bad binding.
|
Usage Notes:
Use this request for creating or replacing bindings. All existing
bindings are replaced by the bindings in the request body. To add
new bindings without changing existing bindings, use the POST method.
To replace only one binding, use
PUT /v1/config/namespaces/{prefix}.
For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.
The content type can be specified using either the format
parameter or Content-type header. One or the
other must be supplied. If both are supplied and are different,
the format parameter takes precedence.
The request body must have the following format when sending XML:
<rapi:namespace-bindings xmlns="http://marklogic.com/rest-api">
<rapi:prefix>the-prefix</rapi:prefix>
<rapi:uri>the-uri</rapi:uri>
</rapi:namespace-bindings>
The request body must have the following format when sending JSON:
{ "prefix" : "the-prefix", "uri" : "the-uri" }
|
Example:
$ cat ns-xml
<namespace-bindings xmlns="http://marklogic.com/rest-api">
<namespace>
<prefix>bill</prefix>
<uri>http://marklogic.com/examples/shakespeare</uri>
</namespace>
</namespace-bindings>
$ curl --anyauth --user user:password -X PUT -d@'./ns-xml' -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/config/namespaces
==> MarkLogic Server replaces any existing namespace bindings with the
single binding between the prefix "bill" and the namespace URI
"http://marklogic.com/examples/shakespeare. MarkLogic Server
returns the following headers.
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
Example:
$ cat ns-json
{
"namespace-bindings": [
{
"prefix": "will",
"uri": "http://marklogic.com/examples/shakespeare"
}
]
}
$ curl --anyauth --user user:password -X PUT -d@'./ns-json' -i \
-H "Content-type: application/json" \
http://localhost:8003/v1/config/namespaces
==> MarkLogic Server replaces any existing namespace bindings with the
single binding between the prefix "will" and the namespace URI
"http://marklogic.com/examples/shakespeare. MarkLogic Server
returns the following headers.
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
DELETE /v1/config/namespaces/{prefix}
|
|
 |
Summary:
Remove the namespace binding for {prefix}.
|
Required Privilege:
This operation 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 responds with status 204 (Content
Deleted). MarkLogic Server responds with status 204 even if no
binding exists for {prefix}.
|
Usage Notes:
For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
http://localhost:8004/v1/config/namespaces/bill
==> MarkLogic Server removes the namespace binding between the prefix
"bill" and the associated URI and responds with status 204.
MarkLogic server responds with headers of the form:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
GET /v1/config/namespaces/{prefix}
|
|
 |
Summary:
Retrieve the namespace URI associated with the REST service
namespace binding prefix {prefix}.
|
Parameters:
format?
:
The expected format of the response, either xml or
json. Overrides the format specified in the Accept header.
|
|
Request Headers:
Accept*:
The expected MIME type of the response, either
application/json or application/XML (the
default). If the format parameter is set, the Accept
header is ignored in favor of the format parameter.
|
|
Response Headers:
Content-Type:
The MIME type of the content returned in the response body, either
application/xml or application/json.
|
|
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 status 200 and returns the
requested information in the response body, as either XML or JSON.
If no namespace binding exists for {prefix}, MarkLogic
server returns 404 (Not Found).
The response body has the following format when requesting XML:
<namespace xmlns="http://marklogic.com/rest-api">
<prefix>the-prefix</prefix>
<namespace-uri>the-uri</namespace-uri>
</namespace>
The response body has the following format when requesting JSON:
{ "prefix" : "the-prefix", "uri" : "the-uri" }
|
Usage Notes:
For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.
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.
|
Example:
$ curl --anyauth --user user:password -i -X GET \
-H "Accept: application/xml" \
http://localhost:8004/v1/config/namespaces/will
==> MarkLogic Server responds with status 200 and returns the namespace
binding information for prefix "will", as XML. For example:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 170
Connection: close
<rapi:namespace xmlns:rapi="http://marklogic.com/rest-api">
<rapi:prefix>will</rapi:prefix>
<rapi:uri>http://marklogic.com/examples/shakespeare</rapi:uri>
</rapi:namespace>
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/json" \
http://localhost:8004/v1/config/namespaces/will
==> MarkLogic Server responds with status 200 and returns the namespace
binding information for prefix "will", as JSON. For example:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 67
Connection: close
{
"prefix":"will",
"uri":"http://marklogic.com/examples/shakespeare"
}
|
|
|
|
PUT /v1/config/namespaces/{prefix}
|
|
 |
Summary:
Create or modify a namespace binding.
|
Parameters:
format?
:
Specifies the type of the content in the request body. Accepted values:
json and xml (default). If there is no
format parameter, the format must be specified in the Accept header.
|
|
Request Headers:
Content-Type?:
The MIME type of the data in the request body, either
application/xml or application/json.
|
|
Required Privilege:
This operation 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:
MarkLogic Server responds with status 201 (Created) if a new
prefix binding is created as a result of this request. MarkLogic Server
responds with status 204 (Updated) if an existing prefix binding
is updated as a result of this request.
|
Usage Notes:
For details, see 'Using Namespace Bindings' in the REST Application Developer's Guide.
The request body must have the following format when sending XML:
<namespace xmlns="http://marklogic.com/sdmp/group">
<prefix>the-prefix</prefix>
<namespace-uri>the-uri</namespace-uri>
</namespace>
The request body must have the following format when sending JSON:
{ "prefix" : "the-prefix", "uri" : "the-uri" }
|
Example:
$ cat ns-xml
<namespace xmlns="http://marklogic.com/group">
<prefix>bill</prefix>
<namespace-uri>http://marklogic.com/examples/shakespeare</uri>
<namespace>
$ curl --anyauth --user user:password -T './ns-xml' -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/config/namespaces/bill
==> Create or update a namespace binding between the prefix "bill" and the
namespace URI http://marklogic.com/examples/shakespeare. MarkLogic
Server returns the following headers:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 100 Continue
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: close
|
Example:
$ cat ns-json
{ "prefix" : "will", "uri" : "http://marklogic.com/examples/shakespeare" }
$ curl --anyauth --user user:password -T './ns-json' -i \
-H "Content-type: application/json" \
http://localhost:8003/v1/config/namespaces/will
==> Create or update a namespace binding between the prefix "will" and the
namespace URI http://marklogic.com/examples/shakespeare. MarkLogic
Server returns the following headers:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 100 Continue
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
DELETE /v1/config/properties
|
|
 |
Summary:
Reset all MarkLogic REST API instance configuration properties to their default values.
|
Required Privilege:
This operation 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 status 204 (Reset).
|
Usage Notes:
All properties are reset to their default values.
For more details, see
'Configuring Instance Properties' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
http://localhost:8003/v1/config/properties
==> All configuration properties are reset to default values.
|
|
|
|
GET /v1/config/properties
|
|
 |
Summary:
Retrieve a list of all MarkLogic REST API instance configuration properties
names and settings.
|
Parameters:
format?
:
Specifies the content type of the response, as an alternative to using
the Accept header. Accepted values: json and
xml (default). This value takes precedence over the Accept
headers.
|
|
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 content returned in the response body, one of
application/xml or application/json,
depending on the type requested by the format value
or Accept header.
|
|
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 and provides the
requested information in the response body.
|
Usage Notes:
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 details, see
'Retrieving Configuration Information' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET -H "Accept: application/xml" -i \
http://localhost:8003/v1/config/properties
==> The instance configuration properties in the response body, as XML.
For example:
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 87
Connection: close
<rapi:properties xmlns:rapi="http://marklogic.com/rest-api">
<rapi:debug>false</rapi:debug>
<rapi:document-transform-out/>
<rapi:error-format>xml</rapi:error-format>
<rapi:validate-options>true</rapi:validate-options>
<rapi:update-policy>merge-metadata</rapi:update-policy>
</rapi:properties>
|
Example:
$ curl --anyauth --user user:password -X GET -H "Accept: application/json" -i \
http://localhost:8003/v1/config/properties
==> The instance configuration properties in the response body, as JSON.
For example:
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 43
Connection: close
{
"update-policy":"merge-metadata",
"validate-options":true,
"document-transform-out":"",
"debug":false,
"error-format":"xml"
}
|
|
|
|
PUT /v1/config/properties
|
|
 |
Summary:
Set or modify MarkLogic REST API instance configuration properties.
|
Parameters:
format?
:
The content type of the information in the request body. Accepted types:
json or xml. This parameter takes precedence
over the Content-Type request header.
|
|
Request Headers:
Content-Type?:
The MIME type of the data in the request body, one of
application/xml or application/json.
The format parameter overrides the Content-type
header if both are present and do not match.
|
|
Required Privilege:
This operation 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 responds with a 204 (Updated)
status.
|
Usage Notes:
Only the properties included in the request body are modified.
For a list of property names, see
GET /v1/config/properties/{name}.
For more details, see
'Configuring Instance Properties' in the REST Application Developer's Guide.
|
Example:
$ cat ./settings
<properties xmlns="http://marklogic.com/rest-api">
<debug>false</debug>
</properties>
$ curl --anyauth --user user:password -X POST -d@'./settings' -i \
"Content-Type: application/xml" \
http://localhost:8003/v1/config/properties
==> MarkLogic Server updates the settings for the properties named
in the settings file.
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 5
Connection: close
|
Example:
$ cat ./settings
{"validate-options":"false"}
$ curl --anyauth --user user:password -X PUT -d@'./settings' -i \
"Content-Type: application/json" \
http://localhost:8003/v1/config/properties
==> MarkLogic Server updates the settings for the properties named
in the settings file.
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 5
Connection: close
|
|
|
|
PUT /v1/config/properties/(property-name)
|
|
 |
Summary:
Set the value of the MarkLogic REST API instance configuration property named by
{property-name}.
|
Parameters:
format?
:
The MIME type of the metadata in the request body. Specifying a format
overrides the Content-Type request header value. See the usage notes
for details on special handling for XML, JSON, and binary content.
|
|
Request Headers:
Content-Type?:
The MIME type of the data in the request body, one of
application/xml or application/json.
|
|
Required Privilege:
This operation 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 responds with status 204 (Updated).
|
Usage Notes:
For a list of property names, see
GET /v1/config/properties/{name}.
For more details, see
'Configuring Instance Properties' in the REST Application Developer's Guide.
|
Example:
$ cat setting
<rapi:debug xmlns:rapi="http://marklogic.com/rest-api">
true
</rapi:debug>
$ curl --anyauth --user user:password -T ./setting -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/config/properties/debug
==> The "debug" property is set to true. MarkLogc Server returns
the following headers:
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: close
|
Example:
$ cat setting
{ "debug" : "true" }
$ curl --anyauth --user user:password -T ./setting -i \
-H "Content-type: application/json" \
http://localhost:8003/v1/config/properties/debug
==> The "debug" property is set to true. MarkLogc Server returns
the following headers:
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
DELETE /v1/config/properties/{property-name}
|
|
 |
Summary:
Reset the MarkLogic REST API instance configuration property {property-name}
to its default value.
|
Required Privilege:
This operation 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 status 204 (Reset).
|
Usage Notes:
For a list of property names, see
GET /v1/config/properties/{name}.
For more details, see
'Configuring Instance Properties' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE \
http://localhost:8003/v1/config/properties/debug
==> The "debug" configuration property is reset to its default value.
|
|
|
|
GET /v1/config/properties/{property-name}
|
|
 |
Summary:
Retrieve the value of the MarkLogic REST API instance configuration
property named by {property-name}.
|
Parameters:
format?
:
Specifies the content type of the response, as an alternative to using
the Accept header. Accepted values: json and
xml (default). This value takes precedence over the Accept
headers.
|
|
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 content returned in the response body, one of
application/xml or application/json,
depending on the type requested by the format value
or Accept header.
|
|
Required Privilege:
This operation 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 200 status, with the requested
data in the response body. If the requested property does not exist,
MarkLogic Server returns status 404 (Not Found).
|
Usage Notes:
The expected response content 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.
The following properties are available for configuration:
| Propety Name |
Description |
| content-versions |
Deprecated. Use update-policy instead. |
| debug |
Controls debugging output. Allowed values: true, false.
Default: false.
|
| document-transform-out |
The name of a default content transformation to apply when
retrieving documents from the database using /documents. Default:
no transformation.
|
| error-format |
The content type of error responses. Allowed values: xml, json.
Default: xml.
|
| update-policy |
Determines the behavior of conditional GET, PUT, POST, and DELETE
on /documents and metadata handling on updates. Allowed
Values: merge-metadata (default),
version-required, version-optional,
overwrite-metadata. For details, see
'Understanding Optimistic Locking' in the REST Application Developer's Guide
and
'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
|
| validate-options |
Whether or not to validate query options when they are created
or updated. Allowed values: true, false. Default: true. |
For more details, see
'Configuring Instance Properties' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET -i \
http://localhost:8003/v1/config/properties/debug
==> MarkLogic Server returns the setting of the configuration property
"debug", as XML. For example:
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 74
Connection: close
<rapi:debug xmlns:rapi="http://marklogic.com/rest-api">
false
</rapi:debug>
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/json" \
http://localhost:8003/v1/config/properties/debug
==> MarkLogic Server returns the setting of the configuration property
"debug", as JSON. For example:
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 15
Connection: close
{"debug":false}
|
|
|
|
|
 |
Summary:
Remove all named query options.
|
Required Privilege:
This operation 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 successful removal, MarkLogic returns status 204 (Deleted).
|
Usage Notes:
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
http://localhost:8003/v1/config/query
==> All installed options are removed. The following headers are returned:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
|
 |
Summary:
Retrieve a list of all the named query options available for use
with the service. For example, the names of query options previously
stored using POST requests to the /config/query service.
The results include the name and URI of all named query options.
|
Parameters:
format?
:
Specifies the content type of the response, as an alternative to using
the Accept header. Accepted values: json and
xml (default). This value takes precedence over the Accept
headers.
|
|
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 status 200 (OK) and the
response body contains the options data. If no query options are
installed, MarkLogic Server returns an empty <query-options>
node (XML) or an empty array (JSON).
|
Usage Notes:
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 details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET -i \
http://localhost:8003/v1/config/query
==> A list of the names of installed options, as XML. Assuming two named
query options, "scene" and "title" were previously installed:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
Content-type: text/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 318
Connection: close
<rapi:query-options xmlns:rapi="http://marklogic.com/rest-api">
<rapi:options>
<rapi:name>default</rapi:name>
<rapi:uri>/v1/config/query/default</rapi:uri>
</rapi:options>
<rapi:options>
<rapi:name>title</rapi:name>
<rapi:uri>/v1/config/query/title</rapi:uri>
</rapi:options>
<rapi:options>
<rapi:name>scene</rapi:name>
<rapi:uri>/v1/config/query/scene</rapi:uri>
</rapi:options>
</rapi:query-options>
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/json" \
http://localhost:8003/v1/config/query
==> A list of the names of installed options, as JSON. Assuming two named
query options, "scene" and "title" were previously installed:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
Content-type: text/plain; charset=UTF-8
Server: MarkLogic
Content-Length: 318
Connection: close
[
{
"name": "default",
"uri": "/v1/config/query/default"
},
{
"name": "title",
"uri": "/v1/config/query/title"
},
{
"name": "scene",
"uri": "/v1/config/query/scene"
}
]
|
|
|
|
DELETE /v1/config/query/(default|{name})
|
|
 |
Summary:
Remove the named (or default) query options from the App Server.
|
Required Privilege:
This operation 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 204 (Deleted) status.
|
Usage Notes:
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
http://localhost:8003/v1/config/query/scene
==> MarkLogic Server removes the options installed under the
name "scene". The response includes the following headers:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
GET /v1/config/query/(default|{name})
|
|
 |
Summary:
Retrieve the query options whose name matches the name in the
request URI, or retrieve the default query options.
|
Parameters:
format?
:
Specifies the content type of the response, as an alternative to using
the Accept header. Accepted values: json and
xml (default). This value takes precedence over the Accept
headers.
|
|
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 responds with a status 200 (OK) and
returns the requested information in the response body, XML or JSON.
If the named configuration does not exist, MarkLogic Server
returns a 404 status.
|
Usage Notes:
The response body contains a list of search:options nodes,
expressed in either XML or JSON, depending upon the format
parameter or Accept header setting. For details on the options, see
PUT /v1/config/query/(default|{name}).
The returned configuration does not include configuration
inherited at runtime from the default or global query options.
The XML or JSON structure returned by this method is suitable for
passing to a PUT or POST request to /config/query.
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET -i \
http://localhost:8003/v1/config/query/title
==> The query options previously saved under the name "title".
For example:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 172
Connection: close
<options xmlns="http://marklogic.com/appservices/search">
<constraint name="title">
<word>
<element ns="" name="TITLE"/>
</word>
</constraint>
</options>
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/json" \
http://localhost:8003/v1/config/query/tuples
==> The query options previously saved under the name "tuples".
For example:
Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 271
Connection: close
{ "options": {
"tuples": [ {
"name": "speaker-title",
"range": [
{
"type": "xs:string",
"element": {
"ns": "",
"name": "SPEAKER"
}
},
{
"type": "xs:string",
"path-index": {
"text": "/PLAY/ACT/SCENE/TITLE"
}
}
]
} ],
"constraint": [ {
"name": "title",
"word": {
"element": {
"ns": "",
"name": "TITLE"
}
}
} ]
} }
|
|
|
|
POST /v1/config/query/(default|{name})
|
|
 |
Summary:
Create or append to named query options.
|
Parameters:
format?
:
The content type of the information in the request body. Accepted types:
json or xml. This parameter takes precedence
over the Content-Type request header.
|
|
Request Headers:
Content-Type:
The MIME type of the data in the POST body, either
application/json or application/xml.
Ignored if the request includes a format parameter.
|
|
Required Privilege:
This operation 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 status 201 (Created) or
204 (Updated).
If the payload is invalid, MarkLogic Server responds with status 400
by default. However, validation may be disabled. For details, see
/config/properties.
|
Usage Notes:
The POST body must be a valid search:options node, expressed
in either XML or JSON, depending upon the request Content-Type header or
format parameter. For options information, see
PUT /v1/config/query/(default|{name}).
If the named options do not exist, new ones are created.
If the named options exist, the options in the POST body are added
to the existing definition.
If {name} is default, default query
options are installed or updated.
Named query options are versioned by MarkLogic server. The version
identifier returned in the response ETag header may be
used in subsequent conditional GET requests to the
/config/query/{name} service to restrict requests to
particular option versions.
For a summary of available options, see
PUT /v1/config/query/(default|{name}). 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.
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
$ cat > options
<options xmlns="http://marklogic.com/appservices/search">
<constraint name="title">
<word>
<element ns="" name="TITLE" />
</word>
</constraint>
</options>
$ curl --anyauth --user user:password -X POST -d@'./options' -i \
-H "Content-type:application/xml" \
http://localhost:8003/v1/config/query/title
==> Install options named "title" which constrains searches
to words in the TITLE element. The request returns headers of
the form:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
PUT /v1/config/query/(default|{name})
|
|
 |
Summary:
Create or replace named query options.
|
Parameters:
format?
:
The content type of the information in the request body. Accepted types:
json or xml. This parameter takes precedence
over the Content-Type request header.
|
|
Request Headers:
Content-type:
The MIME type of the data in the request body, either
application/json or application/xml.
Ignored if the request includes a format parameter.
|
|
Required Privilege:
This operation 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 status 201 (Created) or
204 (Updated).
If the payload is invalid, MarkLogic Server responds with status 400
by default. However, validation may be disabled. For details, see
/config/properties.
|
Usage Notes:
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
The request body must be a valid search:options node,
expressed in either XML or JSON, depending upon the request Content-Type
header or format parameter. See the Usage Notes, below.
By default, options are validated. Options validation can be disabled
using the /config/properties service.
If the named options do not exist, they are created.
If the named options exist, the options in the request body replace
the existing query options.
If {name} is default, the default search
options are modified.
Query options are expressed as a multi-level JSON or XML structure.
The following list is brief summary of the top level option XML elements
or JSON objects. For details, see
'Search Customization Using Query Options' in the Search Developer's Guide,
'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.
- additional-query
-
Additional serialized queries that are AND'd with any string
or structured query supplied to a request.
- concurrency-level
-
The maximum number of threads used to resolve facets.
- constraint
-
Constraints used to control the search and faceting.
- debug
-
Activate debugging mode.
- default-suggestion-source
-
Define content to be used as the default source of search
suggestions.
- extract-metadata
-
Specify data to return in the
metadata section of
the response output.
- forest
-
One or more forest ids.
- fragment-scope
-
The global fragment scope over which to search, either properties
or documents.
- grammar
-
Specify a custom search grammar. The default grammar defines
"Google-style" parsing.
- operator
-
A list of state elements, each representing a unique runtime
configuration option.
- page-length
-
The number of results per page. The default is 10.
- quality-weight
-
A weighting factor to use in the query. The default is 1.0.
- return-aggregates
-
Whether to include results from builtin or user-defined
aggregate functions in the search response. Default: true.
- return-constraints
-
Whether to include the original constraint definitions in the
results. Default: false.
- return-facets
-
Whether to include resolved facets in the results. Default: true.
- return-frequencies
-
Whether to include value frequencies in range indexes and lexicons
in the results. Default: true.
- return-metrics
-
Whether to include statistics in the results. Default: true.
- return-plan
-
Whether to include
xdmp:plan output in the
results. Default: false.
- return-qtext
-
Whether to include the original query text in the results.
Default: true.
- return-query
-
Whether to include the XML query representation in the results.
Default: false.
- return-results
-
Whether to include search results in the output. Default: true.
- return-similar
-
Whether to include a list of URLS of similar documents with
each search result. Default: false.
- return-values
-
Whether to include values from range indexes and lexicons in
the results. Default: true.
- search-option
-
For advanced usrs. Additional options to pass in, such as
filtered, unfiltered, and
score-logtfidf. Default: No additional options.
- searchable-expression
-
An expression to search. Whatever expression is specified
is return from the search.
- sort-order
-
Set the default sort order.
- suggestion-source
-
A constraint source to override a named constraint when using
search:suggest.
- term
-
Specifies handling of empty searches and controls option
for how individual are represented when parsing the search.
- transform-results
-
Specifies a function for processing search results to create
snippet output.
- tuples
-
Specifies constraints for finding value range index and
lexicon co-ocurrences.
- values
-
Specifies constraints for finding values in range indexes and
lexicons.
|
Example:
$ curl --anyauth --user user:password -T './options2' -i \
-H "Content-type:application/xml" \
http://localhost:8003/v1/config/query/scene
==> MarkLogic Server creates or updates the query options named "scene".
The response includes the following headers:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 100 Continue
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
DELETE /v1/config/query/(default|{name})/{child-element}
|
|
 |
Summary:
Remove an option setting from the named query options.
|
Required Privilege:
This operation 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:
MarkLogic Server returns status 204 Deleted status.
|
Usage Notes:
{child-element} should be the name of a child element of
a search:options node. For an option summary, see
PUT /v1/config/query/(default|{name}).
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.
If {child-element} is unrecognized, this request does nothing.
If the named query options contain multiple occurrences of the
child element, MarkLogic Server deletes all occurrences. For example,
DELETE /v1/config/query/my-options/constraint deletes all
<constraint/> elements of "my-options".
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
|
|
|
|
GET /v1/config/query/(default|{name})/{child-element}
|
|
 |
Summary:
Retrieve the setting for a particular option in named query options.
|
Parameters:
format?
:
Specifies the content type of the response, as an alternative to using
the Accept header. Accepted values: json and
xml (default). This value takes precedence over the Accept
headers.
|
|
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 responds with a 200 staus and returns
the requested information in the response body, in the format requested.
|
Usage Notes:
The {element-name} component of the request URI must be
the localname of a child element of search:options. For
information on query options, see
PUT /v1/config/query/(default|{name}).
The response body contains a search:options node, expressed
as either XML or JSON, depending on the setting of the format
parameter or Accept header. The returned options node contains only
the request child element(s). For information about the structure and
contents of query options, see
PUT /v1/config/query/(default|{name}).
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
Assume the following options are installed under the name "my-options":
<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 -i -X GET \
http://localhost:8003/v1/config/query/my-options/values
==> MarkLogic Server returns the following headers and the requested
subset of my-options. Results are in the default format, XML.
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 187
Connection: close
<options xmlns="http://marklogic.com/appservices/search">
<values name="speaker">
<range type="xs:string">
<element ns="" name="SPEAKER"/>
</range>
</values>
</options>
|
Example:
Assume the following options are installed under the name "my-options":
{ "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 -i -X GET \
-H "Accept: application/json" \
http://localhost:8003/v1/config/query/my-options/values
==> MarkLogic Server returns the following headers and the requested
subset of my-options, as JSON.
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 112
Connection: close
{ "options": {
"values": [ {
"name": "speaker",
"range": {
"type": "xs:string",
"element": {
"ns": "",
"name": "SPEAKER"
}
}
} ]
} }
|
|
|
|
POST /v1/config/query/(default|{name})/{child-element}
|
|
 |
Summary:
Add options to existing named query options, or create new named
query options if {name} does not already exist.
|
Parameters:
format?
:
The content type of the information in the request body. Accepted types:
json or xml. This parameter takes precedence
over the Content-Type request header.
|
|
Request Headers:
Content-Type:
The MIME type of the data in the request body. Accepted values:
application/json or application/xml.
Ignored if the format parameter is present.
|
|
Required Privilege:
This operation 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 status 201 (Created) or
204 (Updated).
If the payload is invalid or applying the payload results in invalid
query options, MarkLogic Server responds with status 400 (Bad Request)
by default. Options validation can be disabled. For details, see
see the validate-options in
'Instance Configuration Properties' in the REST Application Developer's Guide.
|
Usage Notes:
The POST body must be a valid search:options node, expressed
in either XML or JSON, depending upon the request Content-Type header or
format parameter.
For a summary of available options, see
PUT /v1/config/query/(default|{name}).
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.
Multiple option elements (settings) may be included in the options node
if {child-element} is an element that can occur multiple times
in query options. For example, multiple search constraints
(<constraint/>) may be set in a single request.
However, all options in the payload must be of the same type.
If no query options are installed under {name}, they are
created. If the named query options exist, the options in the POST
body are appended. If options validation is enabled (the default)
and adding the new options would result in invalid query options,
the query options remain unchanged, and a 400 status is returned.
Options validation can be disabled. For details, see
validate-options in
'Instance Configuration Properties' in the REST Application Developer's Guide.
If {name} is default, the default search
options are modified.
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
$ cat added-constraint.xml
<options xmlns="http://marklogic.com/appservices/search">
<constraint name="title">
<word>
<element ns="" name="TITLE" />
</word>
</constraint>
</options>
$ curl --anyauth --user user:password -i -X POST -d@"added-constraint.xml" \
-H "Content-type: application/xml" \
http://localhost:8003/v1/config/query/my-options/constraint
==> The "title" constraint is added to the "my-options" query options. If
the query options already contain other <constraint/> elements, they
are unchanged. MarkLogic Server returns the following headers:
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
Example:
$ cat added-constraint.json
{ "options": {
"constraint": [ {
"name": "title",
"word": {
"element": {
"ns": "",
"name": "TITLE"
}
}
} ]
} }
$ curl --anyauth --user user:password -i -X POST -d@"added-constraint.json" \
-H "Content-type: application/json" \
http://localhost:8003/v1/config/query/my-options/constraint
==> The "title" constraint is added to the "my-options" query options. If
the query options already contain other <constraint/> elements, they
are unchanged. MarkLogic Server returns the following headers:
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
PUT /v1/config/query/(default|{name})/{child-element}
|
|
 |
Summary:
Replace options in existing named query options, or create new named
query options if {name} does not already exist.
|
Parameters:
format?
:
The content type of the information in the request body. Accepted types:
json or xml. This parameter takes precedence
over the Content-Type request header.
|
|
Request Headers:
Content-Type:
The MIME type of the data in the request body. Accepted values:
application/json or application/xml.
Ignored if the format parameter is present.
|
|
Required Privilege:
This operation 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 responds with
status 201 (Created) or 204 (Updated).
If the payload is invalid or applying the payload results in invalid
query options, MarkLogic Server responds with status 400 (Bad Request)
by default. Options validation can be disabled. For details, see
see the validate-options in
'Instance Configuration Properties' in the REST Application Developer's Guide.
|
Usage Notes:
The request payload should be a valid search:options node,
expressed in either XML or JSON, depending upon the request Content-Type
header or format parameter. For a summary of available options, see
PUT /v1/config/query/(default|{name}).
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.
If no query options are installed under {name}, they are
created. If the named query options exist, the options in the request
body replace all existing option elements with the same name.
For example, if the query options contains three
<constraint/> options and the request body includes
only one <constraint/>, the three existing constraints
are removed and replaced with the one in the request body.
If options validation is enabled (the default) and the new options
would result in invalid query options, the query options remain
unchanged, and a 400 status is returned. Options validation can be
disabled. For details, see
validate-options in
'Instance Configuration Properties' in the REST Application Developer's Guide.
The request body can contain multiple option elements (settings)
if {child-element} is an element that can occur multiple times
in query options. For example, multiple search constraints
(<constraint/>) can be set in a single request.
However, all options in the payload must be of the same type.
If the named query options do not exist, create new named query options.
If the named query options exist, the options in the request body replace
any existing options of the same name. For example, if the query options
contains 3 constraint options and the PUT request includes only one
constraint, all 3 constraints are removed and replaced with the single
constraint from the request.
If {name} is default, the default search
options are modified.
For more details, see
'Configuring Query Options' in the REST Application Developer's Guide.
|
Example:
$ cat added-constraint.xml
<options xmlns="http://marklogic.com/appservices/search">
<constraint name="title">
<word>
<element ns="" name="TITLE" />
</word>
</constraint>
</options>
$ curl --anyauth --user user:password -i -X PUT -d@"added-constraint.xml" \
-H "Content-type: application/xml" \
http://localhost:8003/v1/config/query/my-options/constraint
==> The "title" constraint is added to the "my-options" query options. If
the query options already contain other <constraint/> elements, they
are removed. MarkLogic Server returns the following headers:
HTTP/1.1 204 Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
Example:
$ cat added-constraint.json
{ "options": {
"constraint": [ {
"name": "title",
"word": {
"element": {
"ns": "",
"name": "TITLE"
}
}
} ]
} }
$ curl --anyauth --user user:password -i -X PUT -d@"added-constraint.json" \
-H "Content-type: application/json" \
http://localhost:8003/v1/config/query/my-options/constraint
==> The "title" constraint is added to the "my-options" query options. If
the query options already contain other <constraint/> elements, they
are removed. MarkLogic Server returns the following headers:
HTTP/1.1 204 Updated
Location:
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
|
 |
Summary:
Retrieve a list of installed resource service extensions, including
their metadata.
|
Parameters:
format?
:
The expected content type of the response, either xml or
json. Overrides the Accept header.
|
refresh?
:
Whether or not to refresh metadata before generating the response.
Default: true.
|
|
Request Headers:
Accept*:
The expected MIME type of the response, either
application/xml, application/json, or
text/xml. Ignored if the format parameter
is present.
|
|
Response Headers:
Content-type:
The MIME type of the content in the response, either
application/xml or application/json.
|
|
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 status 200 (OK) and returns
the requested listing in XML or JSON in the response body. The amount
of detail available for a given extension depends on the metadata
specified during extension installation.
|
Usage Notes:
Specify the expected response content type using either the
format parameter or Accept header. If you supply
both, the format parameter takes precedence. If you specify
neither, XML is returned.
When refresh is true (the default), extension metadata
is rebuilt from the most recent installation of all extensions. When
set to false, the metadata in the response reflects the contents as of
the last refresh, and may be out of synch if there has been a
subsequent update to the extension. You should only need to set
refresh to false if you find this request is taking too long.
Extension metadata is only used for informational purposes, so the
ability of client applications to use an extension is not affected by
out of synch metadata.
For details, see
'Discovering Resource Service Extensions' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -H "Accept: application/xml" -X GET -i \
http://localhost:8004/v1/config/resources
==> A list of resource service extensions is returned as XML in the response
body. For example, the output below reflects a extension, "example",
which supports only a GET method. The GET method accepts a single
string parameter, "the-uri". The provider is "Acme Widgets".
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 571
Connection: close
<rapi:resources xmlns:rapi="http://marklogic.com/rest-api">
<rapi:resource>
<rapi:name>example</rapi:name>
<rapi:title/>
<rapi:version/>
<rapi:provider-name>Acme Widgets</rapi:provider-name>
<rapi:description/>
<rapi:methods>
<rapi:method>
<rapi:method-name>get</rapi:method-name>
<rapi:parameter>
<rapi:parameter-name>the-uri</rapi:parameter-name>
<rapi:parameter-type>string</rapi:parameter-type>
</rapi:parameter>
</rapi:method>
</rapi:methods>
<rapi:resource-source>/v1/resources/example</rapi:resource-source>
</rapi:resource>
</rapi:resources>
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/json" \
http://localhost:8004/v1/config/resources
==> A list of resource service extensions is returned as JSON in the response
body. For example, the output below reflects a single extension, "example",
which supports only a GET method. The GET method accepts a single
string parameter, "the-uri". The provider is "Acme Widgets".
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Content-type: application/json
Server: MarkLogic
Content-Length: 286
Connection: close
{
"resources": {
"resource": [
{
"name": "example",
"title": "",
"version": "",
"provider-name": "Acme Widgets",
"description": "",
"methods": {
"method": [
{
"parameter": [
{
"parameter-name": "the-uri",
"parameter-type": "string"
}
],
"method-name": "get"
}
]
},
"resource-source": "/v1/resources/example"
}
]
}
}
|
|
|
|
DELETE /v1/config/resources/{name}
|
|
 |
Summary:
Uninstall the named resource service extension.
|
Required Privilege:
This operation 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:
MarkLogic Server responds with 204 Deleted.
|
Usage Notes:
For more information, see
'Extending the REST API' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
http://localhost:8004/v1/config/resources/example
==> The resource service extension installed with the name "example"
is removed. MarkLogic Server responds with headers of the form:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
GET /v1/config/resources/{name}
|
|
 |
Summary:
Retrieve the XQuery library module implementing the named resource
service extension.
|
Request Headers:
Accept?:
The expected MIME type of the response. Only
application/xquery is accepted.
|
|
Response Headers:
Content-type:
The MIME type of the content in the response. The content type
is always application/xquery.
|
|
Required Privilege:
This operation 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 status 200 (OK) and
returns the XQuery library module implementing the extension
in the response body.
|
Usage Notes:
For more details, see
'Retrieving the Implementation of a Resource Service Extension' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -H "Accept: application/xquery" -i \
-X GET http://localhost:8004/v1/config/resources/example
==> The contents of the XQuery library module that implements the
"example" resource services. MarkLogic Server returns:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Content-type: application/xquery
Server: MarkLogic
Content-Length: 650
Connection: close
xquery version "1.0-ml";
module namespace example="http://marklogic.com/rest-api/resource/example";
declare function example:get(
...
|
|
|
|
PUT /v1/config/resources/{name}
|
|
 |
Summary:
Create or update a resource service extension.
|
Parameters:
provider?
:
The name of the provider of the service. Optional, used only as metadata.
|
version?
:
The version of the service. Optional, used only as metadata.
|
title?
:
The title of the service. Optional, used only as metadata.
|
description?
:
A description of the service. Optional, used only as metadata.
|
method*
:
The name of an HTTP method supported by the extension. Accepted
values: get, put, post
delete. The parameter may be specified multiple times
to specify multiple methods. Optional, used only as metadata.
|
method:{name}*
:
The name, type, and cardinality of a method parameter. For example,
get:the-uri=string. The method must be one of
get, put, post, or
delete. The {name} is the
parameter name. The parameter value is an XQuery SequenceType,
including cardinality (*, ?, etc.) such as appears in the type
declaration of an XQuery function parameter. Optional, used only
as metadata.
|
|
Request Headers:
Content-type:
The type of the request body. Since request body must contain an
XQuery library module that implements the services provided for
the named resource, the content type must be
application/xquery
|
|
Required Privilege:
This operation 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
|
Usage Notes:
For details on implementing a resource service extension, see
'Extending the REST API' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X PUT -i \
-H "Content-type: application/xquery" -d@"./example.xqy" \
'http://localhost:8004/v1/config/resources/example'
==> A resource addressable through /v1/resources/example. MarkLogic Server
returns the following headers:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Created
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 4
Connection: close
|
Example:
$ curl --anyauth --user user:password -X PUT -i \
-H "Content-type: application/xquery" -d@"./example.xqy" \
'http://localhost:8004/v1/config/resources/example?method=get&get:the-uri=string&provider=Acme Widgets'
==> A resource addressable through /v1/resources/example. The metadata for
the extension will include parameter name and type information for the
GET method. MarkLogic Server returns the following headers:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Created
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 4
Connection: close
|
|
|
|
GET /v1/config/transforms
|
|
 |
Summary:
Retrieve metadata about all transforms installed using the
/v1/config/transforms/{name} service.
|
Parameters:
format?
:
Specifies the content type of the response, as an alternative to using
the Accept header. Accepted values: json and
xml (default). This value takes precedence over the Accept
headers.
|
refresh?
:
Whether or not to refresh metadata before generating the response.
Default: true.
|
|
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.
|
|
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 status 200 (OK) and returns
the requested information in the response body.
|
Usage Notes:
For more details, see
'Discovering Transformations' in the REST Application Developer's Guide.
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.
When refresh is true (the default), transform metadata
is rebuilt from the most recent installation of all transforms. When
set to false, the metadata in the response reflects the contents as of
the last refresh, and may be out of synch if there has been a
subsequent update to the extension. You should only need to set
refresh to false if you find this request is taking too long.
Transform metadata is only used for informational purposes, so
neither the acessibility nor the output of a transform is affected by
out of date metadata. The implementation is always up to date.
When refresh is true (the default), extension metadata
is rebuilt from the most recent installation. When set to false, the
metadata in the response reflects the contents as of the last refresh
or App Server restart, and may be out of synch if there has been a
subsequent update to the extension. You should only need to set
refresh to false if you find this request is taking too long.
|
Example:
$ curl --anyauth --user user:password -i -X GET -H "Accept: application/xml" \
http://localhost:8004/v1/config/transforms
==> A list of installed transforms and their metadata, as XML. For example:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 101
Connection: close
<?xml version="1.0" encoding="UTF-8"?>
<rapi:transforms xmlns:rapi="http://marklogic.com/rest-api">
<rapi:transform>
<rapi:name>example</rapi:name>
<rapi:title>example transform</rapi:title>
<rapi:version/>
<rapi:provider-name/>
<rapi:description/>
<rapi:transform-parameters>
<rapi:parameter>
<rapi:parameter-name>style?</rapi:parameter-name>
<rapi:parameter-type>xs:string</rapi:parameter-type>
</rapi:parameter>
<rapi:parameter>
<rapi:parameter-name>tag</rapi:parameter-name>
<rapi:parameter-type>xs:string</rapi:parameter-type>
</rapi:parameter>
</rapi:transform-parameters>
<rapi:transform-source>/v1/transforms/example</rapi:transform-source>
</rapi:transform>
</rapi:transforms>
|
Example:
$ curl --anyauth --user user:password -i -X GET \
-H "Accept: application/json" \
http://localhost:8004/v1/config/transforms
==> A list of installed transforms and their metadata, as JSON. For example:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Content-type: application/json
Server: MarkLogic
Content-Length: 331
Connection: close
{
"transforms": {
"transform": [
{
"name": "example",
"title": "example transform",
"version": "",
"provider-name": "",
"description": "example transform",
"transform-parameters": {
"parameter": [
{
"parameter-name": "style",
"parameter-type": "xs:string?"
},
{
"parameter-name": "tag",
"parameter-type": "xs:string"
}
]
},
"transform-source": "/v1/transforms/example"
}
]
}
}
|
|
|
|
DELETE /v1/config/transforms/{name}
|
|
 |
Summary:
Remove the named transform.
|
Required Privilege:
This operation 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 successful removal, MarkLogic Server returns status 204 (Transform
Deleted).
|
Usage Notes:
For details, see
'Working With Content Transformations' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
http://localhost:8004/v1/config/transforms/example
==> The transform named "example" is uninstalled. MarkLogic Server
responds with headers of the form:
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
GET /v1/config/transforms/{name}
|
|
 |
Summary:
Retrieve the XQuery or XSLT implementation installed for the
named transform.
|
Request Headers:
Accept?:
The MIME type of the data expected in the response, either
application/xslt+xml or application/xquery.
|
|
Response Headers:
Content-Type:
The MIME type of the data in the response, either
application/xslt+xml or application/xquery.
|
|
Required Privilege:
This operation 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 responds with status 200 (OK) and returns
the transform implementation in the response body.
|
Usage Notes:
For details, see
'Retrieving the Implementation of a Transformation' in the REST Application Developer's Guide.
To install a transform, use PUT /v1/config/transforms/{name}.
To retrieve a list of available transforms use
GET /v1/config/transforms.
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/xquery" \
http://localhost:8004/v1/config/transforms/example
==> The XQuery library module implementing the "example" transform.
For example:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 200 OK
Content-type: application/xquery
Server: MarkLogic
Content-Length: 508
Connection: close
xquery version "1.0-ml";
module namespace example="http://marklogic.com/rest-api/transform/example";
declare function example:transform(
...
|
|
|
|
PUT /v1/config/transforms/{name}
|
|
 |
Summary:
Create or update the named transform.
|
Parameters:
title?
:
Title metadata for the transform. This free-form string is returned
by GET /v1/config/transforms.
|
provider?
:
Provider metadata for the transform. This free-form string is returned
by GET /v1/config/transforms.
|
version?
:
Version metadata for the transform. This free-form string is returned
by GET /v1/config/transforms.
|
description?
:
Description metadata for the transform. This free-form string is returned
by GET /v1/config/transforms.
|
trans:{name}*
:
The name, type, and cardinality of a transform-specific parameter.
{name} is the parameter name. The parameter value is an
XQuery SequenceType, including cardinality (*, ?, etc.) such as appears
in the type declaration of an XQuery function parameter.
|
format?
:
Specifies the MIME type of the request body, as an alternative to
specifying format via the Content-type header. Accepted values:
xslt or xquery. This value takes
precedence over the Content-type header.
|
|
Request Headers:
Content-Type:
The MIME type of the data in the request body, one of
application/xslt+xml or application/xquery.
Ignored if a format parameter is present.
|
|
Required Privilege:
This operation 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 responds with status 204 (Transform
Created).
|
Usage Notes:
Once installed, the transform can be used with other MarkLogic
REST API services that accept a transform parameter.
It is recommended that the request always include a Content-type
header, even though it is not strictly required.
If the named transform is already installed, MarkLogic Server replaces
the content and metadata with the new information from this request.
For more details, see
'Working With Content Transformations' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X PUT -d@"./transform.xqy" -i \
-H "Content-type: application/xquery" \
'http://localhost:8004/v1/config/transforms/example?title=example transform'
==> Install an XQuery transform named "example" with the description
"example transform" and the implementation contained in transform.xqy.
MarkLogic Server responds with headers of the form:
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 211
Connection: close
HTTP/1.1 204 Created
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 4
Connection: close
|
|
|
|
|
 |
Summary:
Remove a document, or reset document metadata.
|
Parameters:
uri
:
The URI of the document to delete or for which to remove metadata.
|
category*
:
The category of data to remove/reset. Category may be specified
multiple times to remove or reset any combination of content and
metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata to update all metadata.
See the Usage notes below.
|
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:
If-Match?:
Specifies a document version identifier that must match the current
version of the target document for the delete to succeed. If the current
version of the document does not match, a 412 (Precondition Failed) status
is returned. A value of 0 indicates the document must not already exist
in the database. Ignored unless optimistic locking is enabled; for
details see
'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
MarkLogic Server returns status 204 (Document Deleted).
|
Usage Notes:
Removing content also removes all metadata for the document.
Removing a binary document also removes extracted metadata stored in
a separate XHTML document. See
'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.
Sending a DELETE request for permissions metadata resets the permissions
to the default for the current user.
Sending a DELETE request for quality resets the content quality to
the default value (0).
For more details, see
'Removing Documents from the Database' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -X DELETE -i \
http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml
==> The document with URI /shakespeare/plays/a_and_c.xml is removed.
The following headers are returned:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 204 Document Deleted
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
|
 |
Summary:
Retrieve document content and/or metadata from the database.
|
Parameters:
uri+
:
One or more URIs for documents in the database. If you specify
multiple URIs, the Accept header must be multipart/mixed.
|
category*
:
The category of data to fetch about the requested document. 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.
|
format?
:
The expected format of metadata returned in the response.
Accepted values: xml or json. This
parameter does not affect document content. For metadata, this
parameter overrides the MIME type in the Accept header, except
when the Accept header is multipart/mixed. For details, see
'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
|
transform?
:
Names a content transformation previously installed via the
/config/transforms service. The service applies the
transformation to all documents prior to constructing the response.
|
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 response. For a multi-document read
request or a single document request for both content and metadata,
this header must be set to multipart/mixed. When
requesting only metadata for a single document, use
application/json or application/XML (default)
or set the format parameter.
|
If-None-Match?:
This header is not supported for multi-document requests.
If the current version of the requested document matches the version
identifier in this header, return a 304 (Not Modified) response.
This header is ignored unless content versioning is enabled. For
details, see
'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
|
Range?:
This header is not supported for multi-document requests.
Specifies a zero-based start index or start and end indices for
retrieving a sub-binary from a binary document.
|
|
Response Headers:
Content-Type:
The MIME type of the content returned in the response body.
|
Content-Disposition:
On a multi-document read request response, each part includes this
header with the following format:
Content-Disposition: attachment; filename=db-uri; category=part-contents; format=part-content-type. For details, see
'Bulk Read Response Overview' in the REST Application Developer's Guide.
|
Etag:
This header is not supported for multi-document requests.
An opaque version identifier for the requested document, suitable
for subsequent use in an If-None-Match or If-Match header. This
header is only available when content versioning is enabled. For
details, see
'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
|
|
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 status 200 (OK) and the requested
document(s) and/or metadata.
For a single-document read that returns both content and metadata, the
response body MIME type is multipart/mixed with metadata
in the first part and content in the second part.
For a multi-document read, the response body MIME type is
multipart/mixed and each part contains either content or
metadata, with the part type and document URI indicated by the
Content-Disposition header. For details see
'Bulk Read Response Overview' in the REST Application Developer's Guide.
|
Usage Notes:
You can use this request to retrieve the contents and/or metadata of
a single document or multiple documents. The request headers
If-None-Match, Range, and Etag
are not supported when reading multiple documents. For details about
single document reads, see
'Retrieving Documents from the Database' in the REST Application Developer's Guide.
For details on multi-document reads, see
'Reading Multiple Documents by URI' in the REST Application Developer's Guide.
You can request content only, metadata only, or both, through the
category parameter. Metadata can be requested selectively,
such as category=collections, or as a whole, using
category=metadata. Metadata can only be returned as XML
or JSON.
Content negotiation for fetching metadata as XML or JSON is supported
through the format parameter or Accept header.
In a single document read, one or the other must be supplied when fetching
metadata only; if both are supplied and are different, the
format parameter takes precedence. In a multi-document
read request, the Accept header must be multipart/mixed
so you must use format to specify the metadata format.
The default metadata format is XML except when reading content and
metadata together for a single JSON document, in which case metadata
is returned as XML by default. To get consistent behavior when using
multi-document read of content and metadata together, you should
explicitly set format. Otherwise, you will receive XML
metadata for N > 1 documents, and JSON metadata for N = 1 documents.
There is no default content negotiation or conversion on document content.
The format of the data in the response is based on the MIME type mapping
defined for the URI extension. For details, see
'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
You can support custom content negotiations using the
/transform service; see
'Working With Content Transformations' in the REST Application Developer's Guide.
When you retrieve both content and metadata for a single document in
the same request, the response content type is
multipart/mixed, with the first part containing metadata
and the second part containing the content. For details, see
'Retrieving Content and Metadata in a Single Request' in the REST Application Developer's Guide.
For more details and examples, see
'Retrieving Documents from the Database' in the REST Application Developer's Guide
and
'Reading Multiple Documents by URI' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -X GET -i \
http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml
==> The document at URI /shakespeare/plays/a_and_c.xml in
response body, and the following headers:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
vnd.marklogic.document-format: xml
Content-type: text/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 251855
Connection: close
<?xml version="1.0" encoding="UTF-8"?>
<PLAY xml:lang="en">
<TITLE>The Tragedy of Antony and Cleopatra</TITLE>
...
|
Example:
curl --anyauth --user user:password -X GET -i \
'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&category=metadata'
==> The metadata for the document with URI /shakespeare/plays/a_and_c.xml
in the response body:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
vnd.marklogic.document-format: xml
Content-type: application/xml; charset=UTF-8
Server: MarkLogic
Content-Length: 437
Connection: close
<rapi:metadata uri="/shakespeare/plays/a_and_c.xml"
xsi:schemaLocation="http://marklogic.com/rest-api/database dbmeta.xsd"
xmlns:rapi="http://marklogic.com/rest-api"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<rapi:collections/>
<rapi:permissions/>
<prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
<playtype>TRAGEDY</playtype>
</prop:properties>
<rapi:quality>0</rapi:quality>
</rapi:metadata>
|
Example:
curl --anyauth --user user:password -X GET -i \
-H "Accept: multipart/mixed; boundary=document-part-boundary" \
'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&format=json\&category=properties\&category=content'
==> A multipart response with the JSON metadata in the first part
and the XML document content in the second:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=document-part-boundary
Server: MarkLogic
Content-Length: 252175
Connection: close
--document-part-boundary
vnd.marklogic.document-part: metadata
Content-Type: application/json
Content-Length: 37
{"properties":{"playtype":"TRAGEDY"}}
--document-part-boundary
vnd.marklogic.document-part: content
Content-Type: text/xml
Content-Length: 251873
<?xml version="1.0" encoding="UTF-8"?>
<PLAY xml:lang="en">
<TITLE>The Tragedy of Antony and Cleopatra</TITLE>
...
|
Example:
curl --anyauth --user user:password -X GET -i \
-H "Accept: multipart/mixed; boundary=document-part-boundary" \
'http://localhost:8003/v1/documents?uri=doc1.xml&uri=doc2.json'
==> A multipart response containing two parts, one containing
the XML content for doc1.xml and the other containing the
JSON content for doc2.json.
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=document-part-boundary
Server: MarkLogic
Content-Length: 458
Connection: Keep-Alive
Keep-Alive: timeout=5
--document-part-boundary
Content-Type: text/xml
Content-Disposition: attachment; filename=doc1.xml; category=content;
format=xml
Content-Length: 75
<?xml version="1.0" encoding="UTF-8"?>
<root>some document content</root>
--document-part-boundary
Content-Type: application/json
Content-Disposition: attachment; filename=doc2.json; category=content;
format=json
Content-Length: 36
{"key":"some document content"}
--document-part-boundary--
|
|
|
|
|
 |
Summary:
Returns the same headers as an equivalent GET (content/metadata fetch)
on the /documents service. For example, you can use the
returned content length to determine the end boundary for iterating over
sub-binaries.
|
Parameters:
format?
:
The format any metadata returned by the request, either
xml or json. The format parameter applies
only to metadata and overrides any format specified in the Accept
header.
|
category*
:
The category of data for which to generate headers. Category
can be specified multiple times to request any combination of content
and metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata
to request all categories except content.
|
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.
|
uri
:
The URI of a document in the database.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. Metadata may only be returned
as application/json or application/XML (the
default).
|
Range?:
Specifies a zero-based start index or start and end indices for
retrieving a sub-binary from a binary document.
|
|
Response Headers:
Content-Type:
The MIME type of the content that would be returned by a GET.
|
Etag:
An opaque version identifier for the requested document, suitable
for subsequent use in an If-None-Match or If-Match header. This
header is only available when content versioning is enabled. For
details, see
'Client-Side Cache Management Using Content Versioning' in the REST Application Developer's Guide.
|
|
Response:
Upon success, MarkLogic Server returns status 200 (OK) and the same headers
that are returned by an equivalent GET on the /documents service.
|
Usage Notes:
Use this method to determine what headers an equivalent GET will return.
For example, the returned content length header may be used to set the
ending boundary when using ranges to iterate over sub-binaries in a
binary document.
|
Example:
curl --anyauth --user user:password -X HEAD -i \
-H "Accept: multipart/mixed; boundary=picket-fence" \
'http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml&category=metadata\&category=content\&format=json'
==> The headers that would be returned by a GET request to the
same URL.
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Connection: close
HTTP/1.1 200 OK
Content-type: multipart/mixed; boundary=picket-fence
Server: MarkLogic
Connection: close
|
|
|
|
|
 |
Summary:
Perform a partial update to content or metadata of a document.
|
Parameters:
uri
:
The URI of the document to be updated.
|
category*
:
The category of data to insert or update. Category can be specified
multiple times to insert or replace any combination of content and
metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata to update all metadata.
Default: content.
|
format?
:
The content type of the data in the request body. Specifying a format
overrides the Content-Type request header value. For details, see
the Usage notes and
'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.
|
|
Request Headers:
Content-Type?:
The MIME type of the data in the request body. See the usage notes
for details on special handling for XML, JSON, and binary content.
|
If-Match?:
Specifies a document version identifier that must match the current
version of the target document for the update to succeed. If the current
version of the document does not match, a 412 (Precondition Failed) status
is returned. A value of 0 indicates the document must not already exist
in the database. Ignored unless optimistic locking is enabled; for
details see
'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server responds with 204 (Content Updated).
|
Usage Notes:
If using the PATCH method is problematic in your environment, you can
use POST instead. For details, see POST /v1/documents.
To perform a partial update of content and/or metadata for an existing
document, specify the document URI using the uri parameter
and set the category parameter to reflect what to update,
if needed. The request body must be a JSON or XML patch specification.
For details, see
'Partially Updating Document Content or Metadata' in the REST Application Developer's Guide.
You can only apply partial updates of content to XML and JSON
documents. You can apply partial updates of metadata to any document type.
When updating document permissions, the permissions must include at least
one update permission.
For more details, see
'Loading Content into the Database' in the REST Application Developer's Guide.
|
Example:
$ cat ./my-patch.xml
<rapi:patch xmlns:rapi="http://marklogic.com/rest-api"
xmlns:my-ns="http://marklogic.com/examples">
<rapi:insert context="/my-ns:parent" position="last-child">
<my-ns:child>inserted</my-ns:child>
</rapi:insert>
</rapi:patch>
curl --anyauth --user user:password -X PATCH -d@'./my-patch.xml' -i \
-H "Content-type: application/xml" \
'http://localhost:8003/v1/documents?uri=/doc/example.xml'
==> Perform a partial update on the document with URI /doc/example.xml.
A <child/> element is added as the last child of the node with
the XPath /my-ns:parent. MarkLogic Server responds with headers
similar to the following:
Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5
HTTP/1.1 204 Content Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
Example:
$ cat ./my-patch.json
{ "patch": [
{ "insert": {
"context": "$.parent",
"position": "last-child",
"content": { "child": "inserted" }
}}
] }
curl --anyauth --user user:password -X PATCH -d@'./my-patch.json' -i \
-H "Content-type: application/json" \
'http://localhost:8003/v1/documents?uri=/doc/example.json'
==> Perform a partial update on the document with URI /doc/example.json.
A key-value pair with key 'child' is added as the last child of the
top level 'parent' key. MarkLogic Server responds with headers
similar to the following:
Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
|
 |
Summary:
Insert or update content and/or metadata for multiple documents in
a single request.
|
Parameters:
transform?
:
Names a content transformation previously installed via the
/transforms service. Tranforms are applied only to
content parts. The transform is applied to the content of a part
prior to updating or inserting the document.
|
trans:{name}*
:
A transform parameter name and value. For example,
trans:myparam=1.
|
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:
Content-Type?:
The MIME type of the data in the request body or of a part.
The Content-Type header for the request must be
multipart/mixed. Each part must include a Content-Type
header specifying the MIME type of the part. See the Usage Notes
for accepted values for the Content-Type of a part.
|
Content-Disposition:
Each part must include a Content-Disposition that indicates
the part type (content or metadata) and the document uri, and can
contain additional options. For details, see
'Writing Multiple Documents' in the REST Application Developer's Guide.
|
Accept:
The expected MIME type of the data in the response. Allowed values:
application/xml, application/json.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server responds with 200 (OK) and the data in
the response body is an XML or JSON summary of the inserted or updated
documents. The returned data is sufficient to construct a read request
for each document. For details, see
'Response Overview' in the REST Application Developer's Guide.
|
Usage Notes:
Use this request to insert or update multiple documents in a single
request. For single-document operations, see
PUT /v1/documents and other forms of
POST /v1/documents.
These notes provide only a brief overview of the supported features.
For details, see
'Writing Multiple Documents' in the REST Application Developer's Guide.
The multipart POST body can contain a mixture of document content and
metadata. Each part must contain either content or metadata, indicated
by use of the category parameter in the
Content-Disposition part header. Metadata can apply to
a specific document or multiple documents, depending on
the content disposition.
You can insert or update a document at a known URI or at a server
generated URI. For details, see
'Constructing a Content Part' in the REST Application Developer's Guide.
You cannot use server URI generation with a metadta part.
The Content-Disposition header can include the parameters listed
below. You must include either inline or
attachment. Other parameters depend on the type of part
(content, request default metadata, document-specific metadata, etc.).
| Parameter |
Description |
| inline |
The part contains either content for a document with a server
generated URI or request default metadata. Use the
category parameter to distinguish content from metadata.
If this is a content part, you must also include
extension. If this is a metadata part, you must not
include extension. Use the
category parameter to distinguish content from metadata.
|
| attachment |
The part contains either content or metadata for a document with
a specific URI (provided using filename). Use the
category parameter to distinguish content from metadata.
|
| filename=db-uri |
Specifies an explicit document URI. Use extension
to have MarkLogic Server generate a URI instead. For a given part,
filename and extension are mutually
exclusive.
|
| category=metadata |
Indicates that the part contains metadata. |
| extension=suffix |
Specifies a URI extension to use when the document URI is generated
by MarkLogic Server. The generated URI will end with "." plus this
extension. For a given part, filename and
extension are mutually exclusive. For details, see
'Automatically Generating a Document URI' in the REST Application Developer's Guide.
|
| directory=path |
Specifies a directory prefix to use when the document URI is generated
by MarkLogic Server. The directory prefix must end with "/".
If the part header includes a directory parameter, it
it must also include an extension parameter.
For a given part, filename and directory
are mutually exclusive. For details, see
'Automatically Generating a Document URI' in the REST Application Developer's Guide.
|
| lang=language |
For a JSON content part, this parameter specifies the JSON
content language. Allowed values: Any value accepted in the
xml:lang attribute.
|
| repair=level |
For an XML content part, the level of XML repair to perform.
Allowed values: full (default) or none. Use
full to request the server to repair malformed input
XML. Use none to request the server to reject malformed
input XML. If repair results in multiple root nodes, the update is
rejected.
|
| extract=properties-or-document |
For a binary content part, whether or not to extract metadata, and
whether to store the extracted metadata as document properties or
in a separate XHTML document. Allowed values: properties
or document. See note below.
|
| versionId=id |
When optimistic locking is enabled by setting the REST instance
configuration property update-policy to
version-required or version-optional,
reject this request if the current version of this document does
not match the version in versionId. Only applicable
to content parts. Ignored if optimistic locking is not enabled.
This option is equivalent to supplying a version id through the
If-Match header of a single document update.
For details, see
'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.
|
With the exception of properties, any pre-existing metadata for
documents updated by a multi-document write is replaced with either
the metadata in the request or the in scope metadata defaults. For
details see
'Constructing a Metadata Part' in the REST Application Developer's Guide.
Extracting metadata for a binary content part as properties replaces
any existing properties on
the document. Extracting metadata to a document creates an XHTML document
that differs from the input document only by having a xhtml
file name extension. If CPF is installed in the database, the XHTML
document includes a link to the binary document. For details, see
'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.
If no permissions are explicitly set, documents you create with the
MarkLogic REST API have a read permission for the rest-reader
role and an update permission for the rest-writer role.
If you explicitly set permissions, the permissions must include at least
one update permission.
For more details, see
'Writing Multiple Documents' in the REST Application Developer's Guide.
|
Example:
NOTE: Do not attempt to cut-and-paste this example body. A multipart
body must contain control characters that are not preserved when you
cut-and paste. See "Generating Example Payloads with XQuery" in the
REST Application Developer's Guide for one alternative.
$ cat body
--BOUNDARY
Content-Type: application/xml
Content-Disposition: inline; category=metadata
Content-Length: 554
<?xml version="1.0" encoding="UTF-8"?>
<rapi:metadata xmlns:rapi="http://marklogic.com/rest-api">
<rapi:quality>1</rapi:quality>
<prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
<my-prop>my first property</my-prop>
</prop:properties>
<rapi:collections>
<rapi:collection>my-first-coll</rapi:collection>
</rapi:collections>
<rapi:permissions>
<rapi:permission>
<rapi:role-name>readers</rapi:role-name>
<rapi:capability>read</rapi:capability>
</rapi:permission>
</rapi:permissions>
</rapi:metadata>
--BOUNDARY
Content-Type: application/xml
Content-Disposition: attachment; filename="doc1.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"
Content-Length: 22
{ "key": "some json" }
--BOUNDARY
Content-Type: application/xml
Content-Disposition: attachment; filename="doc3.xml"
Content-Length: 60
<?xml version="1.0" encoding="UTF-8"?>
<root>some xml</root>
--BOUNDARY--
curl --anyauth --user user:password -X POST -i \
--data-binary @body \
-H "Content-type: multipart/mixed; boundary=BOUNDARY"
-H "Accept: application/json" 'http://localhost:8003/v1/documents'
==> Insert 3 documents into the database, doc1.xml, doc2.json, and
doc3.xml. All three documents use the request default metadata
provided in the first part. For more examples, see the REST
Application Developer's Guide. 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: 169
Connection: Keep-Alive
Keep-Alive: timeout=5
{ "documents": [
{ "uri": "doc1.xml",
"mime-type": "application/xml",
"category": [
"metadata",
"content"
]
},
{ "uri": "doc2.json",
"mime-type": "application/json",
"category": [
"metadata",
"content"
]
},
{ "uri": "doc3.xml",
"mime-type": "application/xml",
"category": [
"metadata",
"content"
]
}
] }
If you set the Accept header to application/XML, the data in the
response is similar to the following:
<rapi:documents xmlns:rapi="http://marklogic.com/rest-api">
<rapi:document>
<rapi:uri>doc1.xml</rapi:uri>
<rapi:category>metadata</rapi:category>
<rapi:category>content</rapi:category>
<rapi:mime-type>application/xml</rapi:mime-type>
</rapi:document>
<rapi:document>
<rapi:uri>doc2.json</rapi:uri>
<rapi:category>metadata</rapi:category>
<rapi:category>content</rapi:category>
<rapi:mime-type>application/json</rapi:mime-type>
</rapi:document>
<rapi:document>
<rapi:uri>doc3.xml</rapi:uri>
<rapi:category>metadata</rapi:category>
<rapi:category>content</rapi:category>
<rapi:mime-type>application/xml</rapi:mime-type>
</rapi:document>
</rapi:documents>
|
|
|
|
|
 |
Summary:
Insert or update document contents and/or metadata, at a
caller-supplied document URI.
|
Parameters:
uri
:
The URI of the document to be created or updated.
|
category*
:
The category of data to insert or update. Category may be specified
multiple times to insert or replace any combination of content and
metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata to update all metadata.
See the Usage notes below.
|
format?
:
The content type of the metadata in the request body. Specifying a format
overrides the Content-Type request header value. For details, see the
Usage Notes and
'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
|
lang?
:
When ingesting JSON content, this parameter specifies the JSON
content language. Accepted values:
Any value accepted in the xml:lang attribute.
|
collection*
:
The URI of a collection to which to add the document. Use this
parameter only when the request includes content; see the Usage notes
for details.
|
quality?
:
The quality of this document. A positive value increases the
relevance score of the document in text search functions. The converse
is true for a negative value. The default value is 0. Use this parameter
only when the request includes content; see the Usage notes for details.
|
perm:{role}*
:
Assign the document to the listed role, with the permission given in
the parameter value. For example, perm:editor=update.
Valid values: read, update, execute. Only the named role
is changed. Unspecified roles retain their current permissions. Use
this parameter only when the request includes content; see the Usage
notes for details.
|
prop:{name}*
:
Attach the named property to the document, with the given property value.
For example, prop:decade=70. The property name must be an
xs:NCName. If the property already exists, its value is
replaced. Only the named property is modified. Unspecified properties
are unaffected. Use this parameter only when the request includes
content; see the Usage notes for details.
|
extract?
:
For binary content, whether or not to extract metadata, and whether to
store the extracted metadata as properties or in a separate XHTML
document. Accepted values: properties or
document. See note below.
|
repair?
:
The type of XML repair to perform on the input content. Accepted values:
full (default) or none. Use full
to request the server to repair malformed input XML. Use none to request the server to reject malformed input XML. If repair results
in multiple root nodes, the update is rejected.
|
transform?
:
Names a content transformation previously installed via the
/transforms service. The service applies the transformation
to the content prior to updating or inserting the document or metadata.
|
trans:{name}*
:
A transform parameter name and value. For example,
trans:myparam=1.
|
forest-name?
:
Specifies the name of a forest into which this document is inserted.
If the document already exists in the database, it remains in its
existing forest. If no such forest exists or if no such forest is
attached to the context database, an error is raised. If the
document already exists and the forest in which it is stored is
set to delete-only, an error is raised.
|
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:
Content-Type?:
The MIME type of the data in the request body. See the usage notes
for details.
|
If-Match?:
Specifies a document version identifier that must match the current
version of the target document for the update to succeed. If the current
version of the document does not match, a 412 (Precondition Failed) status
is returned. A value of 0 indicates the document must not already exist
in the database. Ignored unless optimistic locking is enabled; for
details see
'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server responds with 201 (Created) or
204 (Updated).
|
Usage Notes:
If no permissions are explicitly set, documents you create with the
MarkLogic REST API have a read permission for the rest-reader
role and an update permission for the rest-writer role.
You can add or update content and metadata in a single request in two
ways: Construct a multipart/mixed request with the
metadata and content in the request body parts, or place the content
in the request body and specify metadata using the collection,
quality, perm, and prop request
parameters. You cannot combine these methods: Metadata request parameters
are ignored when the request body includes metadata. The metadata request
parameters are only usable when you also insert or update content.
Use a multipart/mixed request to insert or update content
and metadata in the body of a single request. Put the metadata in the
first part and specify its content type (XML or JSON) using the
Content-type header of the part or the format request
parameter. Put the content in the second part and set the Content-type
header on the part to the appropriate MIME type for the content.
To add or replace just metadata, specify the metadata in the request
body and specify its content type (XML or JSON) using the Content-type
header or the format request parameter. You cannot use
the metadata request parameters without content.
Supply metadata specified in category parameters in the
request body, contained in a single XML or JSON container. For details, see
'Loading Content into the Database' in the REST Application Developer's Guide.
Use category to completely replace a category of metadata.
For example, category=properties replaces all existing
properties of the document. Use the specific metadata parameters to
selectively modify a metadata category. For example, use
prop:decade=70 to add or modify just the "decade" property.
Using category=metadata replaces all metadata for
the document. Metadata request parameters are ignored when the request
body includes metadata.
Extracting metadata as properties replaces any existing properties on
the document. Extracting metadata to a document creates an XHTML document
that differs from the input document only by having a xhtml
file name extension. If CPF is installed in the database, the XHTML
document includes a link to the binary document. For details, see
'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.
When updating document permissions, the permissions must include at least
one update permission.
For more details, see
'Loading Content into the Database' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -T ./my-content -i \
-H "Content-type: application/xml" \
http://localhost:8003/v1/documents?uri=/shakespeare/plays/a_and_c.xml
==> If a document already exists with URI /shakespeare/plays.a_and_c.xml,
the document contents are updated with the contents of the file
./my-content, and the following headers are returned:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 100 Continue
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: close
==> If a document does not already exist with URI
/shakespeare/plays/a_and_c.xml, a new document in created with
that URI, and the following headers are returned:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 100 Continue
HTTP/1.1 201 Document Created
Location: /shakespeare/plays/a_and_c.xml
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
POST /v1/documents?extension={ext}
|
|
 |
Summary:
Create a new document with a server-generated database URI.
|
Parameters:
extension
:
Specifies a URI extension to use when the document URI is generated
by MarkLogic Server. The generated URI will end with "." plus this
extension. This parameter is required.
|
category*
:
The category of data to insert or update. Category may be specified
multiple times to insert or replace any combination of content and
metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata to update all metadata.
See the Usage notes below.
|
directory?
:
Specifies a directory prefix to use when the document URI is generated
by MarkLogic Server. If an extension parameter is
present and there is no directory parameter, then no
directory prefix is included in the generated URI. If the request
includes a directory parameter, it must also include
an extension parameter.
You cannot use this parameter with the uri parameter.
|
format?
:
The content type of the metadata in the request body. Specifying a format
overrides the Content-Type request header value. For details, see
the Usage notes and
'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
|
lang?
:
When ingesting JSON content, this parameter specifies the JSON
content language. Accepted values:
Any value accepted in the xml:lang attribute.
|
collection*
:
The URI of a collection to which to add the document. Use this
parameter only when the request includes content; see the Usage notes
for details.
|
quality?
:
The quality of this document. A positive value increases the
relevance score of the document in text search functions. The converse
is true for a negative value. The default value is 0. Use this parameter
only when the request includes content; see the Usage notes for details.
|
perm:{role}*
:
Assign the document to the listed role, with the permission given in
the parameter value. For example, perm:editor=update.
Valid values: read, update, execute. Only the named role
is changed. Unspecified roles retain their current permissions. Use
this parameter only when the request includes content; see the Usage
notes for details.
|
prop:{name}*
:
Attach the named property to the document, with the given property value.
For example, prop:decade=70. The property name must be an
xs:NCName. If the property already exists, its value is
replaced. Only the named property is modified. Unspecified properties
are unaffected. Use this parameter only when the request includes
content; see the Usage notes for details.
|
extract?
:
For binary content, whether or not to extract metadata, and whether to
store the extracted metadata as properties or in a separate XHTML
document. Accepted values: properties or
document. See note below.
|
repair?
:
The type of XML repair to perform on the input content. Accepted values:
full (default) or none. Use full
to request the server to repair malformed input XML. Use none to request the server to reject malformed input XML. If repair results
in multiple root nodes, the update is rejected.
|
transform?
:
Names a content transformation previously installed via the
/transforms service. The service applies the transformation
to the content prior to updating or inserting the document or metadata.
|
trans:{name}*
:
A transform parameter name and value. For example,
trans:myparam=1.
|
forest-name?
:
Specifies the name of a forest into which this document is inserted.
If the document already exists in the database, it remains in its
existing forest. If no such forest exists or if no such forest is
attached to the context database, an error is raised. If the
document already exists and the forest in which it is stored is
set to delete-only, an error is raised.
|
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:
Content-Type?:
The MIME type of the data in the request body. See the usage notes
for details on special handling for XML, JSON, and binary content.
|
|
Response Headers:
Location?:
If the request successfully creates a new document with a server
assigned URI, then the Location contains a reference
to the /documents service that you can use to retrieve the new
document. That is, a reference of the following form is returned:
/v1/documents?uri=generated-uri.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server responds with 201 (Document Created) or
204 (Updated or Unchanged).
|
Usage Notes:
Use this form of POST /v1/documents to create a new
document with a server-generated URI. The request can optionally
include metadata. For all other document and metadata creation or
update operations, see PUT /v1/documents or the other
forms of POST /v1/documents.
To create a new document with a server-assigned URI, specify a URI
extension using the extension parameter, optionally specify
a directory prefix using the directory parameter, and include
content as one of the category parameter values.
The request body must be either the document content or a multi-part
message that includes both metadata and content, as described below.
The server-generated URI is returned in the Location
response header.
You can create content and metadata in a single request in two
ways: Construct a multipart/mixed request with the
metadata and content in the request body parts, or place the content
in the request body and specify metadata using the collection,
quality, perm, and prop request
parameters. You cannot combine these methods: Metadata request parameters
are ignored when the request body includes metadata. You cannot insert
metadata without also inserting content.
Use a multipart/mixed request to insert content
and metadata in the body of a single request. Put the metadata in the
first part and specify its content type (XML or JSON) using the
Content-type header of the part or the format request
parameter. Put the content in the second part and set the Content-type
header the appropriate MIME type for the content.
When including metadata in the request body, supply metadata specified
in category parameters in a single XML or JSON container.
For details, see
'Loading Content into the Database' in the REST Application Developer's Guide.
Extracting metadata as properties replaces any existing properties on
the document. Extracting metadata to a document creates an XHTML document
that differs from the input document only by having a xhtml
file name extension. If CPF is installed in the database, the XHTML
document includes a link to the binary document. For details, see
'Extracting Metadata and Text From Binary Documents' in the Search Developer's Guide.
If no permissions are explicitly set, documents you create with the
MarkLogic REST API have a read permission for the rest-reader
role and an update permission for the rest-writer role.
When updating document permissions, the permissions must include at least
one update permission.
For more details, see
'Loading Content into the Database' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -X POST -d@'./my-content' -i \
-H "Content-type: application/xml" \
'http://localhost:8003/v1/documents?extension=xml&directory=/plays/'
==> Create a document from the XML in ./my-content, with a server
generated URI. The URI is rooted at the directory "/plays/" and
has an ".xml" suffix. The generated URI is returned in the Location
response header. MarkLogic Server returns a response similar to
the following:
Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5
HTTP/1.1 201 Document Created
Location: /plays/14993128029398656352.xml
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
POST /v1/documents?uri={db-uri}
|
|
 |
Summary:
Perform a partial update to content or metadata of a document at a
caller-specified URI. This operation is equivalent to
PATCH /v1/documents.
|
Parameters:
uri
:
The URI of the document whose content or metadata is being updated.
Required.
|
category*
:
The category of data to insert or update. Category may be specified
multiple times to insert or replace any combination of content and
metadata. Valid categories: content (default),
metadata, collections, permissions, properties, and
quality. Use metadata to update all metadata.
See the Usage notes below.
|
format?
:
The content type of the metadata in the request body. Specifying a format
overrides the Content-Type request header value. For details, see the
Usage Notes and
'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.
|
|
Request Headers:
Content-Type?:
The MIME type of the data in the request body. See the usage notes
for details on special handling for XML, JSON, and binary content.
|
If-Match?:
Specifies a document version identifier that must match the current
version of the target document for the update to succeed. If the current
version of the document does not match, a 412 (Precondition Failed) status
is returned. A value of 0 indicates the document must not already exist
in the database. Ignored unless optimistic locking is enabled; for
details see
'Using Optimistic Locking to Update Documents' in the REST Application Developer's Guide.
|
X-HTTP-Method-Override:
This header signals that this request is a partial update to document
content or metadata. You must include this header and it must have
a value of PATCH.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server responds with 201 (Document Created) or
204 (Updated or Unchanged).
|
Usage Notes:
Use this form of POST /v1/documents to update a portion
of the content and/or metadata for an existing document at a
caller-supplied URI. For all other document and metadata creation and
update operations, use PUT /v1/documents or one of the
other forms of POST /v1/documents.
To perform a partial update of content and/or metadata, specify the
document URI using the uri parameter, set the
category parameter to reflect the content and/or metadata
to be modified, and set the request header
X-HTTP-Method-Override to PATCH. The
request body must be a JSON or XML patch specification. For details, see
'Partially Updating Document Content or Metadata' in the REST Application Developer's Guide.
You can also use a PATCH request to apply a partial update. For details,
see PATCH /v1/documents. The functionality and request
body contents are the same.
You can only apply partial updates of content to XML and JSON
documents. You can apply partial updates of metadata to any document type.
For more details, see
'Loading Content into the Database' in the REST Application Developer's Guide.
|
Example:
$ cat ./my-patch.xml
<rapi:patch xmlns:rapi="http://marklogic.com/rest-api"
xmlns:my-ns="http://marklogic.com/examples">
<rapi:insert context="/my-ns:parent" position="last-child">
<my-ns:child>inserted</my-ns:child>
</rapi:insert>
</rapi:patch>
curl --anyauth --user user:password -X POST -d@'./my-patch.xml' -i \
-H "Content-type: application/xml" -H "X-HTTP-Method-Override: PATCH" \
'http://localhost:8003/v1/documents?uri=/doc/example.xml'
==> Perform a partial update on the document with URI /doc/example.xml.
A <child/> element is added as the last child of the node with
the XPath /my-ns:parent. MarkLogic Server responds with headers
similar to the following:
Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
Example:
$ cat ./my-patch.json
{ "patch": [
{ "insert": {
"context": "$.parent",
"position": "last-child",
"content": { "child": "inserted" }
}}
] }
curl --anyauth --user user:password -X POST -d@'./my-patch.json' -i \
-H "Content-type: application/json" -H "X-HTTP-Method-Override: PATCH" \
'http://localhost:8003/v1/documents?uri=/doc/example.json'
==> Perform a partial update on the document with URI /doc/example.json.
A key-value pair with key 'child' is added as the last child of the
top level 'parent' key. MarkLogic Server responds with headers
similar to the following:
Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
DELETE /v1/ext/{directories}
|
|
 |
Summary:
Delete the assets in /ext/{directories} in the modules
database associated with the REST API instance.
|
Required Privilege:
This operation requires the rest-admin role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-admin
http://marklogic.com/xdmp/privileges/rest-reader
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
Whether or not any assets exist under the given directory, MarkLogic Server
returns status code 204 (Deleted).
|
Usage Notes:
{directories} must be one or more database directory path
steps. For example: /your/domain/. Use the same directory path
as was used to install the asset with
GET /v1/ext/{directories}/{asset}.
For more details, see
'Managing Dependent Libraries and Other Assets' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -i -X DELETE \
'http://localhost:8003/v1/ext/my/example/'
==> All assets installed in /ext/my/example/ in the modules database are
deleted. MarkLogic Server responds with output similar to the following:
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
GET /v1/ext/{directories}
|
|
 |
Summary:
Retrieve a list of assets installed in the modules database
associated with a REST API instance, such as a dependent library of
an extension or transformation.
|
Parameters:
format?
:
The expected content type of the response, either xml or
json. Overrides the Accept header.
|
|
Request Headers:
Accept*:
The expected MIME type of the response, either
application/xml, application/json, or
text/xml. Ignored if the format parameter
is present.
|
|
Response Headers:
Content-type?:
The MIME type of the data in the response body, either
application/xml or text/plain (JSON).
|
|
Required Privilege:
This operation requires the rest-admin role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-admin
http://marklogic.com/xdmp/privileges/rest-reader
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
Upon successful completion, MarkLogic Server responds with status code
200 (OK) and returns a list of installed assets in XML or JSON. See the
examples, below. If no assets are found with the given directory path,
MarkLogic Server returns status code 404 (Not Found).
|
Usage Notes:
{directories} must be one or more database directory path
steps. For example: /your/domain/. Use the same directory path
as was used to install the asset with
GET /v1/ext/{directories}/{asset}.
The directory path must end with "/".
For more details, see
'Managing Dependent Libraries and Other Assets' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -i -H "Accept: application/xml" -X GET \
'http://localhost:8003/v1/ext'
==> A list of all assets installed in the modules database under /ext/.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 119
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:assets xmlns:rapi="http://marklogic.com/rest-api">
<rapi:asset>/ext/replace/my-lib.xqy</rapi:asset>
</rapi:assets>
|
Example:
$ curl --anyauth --user user:password -i -H "Accept: application/json" -X GET \
'http://localhost:8003/v1/ext'
==> A list of all assets installed in the modules database under /ext/,
as JSON. MarkLogic Server responds with output similar to the following:
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 48
Connection: Keep-Alive
Keep-Alive: timeout=5
{"assets":[
{"asset":"/ext/replace/my-lib.xqy"}
]}
|
Example:
curl --anyauth --user user:password -i -H "Accept: application/xml" -X GET \
'http://localhost:8003/v1/ext/example/'
==> A list of all assets installed in the /ext/example/ directory of the
modules database. MarkLogic Server responds with output similar to the
following:
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 119
Connection: Keep-Alive
Keep-Alive: timeout=5
<rapi:assets xmlns:rapi="http://marklogic.com/rest-api">
<rapi:asset>/ext/example/my-lib.xqy</rapi:asset>
</rapi:assets>
|
|
|
|
DELETE /v1/ext/{directories}/{asset}
|
|
 |
Summary:
Remove the asset with document URI /ext/{directories}/{asset}
from the modules database associated with this REST API instance.
|
Required Privilege:
This operation requires the rest-admin role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-admin
http://marklogic.com/xdmp/privileges/rest-reader
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
MarkLogic Server responds with 204 (Deleted), whether or not there is
an asset in the modules database with the specified document URI.
|
Usage Notes:
/ext/{directories}/{asset} must be the document URI of
the asset in the modules database, where {directories} is
one or more database directory path steps, separated by "/", and
{asset} is the asset document. See the example below.
To remove all assets in a database directory with a single request,
use DELETE /v1/ext/{directories}.
For more details, see
'Managing Dependent Libraries and Other Assets' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X DELETE -i \
'http://localhost:8003/v1/ext/my/example/my-lib.xqy'
==> MarkLogic Server deletes the XQuery library module with the document
URI /ext/my/example/my-lib.xqy from the modules database associated
with this REST API instance and returns a response similar to the
following:
HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
GET /v1/ext/{directories}/{asset}
|
|
 |
Summary:
Retrieve an asset installed in the modules database
associated with a REST API instance, such as a dependent library of a
module implementing an extension or a transformation. The asset should
have the database URI /ext/{directories}/{asset}.
|
Request Headers:
Accept?:
The expected MIME type of the data in the response body. You are
responsible for selecting the correct type for the asset being
retrieved. Content negotiation is not supported.
|
|
Response Headers:
Content-type?:
The MIME type of the data in the response body, derived from the
Accept header.
|
|
Required Privilege:
This operation requires the rest-admin role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-admin
http://marklogic.com/xdmp/privileges/rest-reader
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
Upon successful completion, MarkLogic Server responds with status code
200 (OK) and returns the asset in the response body. If
no asset is found with the specified URI, MarkLogic Server returns status
code 404 (Not Found).
|
Usage Notes:
/ext/{directories}/{asset} should be the document URI of the
asset in the modules database, where {directories} is one
or more database directory path steps, separated by "/", and
{asset} is the asset document. For example, if the asset
is inserted into the database with the document URI
/ext/your/domain/your-module.xqy then the request URL is
of the form http://localhost:port/v1/ext/your/domain/your-module.xqy.
The response returns the asset with a Content-type corresponding to
the MIME type in the Accept header.
No content negotiation is supported. For example, if you specify
application/xml in the Accept header, but retrieve a
binary JPG document, then the response will have Content-type
application/xml, even though the body actually contains JPG.
For more details, see
'Managing Dependent Libraries and Other Assets' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -i -X GET \
'http://localhost:8003/v1/ext/my/example/my-lib.xqy'
==> MarkLogic Server returns the XQuery library module in the modules
database with the document URI /ext/my/example/my-lib.xqy. The response
headers are similar to the following:
HTTP/1.1 200 OK
Content-type: application/xml
Server: MarkLogic
Content-Length: 633
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
PUT /v1/ext/{directories}/{asset}
|
|
 |
Summary:
Install an asset such as a dependent library of an extension module
in the modules database associated with this REST API instance.
The asset is installed with the database URI
/ext/{directories}/{asset}.
|
Parameters:
format?
:
Specify the asset document type for MarkLogic Server. Allowed values:
xml, text, binary. If this
parameter is not given, the document type is determined based on
Content-type request header or the MIME type mapping defined for
for the URI extension. For details, see
'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
|
perm:{role}*
:
Give the asset the specified permissions, in addition to the default
rest-admin permissions that all assets have. Any existing
permissions beyond the default are replaced. Example:
perm:my-role=execute. Valid capability values:
read, update, execute.
|
|
Request Headers:
Content-type?:
The MIME type of the data in the request body.
|
|
Required Privilege:
This operation requires the rest-admin role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-admin
http://marklogic.com/xdmp/privileges/rest-reader
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
Upon successful completion, MarkLogic Server responds with status code
201 (Created) or 204 (Updated).
|
Usage Notes:
/ext/{directories}/{asset} will be the document URI of the
asset in the modules database, where {directories} is one
or more database directory path steps, separated by "/", and
{asset} is the asset document. See the example below.
The input document type is based on the MarkLogic Server MIME type
mapping for the asset URI extension or on Content-type header.
For details, see the discussion of document handling in
'Controlling Input and Output Content Type' in the REST Application Developer's Guide.
For more details, see
'Managing Dependent Libraries and Other Assets' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X PUT -i -d @./my-lib.xqy \
-H "Content-type: application/xquery" \
'http://localhost:8003/v1/ext/my/example/my-lib.xqy?perm:my-users=execute'
==> MarkLogic Server installs the XQuery library module that is in
the request body into the Modules database with the document
URI /ext/my/example/my-lib.xqy and returns a response similar
to the following. The module is executable by users with the
'my-users' role.
HTTP/1.1 201 Created
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
|
 |
Summary:
Remove triples in a named graph or the default graph.
|
Parameters:
graph
:
The name of the graph to modify. You cannot use this parameter
in conjunction with the default parameter.
|
default
:
Indicates the request should modify the default graph. You cannot
use this parameter in conjunction with the graph parameter.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
MarkLogic Server returns status 204 (Updated).
|
Usage Notes:
This interface implements the DELETE method of the W3C Graph Store HTTP
Protocol; for details, see
http://www.w3.org/TR/sparql11-http-rdf-update/. This implementation differs from the
standard in that it returns status 204 even if the target graph does
not exist.
This operation only updates triples documents. That is, documents
with a sem:triples root element, such as those created
using PUT or POST on /graphs. It has no effect on triples
embedded in regular XML documents. If you delete a graph that contains
both embedded triples and triples stored in triples documents, the
embedded triples, and therefore the graph, remain even after this
operation returns success.
For details, see
'Deleting Triples' in the Semantics Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -i -X DELETE \
http://localhost:8003/v1/graphs?graph=/my/named/graph
HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
|
 |
Summary:
Retrieve a graph or a list of available graph URIs.
|
Parameters:
graph?
:
The URI of the named graph to retrieve. You cannot use this parameter
with the default parameter.
|
default?
:
Indicates the request should return the default graph. This parameter
accepts no value. You cannot use this parameter with the
graph parameter.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. When retrieving a list
of available graphs (no request parameters), you can specify
text/plain, text/html, or
text/uri-list (default). When retrieving a named
graph or the default graph, you can specify any of the MIME
types listed in
'Supported RDF Triple Serializations' in the Semantics Developer's Guide.
|
|
Response Headers:
Content-Type:
The MIME type of the data in the response body, corresponding to
the MIME type in the Accept header.
|
|
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 status 200 (OK). If a named graph
or the default graph is requested, the response body contains the graph
data. If neither the graph nor default request
parameters are present, the response body contains a list of available
graph URIs. If you request triples in an unsupported format, MarkLogic
Server returns status 406 (Not Acceptable).
|
Usage Notes:
This interface implements the GET method of the W3C Graph Store HTTP
Protocol; for details, see
http://www.w3.org/TR/sparql11-http-rdf-update/.
The collection lexicon must be enabled on the database before using
the REST graph store interfaces or using the GRAPH '?g' construct in
SPARQL queries. You can enable the collection lexicon from the Admin
Interface.
|
Example:
$ curl --anyauth --user user:password -i -X GET \
'http://localhost:8003/v1/graphs'
==> Retrieve a list of graphs in the database. Since no Accept
is given, results are returned as text/uri-list. MarkLogic Server
responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: text/uri-list; charset=UTF-8
Server: MarkLogic
Content-Length: 61
Connection: Keep-Alive
Keep-Alive: timeout=5
/my/named/graph
http://marklogic.com/semantics#default-graph
If you request output as text/html, MarkLogic Server returns
data in the response body similar to the following:
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Graphs</title>
</head>
<body>
<ul>
<li>/my/named/graph</li>
<li>http://marklogic.com/semantics#default-graph</li>
</ul>
</body>
</html>
|
Example:
$ curl --anyauth --user user:password -i -X GET -H "Accept: text/turtle"
'http://localhost:8003/v1/graphs?graph=/my/named/graph'
==> Retrieve the graph with URI /my/named/graph, in Turtle format.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: text/turtle; charset=UTF-8
Server: MarkLogic
Content-Length: 6680
Connection: Keep-Alive
Keep-Alive: timeout=5
@prefix xs: <http://www.w3.org/2001/XMLSchema#> .
<http://dbpedia.org/resource/Abraham_Lincoln> <http://dbpedia.org/ontology/birthDate> "1809-02-12"^^xs:date .
<http://dbpedia.org/resource/Alan_Turing> <http://dbpedia.org/ontology/birthDate> "1912-06-23"^^xs:date .
|
|
|
|
|
 |
Summary:
Returns the same headers as an equivalent GET on the
/graphs service.
|
Parameters:
graph?
:
Specify the URI of a named graph. You cannot use this
parameter with the default parameter.
|
default?
:
Indicates the request should act on the default graph. This parameter
accepts no value. You cannot use this parameter with the
graph parameter.
|
|
Request Headers:
Accept*:
The expected MIME type of the response.
|
|
Response Headers:
Content-Type:
The MIME type of the data that would be returned by a GET 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 status 200 (OK) and the same headers
that are returned by an equivalent GET on the /documents service.
|
Usage Notes:
Use this method to determine what headers an equivalent GET will return.
This interface implements the HEAD method of the W3C Graph Store HTTP
Protocol; for details, see
http://www.w3.org/TR/sparql11-http-rdf-update/.
The collection lexicon must be enabled on the database before using
the REST graph store interfaces or using the GRAPH '?g' construct in
SPARQL queries. You can enable the collection lexicon from the Admin
Interface.
|
Example:
$ curl --anyauth --user user:password -i -X HEAD -H "Accept: text/turtle" \
http://localhost:8003/v1/graphs?graph=/my/named/graph
HTTP/1.1 200 OK
Content-type: text/turtle; charset=UTF-8
Server: MarkLogic
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
|
 |
Summary:
Merge triples into a named graph or the default graph.
|
Parameters:
graph?
:
The URI of the named graph to modify. You cannot use this parameter
with the default parameter.
|
default?
:
Indicates the request should modify the default graph. This parameter
accepts no value. You cannot use this parameter with the
graph parameter.
|
repair
:
If set to true, triples in the request body that cannot be parsed
are skipped, and parsable triples are inserted. If set to false,
triples in the request body that cannot be parsed cause all the data
in the request to be rejected. Default: false.
|
|
Request Headers:
Content-Type:
The MIME type of the data in the request body. For details, see
'Supported RDF Triple Serializations' in the Semantics Developer's Guide.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
Upon success, MarkLogic Server returns status 201 (Created) or status
204 (Updated). If there are errors in the payload, the response body contains
further information about the errors. If the request body is in an
unsupported format, MarkLogic Server returns status 415 (Unsupported
Media Type).
|
Usage Notes:
Supplying an empty graph is a no-op.
This interface implements the POST method of the W3C Graph Store HTTP
Protocol; for details, see
http://www.w3.org/TR/sparql11-http-rdf-update/.
Additional capabilities are available through the
XQuery API and the mlcp command line tool. For details, see
'Updating Triples' in the Semantics Developer's Guide.
The collection lexicon must be enabled on the database before using
the REST graph store interfaces or using the GRAPH '?g' construct in
SPARQL queries. You can enable the collection lexicon from the Admin
Interface.
|
Example:
NOTE: Be sure to use --data-binary rather than -d if extracting
the request body from a file with curl, as shown below.
$ curl --anyauth --user user:password -i -X POST \
--data-binary @./example.nq -H "Content-type: application/n-quads" \
http://localhost:8003/v1/graphs?default
==> The N-Quad data in example.nq is merged into the default graph.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
Example:
NOTE: Be sure to use --data-binary rather than -d if extracting
the request body from a file with curl, as shown below.
$ curl --anyauth --user user:password -i -X POST \
--data-binary @./example.ttl -H "Content-type: text/turtle" \
http://localhost:8003/v1/graphs?graph=/my/named/graph
==> The Turtle data in example.ttl is merged into the named graph
with the URI /my/named/graph. MarkLogic Server responds with
output similar to the following:
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
|
 |
Summary:
Create or replace triples in a named graph or the default graph.
|
Parameters:
graph?
:
The URI of the named graph to modify. You cannot use this parameter
with the default parameter.
|
default?
:
Indicates the request should modify the default graph. This parameter
accepts no value. You cannot use this parameter with the
graph parameter.
|
repair
:
If set to true, triples in the request body that cannot be parsed
are skipped, and parsable triples are inserted. If set to false,
triples in the request body that cannot be parsed cause all the data
in the request to be rejected. Default: false.
|
|
Request Headers:
Content-Type:
The MIME type of the data in the request body. For details, see
'Supported RDF Triple Serializations' in the Semantics Developer's Guide.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-writer
The collection lexicon must be enabled on the database before using
the REST graph store interfaces or using the GRAPH '?g' construct in
SPARQL queries. You can enable the collection lexicon from the Admin
Interface.
|
Response:
Upon success, MarkLogic Server returns status 201 (Created) or status
200 (OK). If there are errors in the payload, the response body contains
further information about the errors. If the request body is in an
unsupported format, MarkLogic Server returns status 415 (Unsupported
Media Type).
|
Usage Notes:
A PUT request is functionally equivalent to a DELETE followed by a POST.
Supplying an empty graph is equivalent to deleting the graph.
This interface implements the PUT method of the W3C Graph Store HTTP
Protocol; for details, see
http://www.w3.org/TR/sparql11-http-rdf-update/.
Additional capabilities for loading triples are available through the
XQuery API and the mlcp command line tool. For details, see
'Loading Triples' in the Semantics Developer's Guide.
Files submitted to this endpoint are limited in size based on the
format of the documents, which is 512MB for XML files (for
example, rdf .rdf files) and 64MB for text documents (for example,
turtle .ttl files).
|
Example:
NOTE: Be sure to use --data-binary rather than -d if extracting
the request body from a file with curl, as shown below.
$ curl --anyauth --user user:password -i -X PUT --data-binary @./example.ttl \
-H "Content-type: text/turtle" \
http://localhost:8003/v1/graphs?default
==> The Turtle data in example.ttl is created as the default graph.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
|
|
|
|
|
 |
Summary:
Used to perform a SPARQL query on the database. The result output format will depend on the type of SPARQL query in the url-encoded query and the parameters used for the Accept Header Type in the REST request. There are four types of SPARQL queries (SELECT, CONSTRUCT, DESCRIBE and ASK), each with different result formats. The Accept Header Type in the REST request sets the expected MIME type for the response output. For more details, see 'Querying Triples with REST API' in the Semantics Developer's Guide.
|
Parameters:
query
:
A URL-encoded SPARQL query.
|
default-graph-uri*
:
Specify the URI of a graph to use as the default graph.
|
named-graph-uri*
:
Specify the URI of a named graph to include in the query.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. For supported type information, see
'Response Output Formats' in the Semantics Developer's Guide.
|
|
Response Headers:
Content-type:
The MIME type of the data in the response body. The MIME type depends
on the type of information generated by the query. For details, see
'Response Output Formats' in the Semantics Developer's Guide.
|
|
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 status 200 (OK) and the
response body contains the query result. If you request results in
an unsupported format, MarkLogic Server returns status 406
(Not Acceptable).
|
Usage Notes:
This interface implements the GET method of the W3C SPARQL Protocol;
for details, see http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321.
You can specify the RDF Dataset against which to execute the query
using the named-graph-uri and
default-graph-uri request parameters, or within the query.
If the dataset is specified in both the request parameters and the
query, the dataset defined by the request parameters
is used. If neither is specified, all graphs are queried.
The collection lexicon must be enabled on the database before using
the REST graph store interfaces or using the GRAPH '?g' construct in
SPARQL queries. You can enable the collection lexicon from the Admin
Interface.
For more details, see
'Querying Triples with REST API' in the Semantics Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -i -X GET \
-H "Accept: application/sparql-results+json" \
http://localhost:8003/v1/graphs/sparql?query=your-urlencoded-query
==> Run the SPARQL query passed as the URL encoded value of the
query request parameter. MarkLogic Server responds with output
similar to the following:
HTTP/1.1 200 OK
Content-type: application/sparql-results+json
Server: MarkLogic
Content-Length: 126
Connection: Keep-Alive
Keep-Alive: timeout=5
{
"head": {
"vars": [ "s" ]
},
"results": {
"bindings": [ {
"s": {
"type": "uri",
"value": "http://dbpedia.org/resource/Alfonso_Arau"
}
} ]
}
}
If you set the Accept header to application/sparql-results+xml,
MarkLogic Server returns data similar to the following:
<sparql xmlns="http://www.w3.org/2005/sparql-results#">
<head>
<variable name="s"/>
</head>
<results>
<result>
<binding name="s">
<uri>http://dbpedia.org/resource/Alfonso_Arau</uri>
</binding>
</result>
</results>
</sparql>
|
|
|
|
|
 |
Summary:
Used to perform a SPARQL query on one or more graphs. The result output format will depend on the type of SPARQL query and the parameters used for the Accept Header Type in the REST request. There are four types of SPARQL queries (SELECT, CONSTRUCT, DESCRIBE and ASK), each with different result formats. The Accept Header Type in the REST request sets the expected MIME type for the response output. For more details, see 'Querying Triples with REST API' in the Semantics Developer's Guide.
|
Parameters:
default-graph-uri*
:
Specify the default graph URI.
|
named-graph-uri*
:
Specify the URI of a named graph to include in the query.
|
query
:
A URL-encoded SPARQL query. You should only use this parameter when
you put request parameters in the request body and use
application/x-www-form-urlencoded as the request
content type.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. For supported type information, see
'Response Output Formats' in the Semantics Developer's Guide.
|
Content-type:
The MIME type of the query in the request body. Allowed values:
application/x-www-form-urlencoded,
application/sparql-query.
|
|
Response Headers:
Content-type:
The MIME type of the data in the response body. The MIME type depends
on the type of information generated by the query. For details, see
'Response Output Formats' in the Semantics Developer's Guide.
|
|
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 status 200 (OK) and the
response body contains the query result. If you request results in
an unsupported format, MarkLogic Server returns status 406
(Not Acceptable).
|
Usage Notes:
This interface implements the POST method of the W3C SPARQL Protocol;
for details, see http://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/.
If you use application/x-www-form-urlencoded for the
request body content type, put all request parameters in the body,
with their values URL-encoded. Separate parameters with an
ampersand. Specify your SPARQL query using the query
request parameter.
If you use application/sparql-query
for the request body content type, the body must contain only an
unencoded SPARQL query, and you cannot specify a query
request parameter.
You can specify the RDF Dataset against which to execute the query
using the named-graph-uri and
default-graph-uri request parameters, or within the query.
If the dataset is specified in both the request parameters and the
query, the dataset defined by the request parameters
is used. If neither is specified, all graphs are queried.
The collection lexicon must be enabled on the database before using
the REST graph store interfaces or using the GRAPH '?g' construct in
SPARQL queries. You can enable the collection lexicon from the Admin
Interface.
For more details, see
'Querying Triples with REST API' in the Semantics Developer's Guide.
|
Example:
NOTE: Be sure to use --data-binary rather than -d if extracting
the request body from a file with curl, as shown below.
$ cat mexico.sparql
SELECT ?s WHERE {
?s
<http://dbpedia.org/ontology/birthPlace>
<http://dbpedia.org/resource/Mexico>
}
LIMIT 5
$ curl --anyauth --user user:password -i -X POST \
--data-binary @./mexico.sparql \
-H "Content-type: application/sparql-query" \
-H "Accept: application/sparql-results+xml" \
http://localhost:8003/v1/graphs/sparql
==> Run a SPARQL query, placing the unencoded query in the POST body.
MarkLogic Server responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: application/sparql-results+xml
Server: MarkLogic
Content-Length: 213
Connection: Keep-Alive
Keep-Alive: timeout=5
<sparql xmlns="http://www.w3.org/2005/sparql-results#">
<head>
<variable name="s"/>
</head>
<results>
<result>
<binding name="s">
<uri>http://dbpedia.org/resource/Aaron_Herrera</uri>
</binding>
</result>
<result>
<binding name="s">
<uri><http://dbpedia.org/resource/Abel_Ramirez></uri>
</binding>
</result>
<result>
<binding name="s">
<uri>http://dbpedia.org/resource/Abel_Salazar_(actor)</uri>
</binding>
</result>
<result>
<binding name="s">
<uri>http://dbpedia.org/resource/Abigail_Elizalde</uri>
</binding>
</result>
<result>
<binding name="s">
<uri>http://dbpedia.org/resource/Abismo_Negro</uri>
</binding>
</result>
</results>
</sparql>
The following is the equivalent results returned as
application/sparql-results+json:
{
"head":{
"vars":["s"]
},
"results":{
"bindings":[{
"s":{
"type":"uri",
"value":"http://dbpedia.org/resource/Aaron_Herrera"
}},
{
"s":{
"type":"uri",
"value":"<http://dbpedia.org/resource/Abel_Ramirez>"
}},
{
"s":{
"type":"uri",
"value":"http://dbpedia.org/resource/Abel_Salazar_(actor)"
}},
{
"s":{
"type":"uri", "value":"http://dbpedia.org/resource/Abigail_Elizalde"
}},
{
"s":{
"type":"uri",
"value":"http://dbpedia.org/resource/Abismo_Negro"
}}
]
}
}
|
Example:
$ curl --anyauth --user user:password -i -X POST \
--data "query=SELECT%20%3Fs%20WHERE%20%7B%0A%20 \
%20%3Fs%20%0A%20%20%3Chttp%3A%2F%2Fdbpedia.org \
%2Fontology%2FbirthPlace%3E%20%0A%20%20%3Chttp \
%3A%2F%2Fdbpedia.org%2Fresource%2FMexico%3E%20 \
%0A%7D" -H "Content-type:application/x-www-form-urlencoded" \
-H "Accept:application/sparql-results+xml" \
http://localhost:8004/v1/graphs/sparql
==> Run a SPARQL query, passing the URL-encoded query as form data.
MarkLogic Server responds with triples similar to the following:
HTTP/1.1 200 OK
Content-type: application/sparql-results+xml
Server: MarkLogic
Content-Length: 241432
Connection: Keep-Alive
Keep-Alive: timeout=5
<sparql xmlns="http://www.w3.org/2005/sparql-results#"><head><variable name="s"/>
</head><results>
<result><binding name="s"><uri>http://dbpedia.org/resource/Aaron_Herrera
</uri></binding></result>
<result><binding name="s"><uri><http://dbpedia.org/resource/Abel_Ramirez></uri>
</binding></result>
<result><binding name="s"><uri>http://dbpedia.org/resource/Abel_Salazar_(actor)</uri>
</binding></result>
<result><binding name="s"><uri>http://dbpedia.org/resource/Abigail_Elizalde</uri>
</binding></result>
<result><binding name="s"><uri>http://dbpedia.org/resource/Abismo_Negro</uri>
</binding></result>
</sparql>
|
|
|
|
|
 |
Summary:
Retrieve a list of all graph nodes in the database, or a specified
set of nodes.
|
Parameters:
iri*
:
IRIs about which to return information.
|
|
Request Headers:
Accept*:
The expected MIME type of the response. With no parameters, the
only supported MIME type is text/html. When the
iri parameter is used, you can specify any of
the MIME types listed in
'Supported RDF Triple Serializations' in the Semantics Developer's Guide.
|
|
Response Headers:
Content-type:
The MIME type of the data in the response body. The MIME type
corresponds to the type requested by the Accept header.
|
|
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 status 200 (OK) and the
response body contains the requested data. If you request results in
an unsupported format, MarkLogic Server returns status 406
(Not Acceptable). If a specified IRI does not exist, MarkLogic server
returns status 404 (Not Found).
|
Usage Notes:
With no request parameters, this method returns a list of nodes in
the database, both blank and named. If you specify one or more
IRI's using iri, information is returned about just
those nodes. The information is in CBD triple format.
This operation returns a maximum of 10,000 items.
The collection lexicon must be enabled on the database before using
the REST graph store interfaces or using the GRAPH '?g' construct in
SPARQL queries. You can enable the collection lexicon from the Admin
Interface.
|
Example:
$ curl --anyauth --user admin:adm1n -i -X GET -H "Accept: text/html" \
http://localhost:8003/v1/graphs/things
==> The list of all graph nodes is returned as XML. MarkLogic Server
responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: text/html; charset=UTF-8
Server: MarkLogic
Content-Length: 1071
Connection: Keep-Alive
Keep-Alive: timeout=5
<html xmlns="http://www.w3.org/1999/xhtml">
<title>Subjects</title>
<body>
<h2>Subjects</h2>
<p>
<a href="/v1/graphs/things?iri=http%3a//dbpedia.org/resource/Abraham_Lincoln"><http://dbpedia.org/resource/Abraham_Lincoln></a>
</p>
<p>
<a href="/v1/graphs/things?iri=http%3a//dbpedia.org/resource/Alan_Turing"><http://dbpedia.org/resource/Alan_Turing></a>
</p>
<p>
<a href="/v1/graphs/things?iri=http%3a//dbpedia.org/resource/Aleister_Crowley"><http://dbpedia.org/resource/Aleister_Crowley></a>
</p>
<p>
<a href="/v1/graphs/things?iri=http%3a//dbpedia.org/resource/Alexander_Mackenzie"><http://dbpedia.org/resource/Alexander_Mackenzie></a>
</p>
<p>
<a href="/v1/graphs/things?iri=http%3a//dbpedia.org/resource/Alfonso_Arau"><http://dbpedia.org/resource/Alfonso_Arau></a>
</p>
<p>
<a href="/v1/graphs/things?iri=http%3a//dbpedia.org/resource/Alfred_Lawson"><http://dbpedia.org/resource/Alfred_Lawson></a>
</p>
<p>
<a href="/v1/graphs/things?iri=http%3a//dbpedia.org/resource/Aristotle"><http://dbpedia.org/resource/Aristotle></a>
</p>
</body>
</html>
|
Example:
$ curl --anyauth --user user:password -i -X GET -H "Accept: text/turtle" \
http://localhost:8003/v1/graphs/things?iri=http://dbpedia.org/resource/Aleister_Crowley
==> Retrieve the nodes selected by the IRI
http://dbpedia.org/resources/Aleister_Crowley in Turtle format.
MarkLogicServer responds with output similar to the following:
HTTP/1.1 200 OK
Content-type: text/turtle; charset=UTF-8
Server: MarkLogic
Content-Length: 1095
Connection: Keep-Alive
Keep-Alive: timeout=5
@prefix xs: <http://www.w3.org/2001/XMLSchema#> .
<http://dbpedia.org/resource/Aleister_Crowley> <http://dbpedia.org/ontology/deathPlace> <http://dbpedia.org/resource/Hastings> .
<http://dbpedia.org/resource/Aleister_Crowley> <http://dbpedia.org/ontology/birthPlace> <http://dbpedia.org/resource/Royal_Leamington_Spa> .
<http://dbpedia.org/resource/Aleister_Crowley> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .
<http://dbpedia.org/resource/Aleister_Crowley> <http://xmlns.com/foaf/0.1/givenName> "Aleister" .
<http://dbpedia.org/resource/Aleister_Crowley> <http://xmlns.com/foaf/0.1/name> "Aleister Crowley" .
<http://dbpedia.org/resource/Aleister_Crowley> <http://xmlns.com/foaf/0.1/surname> "Crowley" .
<http://dbpedia.org/resource/Aleister_Crowley> <http://purl.org/dc/elements/1.1/description> "poet, mountaineer, occultist" .
<http://dbpedia.org/resource/Aleister_Crowley> <http://dbpedia.org/ontology/birthDate> "1875-10-12"^^xs:date .
<http://dbpedia.org/resource/Aleister_Crowley> <http://dbpedia.org/ontology/deathDate> "1947-12-01"^^xs:date .
|
|
|
|
|
 |
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--
|
|
|
|
DELETE /v1/resources/{name}
|
|
 |
Summary:
Send a DELETE request to the named resource service extension.
|
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.
|
rs:{name}*
:
A service-specific parameter. The name and expected value of the
parameter is service dependent. For example, if the GET method of a
service extension expects a boolean valued parameter named "reset",
then include the URI parameter "rs:reset=true" to set it to true.
|
|
Request Headers:
Accept*:
The accepted response MIME type, if any. The accepted values depends on
service extension implementation.
|
Content-type?:
The type of the request body. The accepted values are service
dependent.
|
|
Response Headers:
Content-type?:
The type of the response body. If the POST method returns multiple
documents, the response is multipart/mixed.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-reader
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
The status and response contents are extension-specific. If the service
does not exists, or if the service exists but does not support this
method, MarkLogic Server returns status 400 (Bad Request).
|
Usage Notes:
This operation invokes the delete function of a resource
service extension previously installed using the
PUT /v1/config/resources/{name}. You can use
GET /v1/config/resources to discover the names and
interfaces of installed extensions. For details, see
'Extending the REST API' in the REST Application Developer's Guide.
All request parameters intended for the underlying XQuery extension
function must be prefixed with rs: to distinguish them from
implementation independent request parameters like txid.
For example, to pass a resource-specific parameter named arg1,
include a request parameter named rs:arg1.
For more details, see
'Using a Resource Service Extension' in the REST Application Developer's Guide.
|
Example:
|
|
|
|
|
 |
Summary:
Make a GET request to the named resource service extension.
|
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.
|
rs:{name}*
:
A service-specific parameter. The name and expected value of the
parameter is service dependent. For example, if the GET method of a
service extension expects a boolean valued parameter named "reset",
then include the URI parameter "rs:reset=true" to set it to true.
|
|
Request Headers:
Accept:
The accepted response MIME type, if any. The accepted values depends on
service extension implementation.
|
|
Response Headers:
Content-type:
The type of the response body. If the GET method returns multiple
documents, the response is multipart/mixed.
|
|
Required Privilege:
This operation requires the rest-reader role, or the
following privilege:
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
The status and response contents are extension-specific.
|
Usage Notes:
This operation invokes the get function of a resource
service extension previously installed using the
PUT /v1/config/resources/{name}. You can use
GET /v1/config/resources to discover the names and
interfaces of installed extensions. For details, see
'Extending the REST API' in the REST Application Developer's Guide.
All request parameters intended for the underlying XQuery extension
function must be prefixed with rs: to distinguish them from
implementation independent request parameters like txid.
For example, to pass a resource-specific parameter named arg1,
include a request parameter named rs:arg1.
For more details, see
'Using a Resource Service Extension' in the REST Application Developer's Guide.
|
Example:
|
|
|
|
POST /v1/resources/{name}
|
|
 |
Summary:
Applies an extension-specific operation to a resource implemented by
a resource service extension.
|
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.
|
rs:{name}*
:
A service-specific parameter. The name and expected value of the
parameter is service dependent. For example, if the GET method of a
service extension expects a boolean valued parameter named "reset",
then include the URI parameter "rs:reset=true" to set it to true.
|
|
Request Headers:
Accept*:
The accepted response MIME type, if any. The accepted values depends on
service extension implementation.
|
Content-type?:
The type of the request body. The accepted values are service
dependent.
|
|
Response Headers:
Content-type?:
The type of the response body. If the POST method returns multiple
documents, the response is multipart/mixed.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-reader
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
The status and response contents are extension-specific. If the service
does not exists, or if the service exists but does not support this
method, MarkLogic Server returns status 400 (Bad Request).
|
Usage Notes:
This operation invokes the post function of a resource
service extension previously installed using the
PUT /v1/config/resources/{name}. You can use
GET /v1/config/resources to discover the names and
interfaces of installed extensions. For details, see
'Extending the REST API' in the REST Application Developer's Guide.
All request parameters intended for the underlying XQuery extension
function must be prefixed with rs: to distinguish them from
implementation independent request parameters like txid.
For example, to pass a resource-specific parameter named arg1,
include a request parameter named rs:arg1.
For more details, see
'Using a Resource Service Extension' in the REST Application Developer's Guide.
|
Example:
|
|
|
|
|
 |
Summary:
Perform the PUT operation associated with a resource service extension.
|
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.
|
rs:{name}*
:
A service-specific parameter. The name and expected value of the
parameter is service dependent. For example, if the GET method of a
service extension expects a boolean valued parameter named "reset",
then include the URI parameter "rs:reset=true" to set it to true.
|
|
Request Headers:
Accept*:
The accepted response MIME type, if any. The accepted values depends on
service extension implementation.
|
Content-type?:
The type of the request body. The accepted values are service
dependent.
|
|
Response Headers:
Content-type?:
The type of the response body. If the PUT method returns multiple
documents, the response is multipart/mixed.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-reader
http://marklogic.com/xdmp/privileges/rest-writer
|
Response:
The status and response contents are extension-specific. If the service
does not exist, or if the service exists but does not support this
method, MarkLogic Server returns status 400 (Bad Request).
|
Usage Notes:
This operation invokes the put function of a resource
service extension previously installed using the
PUT /v1/config/resources/{name}. You can use
GET /v1/config/resources to discover the names and
interfaces of installed extensions. For details, see
'Extending the REST API' in the REST Application Developer's Guide.
All request parameters intended for the underlying XQuery extension
function must be prefixed with rs: to distinguish them from
implementation independent request parameters like txid.
For example, to pass a resource-specific parameter named arg1,
include a request parameter named rs:arg1.
For more details, see
'Using a Resource Service Extension' in the REST Application Developer's Guide.
|
Example:
|
|
|
|
|
 |
Summary:
Retrieve a list of REST API instances, including configuration details.
This request is only available on port 8002.
|
Parameters:
database?
:
Limit the results to services connected to the named database.
|
format?
:
Specifies the type of the response content, as an alternative to
specifying format via the Accept header. Accepted values:
json and xml. If there is no
format parameter, the format must be specified in the Accept header.
|
group?
:
The name of a Group in a MarkLogic Server cluster. If no group is
specified, information is returned for all groups.
|
|
Request Headers:
Accept:
Specifies the MIME type of the response content. The only
supported types are application/json and
application/xml (default). The type can also be specified
through the format parameter.
|
|
Required Privilege:
This operation 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 status 200 OK and configuration
details on all REST API instances, in XML or JSON.
|
Usage Notes:
If no instances are configured, MarkLogic Server returns an empty
<rest-apis> node.
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 details, see
'Retrieving Configuration Information' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -X GET -i http://localhost:8002/v1/rest-apis
==> Information about configured REST services, in XML:
Content-type: text/html; charset=UTF-8
Server: MarkLogic
Content-Length: 1992
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 108
Connection: close
<rapi:rest-apis xmlns:rapi="http://marklogic.com/rest-api">
<rapi:rest-api>
<rapi:name>my-service</rapi:name>
<rapi:group>Default</rapi:group>
<rapi:database>my-database</rapi:database>
<rapi:modules>my-service-modules</rapi:database>
<rapi:port>8003</rapi:port>
</rapi:rest-rapi:api>
</rapi:rest-apis>
|
Example:
curl --anyauth --user user:password -i -X GET -H "Accept: application/json" \
http://localhost:8002/v1/rest-apis
==> Information about configured REST services, in JSON:
HTTP/1.1 200 OK
vnd.marklogic.document-format: json
Content-type: application/json; charset=UTF-8
Server: MarkLogic
Connection: close
{
"rest-apis": [
{
"name": "my-service",
"group": "Default",
"database": "my-database",
"modules": "my-service-modules",
"port": "8003"
}
]
}
|
|
|
|
|
 |
Summary:
Create an instance of the MarkLogic REST API, including an
HTTP app server, required modules, and optionally a content database.
This request is only available on port 8002.
|
Request Headers:
Content-Type:
The MIME type of the service configuration information in the request
body. Accepted types: application/json or
application/xml.
|
|
Required Privilege:
This operation 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 status 201 (Created).
|
Usage Notes:
The POST body must contain App Server configuration information.
The following configuration settings can be specified:
name, group, port, database. Only name is
required. Use the Admin Interface for additional instance configuration.
See the Examples, below, for configuration syntax.
You can specify an existing database or create a new database as part
of the instance creation.
-
If the configuration in the POST body includes the name of an
existing database, that database is associated with the instance.
-
If the configuration in the POST body includes the name of a
database that does not exist, MarkLogic Server creates a new database
with that name.
-
If the configuration in the POST body does not include the name of
a database, MarkLogic Server attempts to create a database with the
same name as the instance. If a database with that name already exists,
a numeric suffix is appended to the new database name. For example, if
you create an instance named PreExisting and a database already
exists with the name PreExisting, then the database PreExisting-1
is created and associated with the instance.
If MarkLogic Server creates the database, a single forest is also
created and attached to the database. The forest name is the same as
the database name, with a "-1" suffix. For example, "my-database-1".
If no port number is specified, MarkLogic Server uses the next available
port above 8002, beginning with 8003. MarkLogic Server returns 400 (Bad
Request) if an explicitly specified port is already in use.
If no group name is specified, MarkLogic Server uses the current
context group.
For details on the meaning of these configuration settings, see
'Creating and Configuring App Servers' in the Scripting Administrative Tasks Guide.
The POST body takes the following form when Content-Type
is application/xml. Only name is required.
<rapi:rest-api xmlns:rapi="http://marklogic.com/rest-api">
<rapi:name>app-server-name</rapi:name>
<rapi:group>group-name</rapi:group>
<rapi:database>database-name</rapi:database>
<rapi:modules-database>modules-database-name</rapi:modules>
<rapi:port>1234</rapi:port>
</rapi:rest-api>
The POST body takes the following form when Content-Type
is application/json. Only name is required.
{
"rest-api": {
"name": "app-server-name",
"group": "group-name",
"database": "database-name",
"modules-database": "modules-database-name",
"port": "1234"
}
}
For more details, see
'Creating an Instance' in the REST Application Developer's Guide.
|
Example:
$ cat > svc-config
<rest-api xmlns="http://marklogic.com/rest-api">
<name>my-service</rapi:name>
<database>my-database</rapi:database>
<port>8003</port>
</rest-api>
$ curl --anyauth --user user:password -X POST -d@'./svc-config' -i \
-H "Content-type: application/xml" \
http://localhost:8002/v1/rest-apis
==> A new REST service named "my-service" is created, listening
on port 8003, serving the content in the "my-database" database.
MarkLogic Server returns the following headers in the response:
Server: MarkLogic
Content-Length: 1992
Connection: close
HTTP/1.1 201 Created
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
DELETE /v1/rest-apis/{name}
|
|
 |
Summary:
Remove an HTTP App Server servicing the MarkLogic REST API.
Optionally, also remove the attached database and forests.
|
Parameters:
include*
:
Indicates that the content and/or modules database should also be
removed. Accepted values: content, modules.
|
group?
:
The name of a MarkLogic Server cluster Group. Use this to disambiguate
the instance when more than one Group contains an instance or App
Server with the same name.
|
|
Required Privilege:
This operation 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 return status 202 (Appserver deleted).
The response body contains XML configuration information that you can
use with the REST management API to confirm removal of all related
resources.
|
Usage Notes:
NOTE: This request causes a MarkLogic Server restart.
NOTE: If you use the include parameter to tear
down the content database and/or the modules database, any data in
the removed database is lost.
The name component of the request URI should be the name of
an HTTP App Server created by making a POST request to
/rest-apis. See "POST /v1/rest-apis".
It may not be possible to remove all requested resource. For example,
if you include the content database (include=content)
and the database is in use by another App Server, it will not be deleted.
The request returns 202 (Appserver deleted) in all cases and provides
additional configuration information that you can use with the REST
Management API to confirm removal if necessary. To learn more, see
'Using the Management API' in the Monitoring MarkLogic Guide.
If you do not include a group parameter and there is
more than one instance or App Server in the cluster with the requested
name, MarkLogic Server returns status 400 (Bad Request).
For more details, see
'Removing an Instance' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -X DELETE -i \
http://localhost:8002/v1/rest-apis/RESTstop
==> The REST service named "RESTstop" is deleted. MarkLogic Server
returns the following headers in the response:
Content-type: text/html; charset=UTF-8
Server: MarkLogic
Content-Length: 2002
Connection: close
HTTP/1.1 204 Appserver deleted
Server: MarkLogic
Content-Length: 0
Connection: close
<cluster-query
xsi:schemaLocation="http://marklogic.com/manage/clusters manage-clusters.xsd"
xmlns="http://marklogic.com/manage/clusters"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
</cluster-query>
|
|
|
|
|
 |
Summary:
Retrieve configuration information about an App Server servicing the
MarkLogic REST API. This request is only available on port 8002.
|
Parameters:
format?
:
Specifies the type of the response content, as an alternative to
specifying format via the Accept header. Accepted values:
json and xml. The format
parameter takes precedence over the Accept headers.
|
group?
:
The name of a MarkLogic Server cluster Group. Use this parameter to
disambiguate the instance when multiple Groups contain an instance
with the same name.
|
|
Request Headers:
Accept:
The expected MIME type of the configuration information in the response.
Accepted types: application/json or
application/xml. Ignored if the request includes a
format parameter value.
|
|
Required Privilege:
This operation 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 status 200 (OK) and the instance
configuration details.
|
Usage Notes:
You may only make this request against port 8002.
The name component of the request URI should be the name of
an MarkLogic REST API instance created by making a POST request to
/v1/rest-apis, or via Application Builder. For details,
see "POST /v1/rest-apis".
If more than one group contains an instance (or App Server) with the
requested name and you do not supply a group parameter,
MarkLogic Server returns 400 (Bad Request).
The response contains the App Server configuration information
for name, as either JSON or XML. For details on the meaning
of the fields, see
'Creating and Configuring App Servers' in the Scripting Administrative Tasks Guide.
Specify the expected response content type using either the
format parameter or Accept header. If you supply
both, the format parameter takes precedence. If you specify
neither, XML is returned.
For more details, see
'Retrieving Configuration Information' in the REST Application Developer's Guide.
|
Example:
curl --anyauth --user user:password -X GET -i \
http://localhost:8002/v1/rest-apis/my-service
==> Information about the rest service named "my-service", in XML:
Content-type: text/html; charset=UTF-8
Server: MarkLogic
Content-Length: 2001
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 85
Connection: close
<rapi:rest-api xmlns:rapi="http://marklogic.com/rest-api">
<rapi:name>my-service</rapi:name>
<rapi:group>Default</rapi:group>
<rapi:database>my-database</rapi:database>
<rapi:modules-database>my-service-modules</rapi:modules>
<rapi:port>8003</rapi:port>
</rapi:rest-api>
|
Example:
curl --anyauth --user user:password -X GET -i -H "Accept: application/json" \
http://localhost:8002/v1/rest-apis/my-service
==> Information about the rest service named "my-service", in JSON:
Server: MarkLogic
Content-Length: 2004
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 115
Connection: close
{
"name": "my-service",
"group": "Default",
"database": "bill",
"modules-database": "my-service-modules",
"port": "8003"
}
|
|
|
|
|
 |
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:
Create a multi-statement transaction. The resulting transaction id
may be used in the txid request parameter on subsequent
requests to force evaluation to take place in the context of the created
transaction.
|
Parameters:
name
:
A symbolic name for the transaction. Default: client-txn.
|
timeLimit
:
The transaction time limit to apply to this transaction, in seconds.
Default: The request timeout configured for the App Server. If the
transaction is not committed or rolled back within this time limit,
the transaction is automatically rolled back. You may not set the
limit to a value greater than the default request timeout configured
for the App Server. For details, see
xdmp:set-transaction-time-limit.
|
|
Response Headers:
Location:
Upon success, the Location header contains a transaction URI of the
form /transactions/txid, where txid
is a concatenation of the host id and transaction id. Use the
txid in the txid parameter or URI of subsequent
requests.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server returns a status 303 (See Created
Transaction) and returns the transaction id in the Location
response header.
|
Usage Notes:
By default, each REST request is serviced in a single transaction.
The transaction is committed (or rolled back, in the case of error)
automatically before the response sent. Use this request to create a
transaction that can service multiple requests. Pass the transaction
id in the txid parameter of subsequent requests to service
a request in the created transaction.
Transactions created in this way should be explicitly committed or
rolled back using the /transactions service. Transactions
which are not explicitly committed are rolled back when the session or
request times out.
For more details, see
'Understanding Transactions in MarkLogic Server' in the Application Developer's Guide and
'Creating a Transaction' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X POST -d "" -i \
-H "Content-type: text/plain" \
http://localhost:8004/v1/transactions
==> A transaction is created. MarkLogic Server returns the
transaction ID is returned in the Location header of the
response. Use the contents of the Location header as the
value of the "txid" parameter in other methods. The transaction
ID is of the form /transactions/hostid_transactionid. For
example, the following headers are returned:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 303 See Created Transaction
Location: /transactions/9146583258914468644_3148548124558550433
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
GET /v1/transactions/{txid}
|
|
 |
Summary:
Retrieve status information for the transaction whose id matches the
txid given in the request URI.
|
Parameters:
format?
:
Specifies the content type of the response, as an alternative to using
the Accept header. Accepted values: json and
xml. This value takes precedence over the Accept headers.
|
|
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-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
Upon success, MarkLogic Server returns status 200 (OK) and returns the
transaction status details in the response body. If the transaction no
longer exists, MarkLogic Server responds with 410 (Gone).
|
Usage Notes:
The txid component of the request URI is of the form
hostid_transactionid, as is returned by creating a
transaction with a POST request on the /transactions service.
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 details, see
'Checking Transaction Status' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X GET -i \
http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087
==> Transaction status information for the requested transaction, as XML.
For example:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/xml; charset=UTF-8
Content-Length: 1011
Connection: close
<rapi:transaction-status xmlns:rapi="http://marklogic.com/rest-api">
<rapi:host>
<rapi:host-id>15127489353049502680</rapi:host-id>
<rapi:host-name>host-3.marklogic.com</rapi:host-name>
</rapi:host>
<rapi:server>
<rapi:server-id>16702373622226553017</rapi:server-id>
<rapi:server-name>RESTstop</rapi:server-name>
</rapi:server>
<rapi:database>
<rapi:database-id>6332900397030137722</rapi:database-id>
<rapi:database-name>bill</rapi:database-name>
</rapi:database>
<rapi:transaction-id>1602843393196055927</rapi:transaction-id>
<rapi:transaction-name>client-txn</rapi:transaction-name>
<rapi:transaction-mode>update</rapi:transaction-mode>
<rapi:transaction-timestamp>0</rapi:transaction-timestamp>
<rapi:transaction-state>idle</rapi:transaction-state>
<rapi:canceled>false</rapi:canceled>
<rapi:start-time>2012-05-07T16:32:42-07:00</rapi:start-time>
<rapi:time-limit>600</rapi:time-limit>
<rapi:max-time-limit>3600</rapi:max-time-limit>
<rapi:user>7071164303237443533</rapi:user>
<rapi:admin>true</rapi:admin>
</rapi:transaction-status>
|
Example:
$ curl --anyauth --user user:password -X GET -i \
-H "Accept: application/json" \
http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087
==> Transaction status information for the requested transaction, as JSON.
For example:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 200 OK
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 647
Connection: close
{
"transaction-status": {
"host": {
"host-id": "15127489353049502680",
"host-name": "host-3.marklogic.com"
},
"server": {
"server-id": "16702373622226553017",
"server-name": "RESTstop"
},
"database": {
"database-id": "6332900397030137722",
"database-name": "bill"
},
"transaction-id": "27981556736957754",
"transaction-name": "client-txn",
"transaction-mode": "update",
"transaction-timestamp": "0",
"transaction-state": "idle",
"canceled": "false",
"start-time": "2012-05-07T16:53:00-07:00",
"time-limit": "600",
"max-time-limit": "3600",
"user": "7071164303237443533",
"admin": "true"
}
}
|
|
|
|
POST /v1/transactions/{txid}
|
|
 |
Summary:
Commit or rollback the transaction whose id matches the txid
given in the request URI.
|
Parameters:
result
:
Specifies the desired outcome of the transaction. Allowed values:
commit, rollback.
|
|
Required Privilege:
This operation requires the rest-writer role, or the
following privileges:
http://marklogic.com/xdmp/privileges/rest-writer
http://marklogic.com/xdmp/privileges/rest-reader
|
Response:
MarkLogic Server responds with status 204 (Committed or Rolled Back).
If the transaction does not exist, MarkLogic Server responds with
status 400 (Bad Request).
|
Usage Notes:
The txid component of the request URI is of the form
hostid_transactionid, as is returned by creating a
transaction with a POST request on the /transactions service.
This method marks a transaction for commit, but commit does not occur
until any currently executing statements in the transaction complete.
For more details, see xdmp:commit.
For more details, see
'Committing or Rolling Back a Transaction' in the REST Application Developer's Guide.
|
Example:
$ curl --anyauth --user user:password -X POST -d "" -i \
-H "Content-type: text/plain" \
http://localhost:8003/v1/transactions/9146583258914468644_12782288875903241087?result=commit
==> The requested transaction is committed. MarkLogic Server returns
the following headers:
Server: MarkLogic
Content-Type: text/plain; charset=UTF-8
Content-Length: 31
Connection: close
HTTP/1.1 100 Continue
HTTP/1.1 204 Committed
Server: MarkLogic
Content-Length: 0
Connection: close
|
|
|
|
|
 |
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
}
} }
|
|
|