Loading TOC...

MarkLogic 10 Product Documentation
POST /v1/alert/match

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.

URL Parameters
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.
database? Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.
format? You can use this parameter in conjunction with or instead of the request Content-type and Accept headers to indicate the input and/or output content type. The Content-type header takes precedence over format in most cases. The format parameter takes precedence over the Accept header in most cases. For details, see Controlling Input and Output Content Type in the REST Application Developer's Guide. Accepted values: json or 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 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.

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.

Required Privileges

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

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:8000/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:8000/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"
        }
    } }
] }

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.