From e6fb86914b1006db33fdd766b29e1fca638066f7 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Mon, 20 May 2024 14:19:52 -0400 Subject: [PATCH] [Request][8.14] improved ES|QL investigation (highlighted) fields (#5182) * 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 <91905639+benironside@users.noreply.github.com> * Update docs/detections/rules-ui-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> * Update docs/detections/rules-ui-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> * Update docs/detections/rules-ui-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> * 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 <91905639+benironside@users.noreply.github.com> (cherry picked from commit 9bb14b7e44f634904705c50a02d4b3309f1fe0bd) --- docs/detections/rules-ui-create.asciidoc | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index 936bb7570e..eb7acda8a4 100644 --- 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 <>. + +[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 <>. -- 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 <>. +When configuring an {esql} rule's **<>**, 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]]