[role="xpack"]
[[test-query-ruleset]]
=== Test query ruleset

++++
<titleabbrev>Tests query ruleset</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-query_rules[Query rules APIs].
--

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

preview::[]

[[test-query-ruleset-request]]
==== {api-request-title}

`POST _query_rules/<ruleset_id>/_test`

[[test-query-ruleset-prereq]]
==== {api-prereq-title}

Requires the `manage_search_query_rules` privilege.

[[test-query-ruleset-path-params]]
==== {api-path-parms-title}

`<ruleset_id>`::
(Required, string)

[[test-query-rule-request-body]]
==== {api-request-body-title}

`match_criteria`::
(Required, object) Defines 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.

[[test-query-ruleset-response-codes]]
==== {api-response-codes-title}

`400`::
The `ruleset_id` or `match_criteria` were not provided.

`404` (Missing resources)::
No query ruleset matching `ruleset_id` could be found.

[[test-query-ruleset-example]]
==== {api-examples-title}

To test a ruleset, provide the match criteria that you want to test against:

////

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

[source,console]
--------------------------------------------------
DELETE _query_rules/my-ruleset
--------------------------------------------------
// TEARDOWN

////

[source,console]
----
POST _query_rules/my-ruleset/_test
{
    "match_criteria": {
        "query_string": "puggles"
    }
}
----

A sample response:

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