MarkLogic 9 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.

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

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"
        }
    } }
] }