Create or update a query ruleset Added in 8.10.0

PUT /_query_rules/{ruleset_id}

There is a limit of 100 rules per ruleset. This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset cluster setting.

IMPORTANT: Due to limitations within pinned queries, you can only select documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.

Path parameters

  • ruleset_id string Required

    The unique identifier of the query ruleset to be created or updated.

application/json

Body Required

  • rules object | array[object]

    One of:
    Hide attributes Show attributes
    • rule_id string Required
    • type string Required

      Values are pinned or exclude.

    • criteria object | array[object] Required

      The criteria that must be met for the rule to be applied. If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.

      One of:
      Hide attributes Show attributes
      • type string Required

        Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

      • metadata string

        The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

      • values array[object]

        The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

        Additional properties are allowed.

    • actions object Required

      Additional properties are allowed.

      Hide actions attributes Show actions attributes object
      • ids array[string]

        The unique document IDs of the documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified.

      • docs array[object]

        The documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified. There is a maximum value of 100 documents in a rule. You can specify the following attributes for each document:

        • _index: The index of the document to pin.
        • _id: The unique document ID.
        Hide docs attributes Show docs attributes object
    • priority number

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • result string Required

      Values are created, updated, deleted, not_found, or noop.

PUT /_query_rules/{ruleset_id}
curl \
 -X PUT http://api.example.com/_query_rules/{ruleset_id} \
 -H "Content-Type: application/json" \
 -d '{"rules":{"rule_id":"string","type":"pinned","criteria":{"type":"global","metadata":"string","values":[{}]},"actions":{"ids":["string"],"docs":[{"_id":"string","_index":"string"}]},"priority":42.0}}'
Request examples
{
  "rules": {
    "rule_id": "string",
    "type": "pinned",
    "criteria": {
      "type": "global",
      "metadata": "string",
      "values": [
        {}
      ]
    },
    "actions": {
      "ids": [
        "string"
      ],
      "docs": [
        {
          "_id": "string",
          "_index": "string"
        }
      ]
    },
    "priority": 42.0
  }
}
Response examples (200)
{
  "result": "created"
}