MarkLogic Server 11.0 Product Documentation

GET /v1/alert/match

Summary

Retrieve a list of rules (including the rule metadata) that match documents identified by a query or a list of URIs.

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.

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 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/alert/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 user:password -X GET -i -H "Accept: application/xml" \
    'http://localhost:8000/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 user:password -X GET -i -H "Accept: application/json" \
    'http://localhost:8000/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"
        }
    } }
] }