[DOCS] Examples for ES|QL DISSECT and WHERE (#102591)

* DISSECT examples

* WHERE examples

* Remove references to empty keys

* Fix non-deterministic test

docs/reference/esql/esql-process-data-with-dissect-grok.asciidoc

@@ -62,8 +62,9 @@ clientip:keyword | @timestamp:keyword | status:keyword
 
 include::../ingest/processors/dissect.asciidoc[tag=intro-example-explanation]
 
-An empty key `%{}` or a <<esql-named-skip-key,named skip key>> can be used to
-match values, but exclude the value from the output.
+A <<esql-named-skip-key,named skip key>> can be used to match values, but
+exclude the value from the output.
+// TODO: Change back to original text when https://github.com/elastic/elasticsearch/pull/102580 is merged
 
 All matched values are output as keyword string data types. Use the
 <<esql-type-conversion-functions>> to convert to another data type.
@@ -126,24 +127,79 @@ include::../ingest/processors/dissect.asciidoc[tag=dissect-key-modifiers]
 ====== Right padding modifier (`->`)
 include::../ingest/processors/dissect.asciidoc[tag=dissect-modifier-skip-right-padding]
 
+For example:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=dissectRightPaddingModifier]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=dissectRightPaddingModifier-result]
+|===
+
+////
+// TODO: Re-enable when https://github.com/elastic/elasticsearch/pull/102580 is merged
+include::../ingest/processors/dissect.asciidoc[tag=dissect-modifier-empty-right-padding]
+
+For example:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=dissectEmptyRightPaddingModifier]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=dissectEmptyRightPaddingModifier-result]
+|===
+////
+
 [[esql-append-modifier]]
 ====== Append modifier (`+`)
 include::../ingest/processors/dissect.asciidoc[tag=append-modifier]
 
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=dissectAppendModifier]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=dissectAppendModifier-result]
+|===
+
 [[esql-append-order-modifier]]
 ====== Append with order modifier (`+` and `/n`)
 include::../ingest/processors/dissect.asciidoc[tag=append-order-modifier]
 
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=dissectAppendWithOrderModifier]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=dissectAppendWithOrderModifier-result]
+|===
+
 [[esql-named-skip-key]]
 ====== Named skip key (`?`)
-include::../ingest/processors/dissect.asciidoc[tag=named-skip-key]
+// include::../ingest/processors/dissect.asciidoc[tag=named-skip-key]
+// TODO: Re-enable when https://github.com/elastic/elasticsearch/pull/102580 is merged
+
+Dissect supports ignoring matches in the final result. This can be done with a
+named skip key using the `{?name}` syntax:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=dissectNamedSkipKey]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=dissectNamedSkipKey-result]
+|===
 
 [[esql-dissect-limitations]]
 ===== Limitations
 
 // tag::dissect-limitations[]
-The `DISSECT` command does not support
-<<dissect-modifier-reference-keys,reference keys>>.
+The `DISSECT` command does not support reference keys and empty keys.
 // end::dissect-limitations[]
 
 [[esql-process-data-with-grok]]

docs/reference/esql/functions/in.asciidoc

@@ -2,10 +2,16 @@
 [[esql-in-operator]]
 === `IN`
 
+//tag::body[]
 The `IN` operator allows testing whether a field or expression equals
 an element in a list of literals, fields or expressions:
 
-[source,esql]
+[source.merge.styled,esql]
 ----
 include::{esql-specs}/row.csv-spec[tag=in-with-expressions]
-----
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/row.csv-spec[tag=in-with-expressions-result]
+|===
+//end::body[]

docs/reference/esql/functions/like.asciidoc

@@ -2,6 +2,7 @@
 [[esql-like-operator]]
 === `LIKE`
 
+// tag::body[]
 Use `LIKE` to filter data based on string patterns using wildcards. `LIKE`
 usually acts on a field placed on the left-hand side of the operator, but it can
 also act on a constant (literal) expression. The right-hand side of the operator
@@ -12,9 +13,12 @@ The following wildcard characters are supported:
 * `*` matches zero or more characters.
 * `?` matches one character.
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| WHERE first_name LIKE "?b*"
-| KEEP first_name, last_name
+include::{esql-specs}/docs.csv-spec[tag=like]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=like-result]
+|===
+// end::body[]

docs/reference/esql/functions/predicates.asciidoc

@@ -2,6 +2,7 @@
 [[esql-predicates]]
 === `IS NULL` and `IS NOT NULL` predicates
 
+//tag::body[]
 For NULL comparison, use the `IS NULL` and `IS NOT NULL` predicates:
 
 [source.merge.styled,esql]
@@ -21,3 +22,4 @@ include::{esql-specs}/null.csv-spec[tag=is-not-null]
 |===
 include::{esql-specs}/null.csv-spec[tag=is-not-null-result]
 |===
+//end::body[]

docs/reference/esql/functions/rlike.asciidoc

@@ -2,14 +2,18 @@
 [[esql-rlike-operator]]
 ==== `RLIKE`
 
+// tag::body[]
 Use `RLIKE` to filter data based on string patterns using using
 <<regexp-syntax,regular expressions>>. `RLIKE` usually acts on a field placed on
 the left-hand side of the operator, but it can also act on a constant (literal)
 expression. The right-hand side of the operator represents the pattern.
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| WHERE first_name RLIKE ".leja.*"
-| KEEP first_name, last_name
-----
+include::{esql-specs}/docs.csv-spec[tag=rlike]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=rlike-result]
+|===
+// end::body[]

docs/reference/esql/processing-commands/where.asciidoc

@@ -19,9 +19,6 @@ A boolean expression.
 The `WHERE` processing command produces a table that contains all the rows from
 the input table for which the provided condition evaluates to `true`.
 
-`WHERE` supports various <<esql-functions,functions>> and
-<<esql-operators,operators>>.
-
 *Examples*
 
 [source,esql]
@@ -36,9 +33,22 @@ Which, if `still_hired` is a boolean field, can be simplified to:
 include::{esql-specs}/docs.csv-spec[tag=whereBoolean]
 ----
 
-Using a function:
+`WHERE` supports various <<esql-functions,functions>>. For example the
+<<esql-length>> function:
 
 [source,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=whereFunction]
 ----
+
+For a complete list of all functions, refer to <<esql-functions>>.
+
+include::../functions/predicates.asciidoc[tag=body]
+
+include::../functions/like.asciidoc[tag=body]
+
+include::../functions/rlike.asciidoc[tag=body]
+
+include::../functions/in.asciidoc[tag=body]
+
+For a complete list of all operators, refer to <<esql-operators>>.

docs/reference/ingest/processors/dissect.asciidoc

@@ -122,6 +122,7 @@ Use the right padding modifier to allow for repetition of the characters after a
 
 The right padding modifier may be placed on any key with any other modifiers. It should always be the furthest right
 modifier. For example: `%{+keyname/1->}` and `%{->}`
+// end::dissect-modifier-skip-right-padding[]
 
 Right padding modifier example
 |======
@@ -132,7 +133,9 @@ Right padding modifier example
 * level = WARN
 |======
 
+// tag::dissect-modifier-empty-right-padding[]
 The right padding modifier may be used with an empty key to help skip unwanted data. For example, the same input string, but wrapped with brackets requires the use of an empty right padded key to achieve the same result.
+// end::dissect-modifier-empty-right-padding[]
 
 Right padding modifier with empty key example
 |======
@@ -142,7 +145,6 @@ Right padding modifier with empty key example
 * ts = 1998-08-10T17:15:42,466
 * level = WARN
 |======
-// end::dissect-modifier-skip-right-padding[]
 
 [[append-modifier]]
 ===== Append modifier (`+`)
@@ -151,6 +153,7 @@ Right padding modifier with empty key example
 Dissect supports appending two or more results together for the output.
 Values are appended left to right. An append separator can be specified.
 In this example the append_separator is defined as a space.
+// end::append-modifier[]
 
 Append modifier example
 |======
@@ -159,7 +162,7 @@ Append modifier example
 | *Result*  a|
 * name = john jacob jingleheimer schmidt
 |======
-// end::append-modifier[]
+
 
 [[append-order-modifier]]
 ===== Append with order modifier (`+` and `/n`)
@@ -168,6 +171,7 @@ Append modifier example
 Dissect supports appending two or more results together for the output.
 Values are appended based on the order defined (`/n`). An append separator can be specified.
 In this example the append_separator is defined as a comma.
+// end::append-order-modifier[]
 
 Append with order modifier example
 |======
@@ -176,7 +180,6 @@ Append with order modifier example
 | *Result*  a|
 * name = schmidt,john,jingleheimer,jacob
 |======
-// end::append-order-modifier[]
 
 [[named-skip-key]]
 ===== Named skip key (`?`)
@@ -184,6 +187,7 @@ Append with order modifier example
 // tag::named-skip-key[]
 Dissect supports ignoring matches in the final result. This can be done with an empty key `%{}`, but for readability
 it may be desired to give that empty key a name.
+// end::named-skip-key[]
 
 Named skip key modifier example
 |======
@@ -193,7 +197,6 @@ Named skip key modifier example
 * clientip = 1.2.3.4
 * @timestamp = 30/Apr/1998:22:00:52 +0000
 |======
-// end::named-skip-key[]
 
 [[reference-keys]]
 ===== Reference keys (`*` and `&`)

x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec

@@ -554,4 +554,100 @@ ROW a = "2023-01-23T12:15:00.000Z - some text - 127.0.0.1"
 msg:keyword  | ip:keyword | date:date
 some text    | 127.0.0.1  | 2023-01-23T12:15:00.000Z
 // end::dissectWithToDatetime-result[]
+;
+
+dissectRightPaddingModifier
+// tag::dissectRightPaddingModifier[]
+ROW message="1998-08-10T17:15:42          WARN"
+| DISSECT message "%{ts->} %{level}"
+// end::dissectRightPaddingModifier[]
+;
+
+// tag::dissectRightPaddingModifier-result[]
+message:keyword  | ts:keyword | level:keyword
+1998-08-10T17:15:42          WARN|1998-08-10T17:15:42|WARN
+// end::dissectRightPaddingModifier-result[]
+;
+
+dissectEmptyRightPaddingModifier
+// tag::dissectEmptyRightPaddingModifier[]
+ROW message="[1998-08-10T17:15:42]          [WARN]"
+| DISSECT message "[%{ts}]%{->}[%{level}]"
+// end::dissectEmptyRightPaddingModifier[]
+| KEEP message, ts, level
+;
+
+// tag::dissectEmptyRightPaddingModifier-result[]
+message:keyword  | ts:keyword | level:keyword
+[1998-08-10T17:15:42]          [WARN]|1998-08-10T17:15:42 |WARN
+// end::dissectEmptyRightPaddingModifier-result[]
+;
+
+dissectAppendModifier
+// tag::dissectAppendModifier[]
+ROW message="john jacob jingleheimer schmidt"
+| DISSECT message "%{+name} %{+name} %{+name} %{+name}" APPEND_SEPARATOR=" "
+// end::dissectAppendModifier[]
+;
+
+// tag::dissectAppendModifier-result[]
+message:keyword  | name:keyword
+john jacob jingleheimer schmidt|john jacob jingleheimer schmidt
+// end::dissectAppendModifier-result[]
+;
+
+dissectAppendWithOrderModifier
+// tag::dissectAppendWithOrderModifier[]
+ROW message="john jacob jingleheimer schmidt"
+| DISSECT message "%{+name/2} %{+name/4} %{+name/3} %{+name/1}" APPEND_SEPARATOR=","
+// end::dissectAppendWithOrderModifier[]
+;
+
+// tag::dissectAppendWithOrderModifier-result[]
+message:keyword  | name:keyword
+john jacob jingleheimer schmidt|schmidt,john,jingleheimer,jacob
+// end::dissectAppendWithOrderModifier-result[]
+;
+
+dissectNamedSkipKey
+// tag::dissectNamedSkipKey[]
+ROW message="1.2.3.4 - - 30/Apr/1998:22:00:52 +0000"
+| DISSECT message "%{clientip} %{?ident} %{?auth} %{@timestamp}"
+// end::dissectNamedSkipKey[]
+;
+
+// tag::dissectNamedSkipKey-result[]
+message:keyword  | clientip:keyword  | @timestamp:keyword
+1.2.3.4 - - 30/Apr/1998:22:00:52 +0000|1.2.3.4        |30/Apr/1998:22:00:52 +0000
+// end::dissectNamedSkipKey-result[]
+;
+
+docsLike
+// tag::like[]
+FROM employees
+| WHERE first_name LIKE "?b*"
+| KEEP first_name, last_name
+// end::like[]
+| SORT first_name
+;
+
+// tag::like-result[]
+first_name:keyword  | last_name:keyword
+Ebbe           |Callaway    
+Eberhardt      |Terkki         
+// end::like-result[]
+;
+
+docsRlike
+// tag::rlike[]
+FROM employees
+| WHERE first_name RLIKE ".leja.*"
+| KEEP first_name, last_name
+// end::rlike[]
+;
+
+// tag::rlike-result[]
+first_name:keyword  | last_name:keyword
+Alejandro      |McAlpine     
+// end::rlike-result[]
 ;