[8.14] [Request][8.14] improved ES|QL investigation (highlighted) fie…

…lds (backport #5182) (#5235) * First draft * Additional information * Small edits * Part of Vitalii's feedback * Re-orged info * Re-adding into sen * Update docs/detections/rules-ui-create.asciidoc * Update docs/detections/rules-ui-create.asciidoc * Draft of Vitalii's input * Update docs/detections/rules-ui-create.asciidoc * Expanding definition for new fields * Update docs/detections/rules-ui-create.asciidoc * Update docs/detections/rules-ui-create.asciidoc * Update docs/detections/rules-ui-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * Update docs/detections/rules-ui-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * Update docs/detections/rules-ui-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * Update docs/detections/rules-ui-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * Update docs/detections/rules-ui-create.asciidoc * Update docs/detections/rules-ui-create.asciidoc * Update docs/detections/rules-ui-create.asciidoc --------- Co-authored-by: Benjamin Ironside Goldstein <[email protected]> (cherry picked from commit 9bb14b7) Co-authored-by: Nastasha Solomon <[email protected]>
elastic · May 20, 2024 · f50bd40 · f50bd40
1 parent b3d951c
commit f50bd40
Showing 1 changed file with 13 additions and 6 deletions.
diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc
@@ -289,7 +289,9 @@ TIP: Click the help icon (image:images/esql-ref-button.png[Click the ES|QL help
 [[esql-agg-query]]
 ===== Aggregating query 
 
-Aggregating queries use {ref}/esql-functions-operators.html#esql-agg-functions[`STATS...BY`] functions to aggregate source event data. Alerts generated by an {esql} rule with an aggregating query only contain the fields returned by the query.
+Aggregating queries use {ref}/esql-functions-operators.html#esql-agg-functions[`STATS...BY`] functions to aggregate source event data. Alerts generated by a rule with an aggregating query only contain the fields that the {esql} query returns and any new fields that the query creates.
+
+NOTE: A _new field_ is a field that doesn't exist in the query's source index and is instead created when the rule runs. You can access new fields in the details of any alerts that are generated by the rule. For example, if you use the `STATS...BY` function to create a column with aggregated values, the column is created when the rule runs and is added as a new field to any alerts that are generated by the rule. 
 
 Here is an example aggregating query:
 
@@ -311,7 +313,9 @@ NOTE: Rules that use aggregating queries might create duplicate alerts. This can
 [float]
 [[esql-non-agg-query]]
 ===== Non-aggregating query 
-Non-aggregating queries don't use `STATS...BY` functions and don't aggregate source event data. Alerts generated by an {esql} rule with a non-aggregating query only contain the fields returned by the query.
+Non-aggregating queries don't use `STATS...BY` functions and don't aggregate source event data. Alerts generated by a non-aggregating query contain source event fields that the query returns, new fields the query creates, and all other fields in the source event document. 
+
+NOTE: A _new field_ is a field that doesn't exist in the query's source index and is instead created when the rule runs. You can access new fields in the details of any alerts that are generated by the rule. For example, if you use the {ref}/esql-commands.html#esql-eval[`EVAL`] command to append new columns with calculated values, the columns are created when the rule runs, and are added as new fields to any alerts generated by the rule.
 
 Here is an example non-aggregating query:
 [source,esql]
@@ -378,12 +382,15 @@ NOTE: The `max_signals` default value is 100. You can modify it using the <<rule
 
 [float]
 [[esql-rule-limitations]]
-==== {esql} rule limitations  
+==== {esql} rule limitations 
 
-The {esql} rule has the following limitations:
+If your {esql} query creates new fields that aren’t part of the ECS schema, they aren't mapped to the alerts index so you can't search for or filter them in the Alerts table. As a workaround, create <<runtime-fields,runtime fields>>. 
+
+[float]
+[[custom-highlighted-esql-fields]]
+==== Highlight fields returned by the {esql} rule query 
 
-- If your {esql} query creates new fields that aren’t part of the ECS schema, they won’t be mapped to the alerts index, and you can't search or filter for them from the Alerts table. As a workaround, create <<runtime-fields,runtime fields>>. 
-- If your {esql} query creates new fields that aren’t in the query’s source index, they can’t be added to the rule’s <<rule-ui-advanced-params,custom highlighted fields>>.
+When configuring an {esql} rule's **<<rule-ui-advanced-params,Custom highlighted fields>>**, you can specify any fields that the rule's aggregating or non-aggregating query return. This can help ensure that returned fields are visible in the alert details flyout while you're investigating alerts.   
 
 [float]
 [[rule-ui-basic-params]]