Add documentation for query rules CRUD APIs (#97524)

Co-authored-by: Abdon Pijpelink <abdon.pijpelink@elastic.co>

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

@@ -0,0 +1,73 @@
+[role="xpack"]
+[[delete-query-ruleset]]
+=== Delete query ruleset
+
+preview::[]
+
+++++
+<titleabbrev>Delete query ruleset</titleabbrev>
+++++
+
+Removes a query ruleset and its associated data.
+This is a destructive action that is not recoverable.
+
+[[delete-query-ruleset-request]]
+==== {api-request-title}
+
+`DELETE _query_rules/<ruleset_id>`
+
+[[delete-query-ruleset-prereq]]
+==== {api-prereq-title}
+
+Requires the `manage_cluster` privilege.
+
+[[delete-query_ruleset-path-params]]
+==== {api-path-parms-title}
+
+`<ruleset_id>`::
+(Required, string)
+
+[[delete-query-ruleset-response-codes]]
+==== {api-response-codes-title}
+
+`400`::
+The `ruleset_id` was not provided.
+
+`404` (Missing resources)::
+No query ruleset matching `ruleset_id` could be found.
+
+[[delete-query-ruleset-example]]
+==== {api-examples-title}
+
+The following example deletes 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",
+                    "value": "marvel"
+                }
+            ],
+            "actions": {
+                "ids": ["id1"]
+            }
+        }
+    ]
+}
+----
+// TESTSETUP
+////
+
+[source,console]
+----
+DELETE _query_rules/my-ruleset/
+----

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

@@ -0,0 +1,157 @@
+[role="xpack"]
+[[get-query-ruleset]]
+=== Get query ruleset
+
+preview::[]
+
+++++
+<titleabbrev>Get query ruleset</titleabbrev>
+++++
+
+Retrieves information about a query ruleset.
+
+[[get-query-ruleset-request]]
+==== {api-request-title}
+
+`GET _query_rules/<ruleset_id>`
+
+[[get-query-ruleset-prereq]]
+==== {api-prereq-title}
+
+Requires the `manage_cluster` privilege.
+
+[[get-query-ruleset-path-params]]
+==== {api-path-parms-title}
+
+`<ruleset_id>`::
+(Required, string)
+
+[[get-query-ruleset-response-codes]]
+==== {api-response-codes-title}
+
+`400`::
+The `ruleset_id` was not provided.
+
+`404` (Missing resources)::
+No query ruleset matching `ruleset_id` could be found.
+
+[[get-query-ruleset-example]]
+==== {api-examples-title}
+
+The following example gets 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",
+                    "value": "marvel"
+                }
+            ],
+            "actions": {
+                "ids": [
+                    "id1",
+                    "id2"
+                ]
+            }
+        },
+        {
+            "rule_id": "my-rule2",
+            "type": "pinned",
+            "criteria": [
+                {
+                    "type": "exact",
+                    "metadata": "query_string",
+                    "value": "dc"
+                }
+            ],
+            "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/
+----
+
+A sample response:
+
+[source,console-result]
+----
+{
+    "ruleset_id": "my-ruleset",
+    "rules": [
+        {
+            "rule_id": "my-rule1",
+            "type": "pinned",
+            "criteria": [
+                {
+                    "type": "exact",
+                    "metadata": "query_string",
+                    "value": "marvel"
+                }
+            ],
+            "actions": {
+                "ids": [
+                    "id1",
+                    "id2"
+                ]
+            }
+        },
+        {
+            "rule_id": "my-rule2",
+            "type": "pinned",
+            "criteria": [
+                {
+                    "type": "exact",
+                    "metadata": "query_string",
+                    "value": "dc"
+                }
+            ],
+            "actions": {
+                "docs": [
+                    {
+                        "_index": "index1",
+                        "_id": "id3"
+                    },
+                    {
+                        "_index": "index2",
+                        "_id": "id4"
+                    }
+                ]
+            }
+        }
+    ]
+}
+----

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

@@ -0,0 +1,23 @@
+[[query-rules-apis]]
+== Query rules APIs
+
+preview::[]
+
+++++
+<titleabbrev>Query rules APIs</titleabbrev>
+++++
+
+---
+
+Use query rules APIs to manage tasks and resources related to query rules.
+
+* <<put-query-ruleset>>
+* <<get-query-ruleset>>
+* <<list-query-rulesets>>
+* <<delete-query-ruleset>>
+
+include::put-query-ruleset.asciidoc[]
+include::get-query-ruleset.asciidoc[]
+include::list-query-rulesets.asciidoc[]
+include::delete-query-ruleset.asciidoc[]
+

docs/reference/query-rules/apis/list-query-rulesets.asciidoc

@@ -0,0 +1,76 @@
+[role="xpack"]
+[[list-query-rulesets]]
+=== List query rulesets
+
+preview::[]
+
+++++
+<titleabbrev>List query rulesets</titleabbrev>
+++++
+
+Returns information about all stored query rulesets.
+Summary information on the number of rules per ruleset will be returned, and full details can be returned with the <<get-query-ruleset>> command.
+
+[[list-query-rules-request]]
+==== {api-request-title}
+
+`GET _query_rules/`
+
+[[list-query-rules-prereq]]
+==== {api-prereq-title}
+
+Requires the `manage_cluster` privilege.
+
+[[list-query-rules-path-params]]
+==== {api-path-parms-title}
+
+`size`::
+(Optional, integer) Maximum number of results to retrieve.
+
+`from`::
+(Optional, integer) The offset from the first result to fetch.
+
+[[list-query-rules-response-codes]]
+==== {api-response-codes-title}
+
+[[list-query-rules-example]]
+==== {api-examples-title}
+
+The following example lists all configured query rulesets:
+
+[source,console]
+----
+GET _query_rules/
+----
+// TEST[skip:TBD]
+
+The following example lists the first three query rulesets:
+
+[source,console]
+----
+GET _query_rules/?from=0&size=3
+----
+// TEST[skip:TBD]
+
+A sample response:
+
+[source,console-result]
+----
+{
+    "count": 4,
+    "results": [
+        {
+            "ruleset_id": "ruleset-1",
+            "rules_count": 10
+        },
+        {
+            "ruleset_id": "ruleset-2",
+            "rules_count": 15
+        },
+        {
+            "ruleset_id": "ruleset-3",
+            "rules_count": 5
+        }
+    ]
+}
+----

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

@@ -0,0 +1,141 @@
+[role="xpack"]
+[[put-query-ruleset]]
+=== Create or update query ruleset
+
+preview::[]
+
+++++
+<titleabbrev>Create or update query ruleset</titleabbrev>
+++++
+
+Creates or updates a query ruleset.
+
+[[put-query-ruleset-request]]
+==== {api-request-title}
+
+`PUT _query_rules/<ruleset_id>`
+
+[[put-query-ruleset-prereqs]]
+==== {api-prereq-title}
+
+Requires the `manage_cluster` privilege.
+
+[[put-query-ruleset-path-params]]
+==== {api-path-parms-title}
+
+`<body>`::
+(Required, object)
+Contains parameters for a query ruleset:
+
+====
+`rules`::
+(Required, array of objects)
+The specific rules included in this query ruleset.
+
+Each rule must have the following information:
+
+- `rule_id` (Required, string)
+  A unique identifier for this rule.
+- `type` (Required, string)
+  The type of rule. At this time only `pinned` query rule types are allowed.
+- `criteria` (Required, array of objects)
+- `actions` (Required, object)
+  The actions to take when the rule is matched. The format of this action depends on the rule type.
+
+Criteria must have the following information:
+
+- `type` (Required, string)
+  The type of criteria. At this time only `exact` criteria types are allowed.
+- `metadata` (Required, string)
+  The metadata field to match against. At this time only `query_string` metadata types are allowed.
+- `value` (Required, string)
+  The value to match against the metadata field.
+
+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 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>>.
+--
+
+====
+
+[[put-query-ruleset-example]]
+==== {api-examples-title}
+
+The following example creates a new query ruleset called `my-ruleset`.
+
+Two rules are associated with `my-ruleset`:
+
+- `my-rule1` will pin documents with IDs `id1` and `id2` when the `query_string` exactly matches `marvel`.
+- `my-rule2` will pin documents from different, specified indices with IDs `id3` and `id4` when the `query_string` exactly matches `dc`.
+
+[source,console]
+----
+PUT _query_rules/my-ruleset
+{
+    "rules": [
+        {
+            "rule_id": "my-rule1",
+            "type": "pinned",
+            "criteria": [
+                {
+                    "type": "exact",
+                    "metadata": "query_string",
+                    "value": "marvel"
+                }
+            ],
+            "actions": {
+                "ids": [
+                    "id1",
+                    "id2"
+                ]
+            }
+        },
+        {
+            "rule_id": "my-rule2",
+            "type": "pinned",
+            "criteria": [
+                {
+                    "type": "exact",
+                    "metadata": "query_string",
+                    "value": "dc"
+                }
+            ],
+            "actions": {
+                "docs": [
+                    {
+                        "_index": "index1",
+                        "_id": "id3"
+                    },
+                    {
+                        "_index": "index2",
+                        "_id": "id4"
+                    }
+                ]
+            }
+        }
+    ]
+}
+----
+// TESTSETUP
+
+//////////////////////////
+
+[source,console]
+--------------------------------------------------
+DELETE _query_rules/my-ruleset
+--------------------------------------------------
+// TEARDOWN
+
+//////////////////////////

docs/reference/rest-api/index.asciidoc

@@ -38,6 +38,7 @@ not be included yet.
 * <<ml-df-trained-models-apis,{ml-cap} trained model APIs>>
 * <<migration-api,Migration APIs>>
 * <<node-lifecycle-api,Node lifecycle API>>
+* <<query-rules-apis,Query rules APIs>>
 * <<indices-reload-analyzers,Reload search analyzers API>>
 * <<repositories-metering-apis,Repositories metering APIs>>
 * <<rollup-apis,Rollup APIs>>
@@ -82,6 +83,7 @@ include::{es-repo-dir}/ml/df-analytics/apis/index.asciidoc[]
 include::{es-repo-dir}/ml/trained-models/apis/index.asciidoc[]
 include::{es-repo-dir}/migration/migration.asciidoc[]
 include::{es-repo-dir}/shutdown/apis/shutdown-api.asciidoc[]
+include::{es-repo-dir}/query-rules/apis/index.asciidoc[]
 include::{es-repo-dir}/indices/apis/reload-analyzers.asciidoc[]
 include::{es-repo-dir}/repositories-metering-api/repositories-metering-apis.asciidoc[]
 include::{es-repo-dir}/rollup/rollup-apis.asciidoc[]