Create or update a query ruleset Generally available; 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.

Required authorization

Cluster privileges: manage_search_query_rules

Edit rules and rulesets from t...

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] Required
One of:
QueryRule object array-2 array[object]
Hide attributes Show attributes

rule_id string Required

A unique identifier for the rule.

type string Required

The type of rule. pinned will identify and pin specific documents to the top of search results. exclude will exclude specific documents from search results.

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:
QueryRuleCriteria object array-2 array[object]

Hide attributes Show attributes

type string Required

The type of criteria. The following criteria types are supported:

always: Matches all queries, regardless of input.

contains: Matches that contain this value anywhere in the field meet the criteria defined by the rule. Only applicable for string values.

exact: Only exact matches meet the criteria defined by the rule. Applicable for string or numerical values.

fuzzy: Exact matches or matches within the allowed Levenshtein Edit Distance meet the criteria defined by the rule. Only applicable for string values.

gt: Matches with a value greater than this value meet the criteria defined by the rule. Only applicable for numerical values.

gte: Matches with a value greater than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.

lt: Matches with a value less than this value meet the criteria defined by the rule. Only applicable for numerical values.

lte: Matches with a value less than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.

prefix: Matches that start with this value meet the criteria defined by the rule. Only applicable for string values.

suffix: Matches that end with this value meet the criteria defined by the rule. Only applicable for string values.

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.

Hide attributes Show attributes object

type string Required

The type of criteria. The following criteria types are supported:

always: Matches all queries, regardless of input.

contains: Matches that contain this value anywhere in the field meet the criteria defined by the rule. Only applicable for string values.

exact: Only exact matches meet the criteria defined by the rule. Applicable for string or numerical values.

fuzzy: Exact matches or matches within the allowed Levenshtein Edit Distance meet the criteria defined by the rule. Only applicable for string values.

gt: Matches with a value greater than this value meet the criteria defined by the rule. Only applicable for numerical values.

gte: Matches with a value greater than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.

lt: Matches with a value less than this value meet the criteria defined by the rule. Only applicable for numerical values.

lte: Matches with a value less than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.

prefix: Matches that start with this value meet the criteria defined by the rule. Only applicable for string values.

suffix: Matches that end with this value meet the criteria defined by the rule. Only applicable for string values.

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.

actions object Required

The actions to take when the rule is matched. The format of this action depends on the rule type.

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

_id

_index

priority number
Hide attributes Show attributes object

rule_id string Required

A unique identifier for the rule.

type string Required

The type of rule. pinned will identify and pin specific documents to the top of search results. exclude will exclude specific documents from search results.

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:
QueryRuleCriteria object array-2 array[object]

Hide attributes Show attributes

type string Required

The type of criteria. The following criteria types are supported:

always: Matches all queries, regardless of input.

contains: Matches that contain this value anywhere in the field meet the criteria defined by the rule. Only applicable for string values.

exact: Only exact matches meet the criteria defined by the rule. Applicable for string or numerical values.

fuzzy: Exact matches or matches within the allowed Levenshtein Edit Distance meet the criteria defined by the rule. Only applicable for string values.

gt: Matches with a value greater than this value meet the criteria defined by the rule. Only applicable for numerical values.

gte: Matches with a value greater than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.

lt: Matches with a value less than this value meet the criteria defined by the rule. Only applicable for numerical values.

lte: Matches with a value less than or equal to this value meet the criteria defined by the rule. Only applicable for numerical values.

prefix: Matches that start with this value meet the criteria defined by the rule. Only applicable for string values.

suffix: Matches that end with this value meet the criteria defined by the rule. Only applicable for string values.

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.

Hide attributes Show attributes object

type

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.

actions object Required

The actions to take when the rule is matched. The format of this action depends on the rule type.

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.

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}

PUT _query_rules/my-ruleset
{
    "rules": [
        {
            "rule_id": "my-rule1",
            "type": "pinned",
            "criteria": [
                {
                    "type": "contains",
                    "metadata": "user_query",
                    "values": [ "pugs", "puggles" ]
                },
                {
                    "type": "exact",
                    "metadata": "user_country",
                    "values": [ "us" ]
                }
            ],
            "actions": {
                "ids": [
                    "id1",
                    "id2"
                ]
            }
        },
        {
            "rule_id": "my-rule2",
            "type": "pinned",
            "criteria": [
                {
                    "type": "fuzzy",
                    "metadata": "user_query",
                    "values": [ "rescue dogs" ]
                }
            ],
            "actions": {
                "docs": [
                    {
                        "_index": "index1",
                        "_id": "id3"
                    },
                    {
                        "_index": "index2",
                        "_id": "id4"
                    }
                ]
            }
        }
    ]
}

resp = client.query_rules.put_ruleset(
    ruleset_id="my-ruleset",
    rules=[
        {
            "rule_id": "my-rule1",
            "type": "pinned",
            "criteria": [
                {
                    "type": "contains",
                    "metadata": "user_query",
                    "values": [
                        "pugs",
                        "puggles"
                    ]
                },
                {
                    "type": "exact",
                    "metadata": "user_country",
                    "values": [
                        "us"
                    ]
                }
            ],
            "actions": {
                "ids": [
                    "id1",
                    "id2"
                ]
            }
        },
        {
            "rule_id": "my-rule2",
            "type": "pinned",
            "criteria": [
                {
                    "type": "fuzzy",
                    "metadata": "user_query",
                    "values": [
                        "rescue dogs"
                    ]
                }
            ],
            "actions": {
                "docs": [
                    {
                        "_index": "index1",
                        "_id": "id3"
                    },
                    {
                        "_index": "index2",
                        "_id": "id4"
                    }
                ]
            }
        }
    ],
)

const response = await client.queryRules.putRuleset({
  ruleset_id: "my-ruleset",
  rules: [
    {
      rule_id: "my-rule1",
      type: "pinned",
      criteria: [
        {
          type: "contains",
          metadata: "user_query",
          values: ["pugs", "puggles"],
        },
        {
          type: "exact",
          metadata: "user_country",
          values: ["us"],
        },
      ],
      actions: {
        ids: ["id1", "id2"],
      },
    },
    {
      rule_id: "my-rule2",
      type: "pinned",
      criteria: [
        {
          type: "fuzzy",
          metadata: "user_query",
          values: ["rescue dogs"],
        },
      ],
      actions: {
        docs: [
          {
            _index: "index1",
            _id: "id3",
          },
          {
            _index: "index2",
            _id: "id4",
          },
        ],
      },
    },
  ],
});

response = client.query_rules.put_ruleset(
  ruleset_id: "my-ruleset",
  body: {
    "rules": [
      {
        "rule_id": "my-rule1",
        "type": "pinned",
        "criteria": [
          {
            "type": "contains",
            "metadata": "user_query",
            "values": [
              "pugs",
              "puggles"
            ]
          },
          {
            "type": "exact",
            "metadata": "user_country",
            "values": [
              "us"
            ]
          }
        ],
        "actions": {
          "ids": [
            "id1",
            "id2"
          ]
        }
      },
      {
        "rule_id": "my-rule2",
        "type": "pinned",
        "criteria": [
          {
            "type": "fuzzy",
            "metadata": "user_query",
            "values": [
              "rescue dogs"
            ]
          }
        ],
        "actions": {
          "docs": [
            {
              "_index": "index1",
              "_id": "id3"
            },
            {
              "_index": "index2",
              "_id": "id4"
            }
          ]
        }
      }
    ]
  }
)

$resp = $client->queryRules()->putRuleset([
    "ruleset_id" => "my-ruleset",
    "body" => [
        "rules" => array(
            [
                "rule_id" => "my-rule1",
                "type" => "pinned",
                "criteria" => array(
                    [
                        "type" => "contains",
                        "metadata" => "user_query",
                        "values" => array(
                            "pugs",
                            "puggles",
                        ),
                    ],
                    [
                        "type" => "exact",
                        "metadata" => "user_country",
                        "values" => array(
                            "us",
                        ),
                    ],
                ),
                "actions" => [
                    "ids" => array(
                        "id1",
                        "id2",
                    ),
                ],
            ],
            [
                "rule_id" => "my-rule2",
                "type" => "pinned",
                "criteria" => array(
                    [
                        "type" => "fuzzy",
                        "metadata" => "user_query",
                        "values" => array(
                            "rescue dogs",
                        ),
                    ],
                ),
                "actions" => [
                    "docs" => array(
                        [
                            "_index" => "index1",
                            "_id" => "id3",
                        ],
                        [
                            "_index" => "index2",
                            "_id" => "id4",
                        ],
                    ),
                ],
            ],
        ),
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"rules":[{"rule_id":"my-rule1","type":"pinned","criteria":[{"type":"contains","metadata":"user_query","values":["pugs","puggles"]},{"type":"exact","metadata":"user_country","values":["us"]}],"actions":{"ids":["id1","id2"]}},{"rule_id":"my-rule2","type":"pinned","criteria":[{"type":"fuzzy","metadata":"user_query","values":["rescue dogs"]}],"actions":{"docs":[{"_index":"index1","_id":"id3"},{"_index":"index2","_id":"id4"}]}}]}' "$ELASTICSEARCH_URL/_query_rules/my-ruleset"

Request example

Run `PUT _query_rules/my-ruleset` to create a new query ruleset. Two rules are associated with `my-ruleset`. `my-rule1` will pin documents with IDs `id1` and `id2` when `user_query` contains `pugs` or `puggles` and `user_country` exactly matches `us`. `my-rule2` will exclude documents from different specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `rescue dogs`.

{
    "rules": [
        {
            "rule_id": "my-rule1",
            "type": "pinned",
            "criteria": [
                {
                    "type": "contains",
                    "metadata": "user_query",
                    "values": [ "pugs", "puggles" ]
                },
                {
                    "type": "exact",
                    "metadata": "user_country",
                    "values": [ "us" ]
                }
            ],
            "actions": {
                "ids": [
                    "id1",
                    "id2"
                ]
            }
        },
        {
            "rule_id": "my-rule2",
            "type": "pinned",
            "criteria": [
                {
                    "type": "fuzzy",
                    "metadata": "user_query",
                    "values": [ "rescue dogs" ]
                }
            ],
            "actions": {
                "docs": [
                    {
                        "_index": "index1",
                        "_id": "id3"
                    },
                    {
                        "_index": "index2",
                        "_id": "id4"
                    }
                ]
            }
        }
    ]
}

Create or update a query ruleset Generally available; Added in 8.10.0

Required authorization

Path parameters

Body Required

rules object | array[object] Required

criteria object | array[object] Required

Responses