Loading TOC...

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

URL Parameters
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.
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? 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.

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

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

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