Create or update a query ruleset

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

About editing rules and rulesets

Path Parameters

ruleset_id string Id required: The unique identifier of the query ruleset to be created or updated.

Request

rules union oneOf required: QueryRule or QueryRule[]

Response

application/json

Examples

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.

Request Console 1 / 8 languages

Console Kibana Dev Tools

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

JavaScript Elasticsearch JavaScript Client

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",
          },
        ],
      },
    },
  ],
});

Python Elasticsearch Python Client

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

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_query_rules/my-ruleset" \
  -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"
            }
          ]
        }
      }
    ]
  }'

Java Elasticsearch Java Client

client.queryRules().putRuleset(p -> p
    .rules(List.of(QueryRule.queryRuleOf(q -> q
            .ruleId("my-rule1")
            .type(QueryRuleType.Pinned)
            .criteria(List.of(QueryRuleCriteria.of(qu -> qu
                    .type(QueryRuleCriteriaType.Contains)
                    .metadata("user_query")
                    .values(List.of(JsonData.fromJson("\"pugs\""),JsonData.fromJson("\"puggles\"")))
                ),QueryRuleCriteria.of(qu -> qu
                    .type(QueryRuleCriteriaType.Exact)
                    .metadata("user_country")
                    .values(JsonData.fromJson("\"us\""))
                )))
            .actions(a -> a
                .ids(List.of("id1","id2"))
            )
        ),QueryRule.queryRuleOf(q -> q
            .ruleId("my-rule2")
            .type(QueryRuleType.Pinned)
            .criteria(c -> c
                .type(QueryRuleCriteriaType.Fuzzy)
                .metadata("user_query")
                .values(JsonData.fromJson("\"rescue dogs\""))
            )
            .actions(a -> a
                .docs(List.of(PinnedDoc.of(pi -> pi
                        .id("id3")
                        .index("index1")
                    ),PinnedDoc.of(pi -> pi
                        .id("id4")
                        .index("index2")
                    )))
            )
        )))
    .rulesetId("my-ruleset")
);

C# Elasticsearch .NET Client

var response = await client.QueryRules
    .PutRulesetAsync(rulesetId: "my-ruleset", d1 => d1
        .Rules(d2 => d2
            .Actions(d3 => d3
                .Ids(["id1", "id2"])
            )
            .Criteria(d3 => d3
                .Metadata("user_query")
                .Type(QueryRuleCriteriaType.Contains)
                .Values(["pugs", "puggles"]), d3 => d3
                .Metadata("user_country")
                .Type(QueryRuleCriteriaType.Exact)
                .Values(["us"])
            )
            .RuleId("my-rule1")
            .Type(QueryRuleType.Pinned), d2 => d2
            .Actions(d3 => d3
                .Docs(d4 => d4
                    .Id("id3")
                    .Index("index1"), d4 => d4
                    .Id("id4")
                    .Index("index2")
                )
            )
            .Criteria(d3 => d3
                .Metadata("user_query")
                .Type(QueryRuleCriteriaType.Fuzzy)
                .Values(["rescue dogs"])
            )
            .RuleId("my-rule2")
            .Type(QueryRuleType.Pinned)
        )
    );

PHP Elasticsearch PHP Client

$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",
                        ],
                    ),
                ],
            ],
        ),
    ],
]);

Ruby Elasticsearch Ruby Client

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

Response

No example