[DOCS] ES|QL in Elasticsearch query rules (#170291)

docs/user/alerting/alerting-setup.asciidoc

@@ -48,15 +48,11 @@ For more information on the scalability of {alert-features}, go to
 [[alerting-security]]
 === Security
 
-If you want to use the {alert-features} in a {kib} app, you must have the
-appropriate feature privileges. For example, to create rules in
-*{stack-manage-app} > {rules-ui}*, you must have `all` privileges for the
-*Management > {stack-rules-feature}* feature. To add rule actions and test
-connectors, you must also have `read` privileges for the *{connectors-feature}*
-feature. To change rule settings, you must have `all` privileges for the
-*Rules Settings* privilege or `all` privileges for the appropriate sub-feature
-such as flapping detection. For more information on configuring roles that
-provide access to features, go to <<kibana-feature-privileges>>.
+If you want to use the {alert-features} in a {kib} app, you must have the appropriate feature privileges.
+For example, to create rules in *Discover* or *{stack-manage-app} > {rules-ui}*, you must have `all` privileges for the *Management > {stack-rules-feature}* feature.
+To add rule actions and test connectors, you must also have `read` privileges for the *{connectors-feature}* feature.
+To change rule settings, you must have `all` privileges for the *Rules Settings* privilege or `all` privileges for the appropriate sub-feature such as flapping detection.
+For more information on configuring roles that provide access to features, go to <<kibana-feature-privileges>>.
 
 Each rule also has a rule visibility value (or `consumer` in the APIs), which affects the {kib} feature privileges that are required to access it.
 To view or edit a rule that has a `Stack Rules` rule visibility, for example, you must have the appropriate *Management > {stack-rules-feature}* feature privileges.

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

@@ -13,38 +13,72 @@ matches to a configured threshold, and schedules actions to run when the
 threshold condition is met.
 
 In *{stack-manage-app}* > *{rules-ui}*, click *Create rule*, fill in the name and optional tags, then select *{es} query*.
-An {es} query rule can be defined using KQL/Lucene or Query DSL.
+An {es} query rule can be defined using {es} Query Domain Specific Language (DSL), {es} Query Language (ES|QL), {kib} Query Language (KQL), or Lucene.
 
 [float]
 === Define the conditions
 
+When you create an {es} query rule, your choice of query type affects the information you must provide.
+For example:
+
 [role="screenshot"]
 image::user/alerting/images/rule-types-es-query-conditions.png[Define the condition to detect]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
-Define your query::
-If you chose the query DSL option, you must specify indices to query and a time field that is used for the time window. You must then define a query in {es} query DSL. Only the `query`, `fields`, `_source` and `runtime_mappings` fields are used, other DSL fields are not considered.
+1. Define your query
 +
-If you chose the KQL or Lucene option, you must specify a data view then define a text-based query. 
-Set the group, theshold, and time window::
-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. 
+--
+If you use {ref}/query-dsl.html[query DSL], you must select an index and time field then provide your query.
+Only the `query`, `fields`, `_source` and `runtime_mappings` fields are used, other DSL fields are not considered.
+For example:
+
+[source,sh]
+--------------------------------------------------
+{
+    "query":{
+      "match_all" : {}
+    }
+ }
+--------------------------------------------------
+
+If you use {kibana-ref}/kuery-query.html[KQL] or {kibana-ref}/lucene-query.html[Lucene], you must specify a data view then define a text-based query.
+For example, `http.request.referrer: "https://example.com"`.
+
+preview:[] If you use {ref}/esql.html[ES|QL], you must provide a source command followed by an optional series of processing commands, separated by pipe characters (|).
+For example:
+
+[source,sh]
+--------------------------------------------------
+FROM kibana_sample_data_logs
+| STATS total_bytes = SUM(bytes) BY host
+| WHERE total_bytes > 200000
+| SORT total_bytes DESC
+| LIMIT 10
+--------------------------------------------------
+--
+
+2. If you use query DSL, KQL, or Lucene, set the group and theshold.
++
+--
+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.
 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.
-Time window::: Defines how far back to search for documents, using the 
-time field set in the index clause. Generally this value should be set to a 
-value higher than the check interval, to avoid gaps in 
+--
+
+3. Set the time window, which defines how far back to search for documents.
+
+4. If you use query DSL, KQL, or Lucene, set the number of documents to send to the configured actions when the threshold condition is met.
+
+5. If you use query DSL, KQL, or Lucene, choose whether to avoid alert duplication by excluding matches from the previous run.
+This option is not available when you use a grouping field.
+
+6. Set the check interval, which defines how often to evaluate the rule conditions.
+Generally this value should be set to a value that is smaller than the time window, to avoid gaps in 
 detection.
-Set the number of documents to send:: Specifies the number of documents to pass to the configured actions when 
-the threshold condition is met.
-Exclude matches from previous run:: Turn on to avoid alert duplication by
-excluding documents that have already been detected by the previous rule run. This
-option is not available when a grouping field is specified.
 
-You can optionally change the check interval, which defines how often to evaluate the rule conditions.
-
-You must select a scope value, which affects the <<kibana-feature-privileges,{kib} feature privileges>> that are required to access the rule.
+7. Select a scope value, which affects the <<kibana-feature-privileges,{kib} feature privileges>> that are required to access the rule.
 For example when it's set to `Stack Rules`, you must have the appropriate *Management > {stack-rules-feature}* feature privileges to view or edit the rule.
 
 [float]
@@ -52,7 +86,7 @@ For example when it's set to `Stack Rules`, you must have the appropriate *Manag
 
 Use the *Test query* feature to verify that your query is valid.
 
-Valid queries are run against the selected indices using the configured time window.
+If you use query DSL, KQL, or Lucene, the query runs against the selected indices using the configured time window.
 The number of documents that match the query is displayed.
 For example:
 
@@ -60,7 +94,12 @@ For example:
 image::user/alerting/images/rule-types-es-query-valid.png[Test {es} query returns number of matches when valid]
 // NOTE: This is an autogenerated screenshot. Do not edit it directly.
 
-An error message is shown if the query is invalid.
+preview:[] If you use an ES|QL query, a table is displayed. For example:
+
+[role="screenshot"]
+image::user/alerting/images/rule-types-esql-query-valid.png[Test ES|QL query returns a table when valid]
+
+If the query is not valid, an error occurs.
 
 [float]
 === Add actions