Test a query ruleset

POST /_query_rules/{ruleset_id}/_test

Auth

Evaluate match criteria against a query ruleset to identify the rules that would match that criteria.

Required authorization

Cluster privileges manage_search_query_rules

Path parameters

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

Request body

match_criteria map string to object required: The match criteria to apply to rules in the given query ruleset. Match criteria should match the keys defined in the criteria.metadata field of the rule.

Response

application/json

total_matched_rules number required
matched_rules object[] required

Examples

Request Console 1 / 8 languages

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.

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

A successful response from POST _query_rules/my-ruleset/_test.

{
  "total_matched_rules": 1,
  "matched_rules": [
    {
      "ruleset_id": "my-ruleset",
      "rule_id": "my-rule1"
    }
  ]
}

Required authorization

Path parameters

Request body { }

Response

Request body