[8.11] [DOCS] Elasticsearch query rule group by multiple terms (#170675…

…) (#170699)

# Backport

This will backport the following commits from `main` to `8.11`:
- [[DOCS] Elasticsearch query rule group by multiple terms
(#170675)](#170675)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT [{"author":{"name":"Lisa
Cawley","email":"[email protected]"},"sourceCommit":{"committedDate":"2023-11-06T20:56:57Z","message":"[DOCS]
Elasticsearch query rule group by multiple terms
(#170675)","sha":"6ac15df6611a1689121c336a0cdba965825351a8","branchLabelMapping":{"^v8.12.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:ResponseOps","docs","Feature:Alerting/RuleTypes","backport:prev-minor","v8.11.0","v8.12.0"],"number":170675,"url":"https://github.com/elastic/kibana/pull/170675","mergeCommit":{"message":"[DOCS]
Elasticsearch query rule group by multiple terms
(#170675)","sha":"6ac15df6611a1689121c336a0cdba965825351a8"}},"sourceBranch":"main","suggestedTargetBranches":["8.11"],"targetPullRequestStates":[{"branch":"8.11","label":"v8.11.0","labelRegex":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.12.0","labelRegex":"^v8.12.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/170675","number":170675,"mergeCommit":{"message":"[DOCS]
Elasticsearch query rule group by multiple terms
(#170675)","sha":"6ac15df6611a1689121c336a0cdba965825351a8"}}]}]
BACKPORT-->

docs/user/alerting/rule-types/es-query.asciidoc

@@ -61,7 +61,10 @@ FROM kibana_sample_data_logs
 +
 --
 When::: Specify how to calculate the value that is compared to the threshold. The value is calculated by aggregating a numeric field within the time window. The aggregation options are: `count`, `average`, `sum`, `min`, and `max`. When using `count` the document count is used and an aggregation field is not necessary.
-Over or Grouped Over::: Specify whether the aggregation is applied over all documents or split into groups using a grouping field. If grouping is used, an alert will be created for each group when it meets the condition. To limit the number of alerts on high cardinality fields, you must specify the number of groups to check against the threshold. Only the top groups are checked.
+Over or Grouped Over::: Specify whether the aggregation is applied over all documents or split into groups using up to four grouping fields.
+If you choose to use grouping, it's a {ref}/search-aggregations-bucket-terms-aggregation.html[terms] or {ref}/search-aggregations-bucket-multi-terms-aggregation.html[multi terms aggregation]; an alert will be created for each unique set of values when it meets the condition.
+To limit the number of alerts on high cardinality fields, you must specify the number of groups to check against the threshold.
+Only the top groups are checked.
 Threshold::: Defines a threshold value and a comparison operator  (`is above`, 
 `is above or equals`, `is below`, `is below or equals`, or `is between`). The value
 calculated by the aggregation is compared to this threshold.

docs/user/whats-new.asciidoc

@@ -180,7 +180,7 @@ image::images/custom-field.gif[An example of creating a custom case field in {ki
 [discrete]
 ==== Supporting multi levels of term aggregations in {es} rule type 
 
-The existing {es} alerting rule (KQL-based) is now supported by multiple selection when grouping by alert fields, which allows you to define multiple layers of term aggregations.
+The existing {es} alerting rule is now supported by multiple selection when grouping by alert fields, which allows you to define multiple layers of term aggregations.
 
 [role="screenshot"]
 image::images/term-aggs.png[An example of creating multiple layers of term aggregations]

x-pack/plugins/alerting/docs/openapi/bundled.json

@@ -3228,8 +3228,19 @@
         "type": "integer"
       },
       "termfield": {
-        "description": "This property is required when `groupBy` is `top`. The name of the field that is used for grouping the aggregation.\n",
-        "type": "string"
+        "description": "The names of up to four fields that are used for grouping the aggregation. This property is required when `groupBy` is `top`.\n",
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 4
+          }
+        ]
       },
       "threshold": {
         "description": "The threshold value that is used with the `thresholdComparator`. If the `thresholdComparator` is `between` or `notBetween`, you must specify the boundary values.\n",

x-pack/plugins/alerting/docs/openapi/bundled.yaml

@@ -2187,8 +2187,13 @@ components:
       type: integer
     termfield:
       description: |
-        This property is required when `groupBy` is `top`. The name of the field that is used for grouping the aggregation.
-      type: string
+        The names of up to four fields that are used for grouping the aggregation. This property is required when `groupBy` is `top`.
+      oneOf:
+        - type: string
+        - type: array
+          items:
+            type: string
+          maxItems: 4
     threshold:
       description: |
         The threshold value that is used with the `thresholdComparator`. If the `thresholdComparator` is `between` or `notBetween`, you must specify the boundary values.

x-pack/plugins/alerting/docs/openapi/components/schemas/termfield.yaml

@@ -1,4 +1,9 @@
 description: >
+  The names of up to four fields that are used for grouping the aggregation.
   This property is required when `groupBy` is `top`.
-  The name of the field that is used for grouping the aggregation.
-type: string
+oneOf:
+  - type: string
+  - type: array
+    items:
+      type: string
+    maxItems: 4