--- type: api title: Test a query ruleset description: Evaluate match criteria against a query ruleset to identify the rules that would match that criteria. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-query-rules-test resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-query-rules-test products: - Elasticsearch --- # Test a query ruleset Availability: 8.10+ ## Paths - `POST` `/_query_rules/{ruleset_id}/_test` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth) #### Path Parameters - `ruleset_id` (string Id) The unique identifier of the query ruleset to be created or updated ## Description Evaluate match criteria against a query ruleset to identify the rules that would match that criteria. ## Required authorization * Cluster privileges: `manage_search_query_rules` ## Request Body `application/json` - `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) - `matched_rules` ([] QueryRulesetMatchedRule) - `ruleset_id` (string Id) Ruleset unique identifier - `rule_id` (string Id) Rule unique identifier within that ruleset ## Code Examples #### Console ```console 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 ```javascript 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 ```python 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 ```curl 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 ```java 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# ```c# 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 ```php $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 ```ruby 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 Examples #### Query ruleset test response example1 A successful response from `POST _query_rules/my-ruleset/_test`. ```json { "total_matched_rules": 1, "matched_rules": [ { "ruleset_id": "my-ruleset", "rule_id": "my-rule1" } ] } ```