[8.x] Add a query rules tester API call (#114168)

docs/changelog/114168.yaml

@@ -0,0 +1,5 @@
+pr: 114168
+summary: Add a query rules tester API call
+area: Relevance
+type: enhancement
+issues: []

docs/reference/query-rules/apis/index.asciidoc

@@ -23,6 +23,7 @@ Use the following APIs to manage query rulesets:
 * <<put-query-rule>>
 * <<get-query-rule>>
 * <<delete-query-rule>>
+* preview:[] <<test-query-ruleset>>
 
 include::put-query-ruleset.asciidoc[]
 include::get-query-ruleset.asciidoc[]
@@ -31,4 +32,5 @@ include::delete-query-ruleset.asciidoc[]
 include::put-query-rule.asciidoc[]
 include::get-query-rule.asciidoc[]
 include::delete-query-rule.asciidoc[]
+include::test-query-ruleset.asciidoc[]
 

docs/reference/query-rules/apis/test-query-ruleset.asciidoc

@@ -0,0 +1,133 @@
+[role="xpack"]
+[[test-query-ruleset]]
+=== Test query ruleset
+
+++++
+<titleabbrev>Tests query ruleset</titleabbrev>
+++++
+
+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"
+        }
+    ]
+}
+----

rest-api-spec/src/main/resources/rest-api-spec/api/query_rules.test.json

@@ -0,0 +1,38 @@
+{
+  "query_rules.test": {
+    "documentation": {
+      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/test-query-ruleset.html",
+      "description": "Tests a query ruleset to identify the rules that would match input criteria"
+    },
+    "stability": "experimental",
+    "visibility": "public",
+    "headers": {
+      "accept": [
+        "application/json"
+      ],
+      "content_type": [
+        "application/json"
+      ]
+    },
+    "url": {
+      "paths": [
+        {
+          "path": "/_query_rules/{ruleset_id}/_test",
+          "methods": [
+            "POST"
+          ],
+          "parts": {
+            "ruleset_id": {
+              "type": "string",
+              "description": "The unique identifier of the ruleset to test."
+            }
+          }
+        }
+      ]
+    },
+    "body": {
+      "description": "The match criteria to test against the ruleset",
+      "required": true
+    }
+  }
+}

server/src/main/java/org/elasticsearch/TransportVersions.java

@@ -242,6 +242,7 @@ static TransportVersion def(int id) {
     public static final TransportVersion ESQL_CACHED_STRING_SERIALIZATION = def(8_766_00_0);
     public static final TransportVersion CHUNK_SENTENCE_OVERLAP_SETTING_ADDED = def(8_767_00_0);
     public static final TransportVersion OPT_IN_ESQL_CCS_EXECUTION_INFO = def(8_768_00_0);
+    public static final TransportVersion QUERY_RULE_TEST_API = def(8_769_00_0);
 
     /*
      * STOP! READ THIS FIRST! No, really,