From b2c73bb3254f04959e2b16b02fcc264dc87d148f Mon Sep 17 00:00:00 2001
From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com>
Date: Fri, 13 Oct 2023 09:51:18 -0400
Subject: [PATCH] ESQL rule docs stub (#4012)

---
 docs/detections/rules-ui-create.asciidoc | 33 ++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc
index da5e6f0f4f..680b8221c2 100644
--- a/docs/detections/rules-ui-create.asciidoc
+++ b/docs/detections/rules-ui-create.asciidoc
@@ -259,6 +259,39 @@ IMPORTANT: When checking multiple fields, each unique combination of values from
 For example, if a rule has an interval of 5 minutes, no additional look-back time, and a history window size of 7 days, a term will be considered new only if the time it appears within the last 7 days is also within the last 5 minutes. Configure the rule interval and additional look-back time when you <<rule-schedule, set the rule's schedule>>.
 . Click *Continue* to <<rule-ui-basic-params, configure basic rule settings>>.
 
+[discrete]
+[[create-esql-rule]]
+=== Create an ES|QL rule
+
+IMPORTANT: This is a placeholder for future documentation. The following content is incomplete.
+
+. Go to *Rules* -> *Detection rules (SIEM)* -> *Create new rule*. The *Create new rule* page displays.
+. To create a rule that uses ES|QL, select **ES|QL**, 
+then write a query. There are two types of ES|QL queries:
+
+.. **Aggregating query**: This is a query that uses the `STATS...BY` grouping commands. Query results cannot be matched with a particular document in Elasticsearch. For example:
++
+[esql]
+-----
+FROM logs*
+| STATS count = COUNT(host.name) BY host.name
+| SORT host.name
+-----
+
+.. **Non-aggregating query**: This is a query that _does not_ use the `STATS...BY` grouping commands. Each row in the query results can be tracked to a source document in Elasticsearch. 
++
+For this type of query, use the operator `[metadata _id, _index, _version]` after defining the index source. This will allow for alerts to be deduplicated and linked to the source documents. For example:
++
+[esql]
+-----
+FROM logs* [metadata _id, _index, _version]
+| WHERE event.id == "test"
+| LIMIT 10
+-----
++
+Ensure, metadata properties `id`, `_index`, `_version` are carried over through pipe operators.
+
+. Click *Continue* to <<rule-ui-basic-params, configure basic rule settings>>.
 
 [float]
 [[rule-ui-basic-params]]