Add documentation for individual query rules (#110006)

* Add individual query rule API docs

* Update docs/reference/query-rules/apis/get-query-rule.asciidoc

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

* Update docs/reference/query-rules/apis/delete-query-rule.asciidoc

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

* Update docs/reference/query-rules/apis/get-query-rule.asciidoc

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

* PR feedback

---------

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

docs/reference/query-rules/apis/delete-query-rule.asciidoc

@@ -0,0 +1,74 @@
+[role="xpack"]
+[[delete-query-rule]]
+=== Delete query rule
+
+++++
+<titleabbrev>Delete query rule</titleabbrev>
+++++
+
+Removes an individual query rule within an existing query ruleset.
+This is a destructive action that is only recoverable by re-adding the same rule via the <<put-query-rule, create or update query rule>> API.
+
+[[delete-query-rule-request]]
+==== {api-request-title}
+
+`DELETE _query_rules/<ruleset_id>/_rule/<rule_id>`
+
+[[delete-query-rule-prereq]]
+==== {api-prereq-title}
+
+Requires the `manage_search_query_rules` privilege.
+
+[[delete-query_rule-path-params]]
+==== {api-path-parms-title}
+
+`<ruleset_id>`::
+(Required, string)
+
+`<rule_id>`::
+(Required, string)
+
+[[delete-query-rule-response-codes]]
+==== {api-response-codes-title}
+
+`400`::
+Missing `ruleset_id`, `rule_id`, or both.
+
+`404` (Missing resources)::
+No query ruleset matching `ruleset_id` could be found, or else no rule matching `rule_id` was found in that ruleset.
+
+[[delete-query-rule-example]]
+==== {api-examples-title}
+
+The following example deletes the query rule with ID `my-rule1` from the query ruleset named `my-ruleset`:
+
+////
+[source,console]
+----
+PUT _query_rules/my-ruleset
+{
+    "rules": [
+        {
+            "rule_id": "my-rule1",
+            "type": "pinned",
+            "criteria": [
+                {
+                    "type": "exact",
+                    "metadata": "query_string",
+                    "values": [ "marvel" ]
+                }
+            ],
+            "actions": {
+                "ids": ["id1"]
+            }
+        }
+    ]
+}
+----
+// TESTSETUP
+////
+
+[source,console]
+----
+DELETE _query_rules/my-ruleset/_rule/my-rule1
+----

docs/reference/query-rules/apis/get-query-rule.asciidoc

@@ -0,0 +1,130 @@
+[role="xpack"]
+[[get-query-rule]]
+=== Get query rule
+
+++++
+<titleabbrev>Get query rule</titleabbrev>
+++++
+
+Retrieves information about an individual query rule within a query ruleset.
+
+[[get-query-rule-request]]
+==== {api-request-title}
+
+`GET _query_rules/<ruleset_id>/_rule/<rule_id>`
+
+[[get-query-rule-prereq]]
+==== {api-prereq-title}
+
+Requires the `manage_search_query_rules` privilege.
+
+[[get-query-rule-path-params]]
+==== {api-path-parms-title}
+
+`<ruleset_id>`::
+(Required, string)
+
+`<rule_id>`::
+(Required, string)
+
+[[get-query-rule-response-codes]]
+==== {api-response-codes-title}
+
+`400`::
+Missing `ruleset_id` or `rule_id`, or both.
+
+`404` (Missing resources)::
+Either no query ruleset matching `ruleset_id` could be found, or no rule matching `rule_id` could be found within that ruleset.
+
+[[get-query-rule-example]]
+==== {api-examples-title}
+
+The following example gets the query rule with ID `my-rule1` from the ruleset named `my-ruleset`:
+
+////
+
+[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]
+----
+GET _query_rules/my-ruleset/_rule/my-rule1
+----
+
+A sample response:
+
+[source,console-result]
+----
+{
+    "rule_id": "my-rule1",
+    "type": "pinned",
+    "criteria": [
+        {
+            "type": "contains",
+            "metadata": "query_string",
+            "values": [ "pugs", "puggles" ]
+        }
+    ],
+    "actions": {
+        "ids": [
+            "id1",
+            "id2"
+        ]
+    }
+}
+----

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

@@ -1,6 +1,8 @@
 [[query-rules-apis]]
 == Query rules APIs
 
+preview::[]
+
 ++++
 <titleabbrev>Query rules APIs</titleabbrev>
 ++++
@@ -20,8 +22,15 @@ Use the following APIs to manage query rulesets:
 * <<get-query-ruleset>>
 * <<list-query-rulesets>>
 * <<delete-query-ruleset>>
+* <<put-query-rule>>
+* <<get-query-rule>>
+* <<delete-query-rule>>
 
 include::put-query-ruleset.asciidoc[]
 include::get-query-ruleset.asciidoc[]
 include::list-query-rulesets.asciidoc[]
 include::delete-query-ruleset.asciidoc[]
+include::put-query-rule.asciidoc[]
+include::get-query-rule.asciidoc[]
+include::delete-query-rule.asciidoc[]
+

docs/reference/query-rules/apis/put-query-rule.asciidoc

@@ -0,0 +1,144 @@
+[role="xpack"]
+[[put-query-rule]]
+=== Create or update query rule
+
+++++
+<titleabbrev>Create or update query rule</titleabbrev>
+++++
+
+Creates or updates an individual query rule within a query ruleset.
+
+[[put-query-rule-request]]
+==== {api-request-title}
+
+`PUT _query_rules/<ruleset_id>/_rule/<rule_id>`
+
+[[put-query-rule-prereqs]]
+==== {api-prereq-title}
+
+Requires the `manage_search_query_rules` privilege.
+
+[role="child_attributes"]
+[[put-query-rule-request-body]]
+(Required, object) Contains parameters for a query rule:
+
+==== {api-request-body-title}
+
+`type`::
+(Required, string) The type of rule.
+At this time only `pinned` query rule types are allowed.
+
+`criteria`::
+(Required, array of objects) The criteria that must be met for the rule to be applied.
+If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.
+
+Criteria must have the following information:
+
+- `type` (Required, string) The type of criteria.
+The following criteria types are supported:
++
+--
+- `exact`
+Only exact matches meet the criteria defined by the rule.
+Applicable for string or numerical values.
+- `fuzzy`
+Exact matches or matches within the allowed {wikipedia}/Levenshtein_distance[Levenshtein Edit Distance] meet the criteria defined by the rule.
+Only applicable for string values.
+- `prefix`
+Matches that start with this value meet the criteria defined by the rule.
+Only applicable for string values.
+- `suffix`
+Matches that end with this value meet the criteria defined by the rule.
+Only applicable for string values.
+- `contains`
+Matches that contain this value anywhere in the field meet the criteria defined by the rule.
+Only applicable for string values.
+- `lt`
+Matches with a value less than this value meet the criteria defined by the rule.
+Only applicable for numerical values.
+- `lte`
+Matches with a value less than or equal to this value meet the criteria defined by the rule.
+Only applicable for numerical values.
+- `gt`
+Matches with a value greater than this value meet the criteria defined by the rule.
+Only applicable for numerical values.
+- `gte`
+Matches with a value greater than or equal to this value meet the criteria defined by the rule.
+Only applicable for numerical values.
+- `always`
+Matches all queries, regardless of input.
+--
+- `metadata` (Optional, string) The metadata field to match against.
+This metadata will be used to match against `match_criteria` sent in the <<query-dsl-rule-query>>.
+Required for all criteria types except `global`.
+- `values` (Optional, array of strings) The values to match against the metadata field.
+Only one value must match for the criteria to be met.
+Required for all criteria types except `global`.
+
+`actions`::
+(Required, object) The actions to take when the rule is matched.
+The format of this action depends on the rule type.
+
+Actions depend on the rule type.
+For `pinned` rules, actions follow the format specified by the <<query-dsl-pinned-query,Pinned Query>>.
+The following actions are allowed:
+
+- `ids` (Optional, array of strings) The unique <<mapping-id-field, document IDs>> of the documents to pin.
+Only one of `ids` or `docs` may be specified, and at least one must be specified.
+- `docs` (Optional, array of objects) The documents to pin.
+Only one of `ids` or `docs` may be specified, and at least one must be specified.
+You can specify the following attributes for each document:
++
+--
+- `_index` (Required, string) The index of the document to pin.
+- `_id` (Required, string) The unique <<mapping-id-field, document ID>>.
+--
+
+IMPORTANT: Due to limitations within <<query-dsl-pinned-query,Pinned queries>>, you can only pin 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.
+
+[[put-query-rule-example]]
+==== {api-examples-title}
+
+The following example creates a new query rule with the ID `my-rule1` in a query ruleset called `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`.
+
+[source,console]
+----
+PUT _query_rules/my-ruleset/_rule/my-rule1
+{
+    "type": "pinned",
+    "criteria": [
+        {
+            "type": "contains",
+            "metadata": "user_query",
+            "values": [ "pugs", "puggles" ]
+        },
+        {
+            "type": "exact",
+            "metadata": "user_country",
+            "values": [ "us" ]
+        }
+    ],
+    "actions": {
+        "ids": [
+            "id1",
+            "id2"
+        ]
+    }
+}
+----
+// TESTSETUP
+
+//////////////////////////
+
+[source,console]
+--------------------------------------------------
+DELETE _query_rules/my-ruleset
+--------------------------------------------------
+// TEARDOWN
+
+//////////////////////////