[DOCS] Uniform formatting for ES|QL commands (elastic#101728)

* Source commands * Missing word * Processing commands * Apply suggestions from code review Co-authored-by: Alexander Spies <[email protected]> * Review feedback * Add sort detail for mv * More review feedback --------- Co-authored-by: Alexander Spies <[email protected]>
idegtiarenko · Nov 6, 2023 · 76ab37b · 76ab37b
1 parent 49c5b03
commit 76ab37b
Show file tree

Hide file tree

Showing 18 changed files with 326 additions and 80 deletions.
diff --git a/docs/reference/esql/index.asciidoc b/docs/reference/esql/index.asciidoc
@@ -62,7 +62,7 @@ An overview of using the <<esql-rest>>, <<esql-kibana>>, and
 The current limitations of {esql}.
 
 <<esql-examples>>::
-A few examples of what you can with {esql}.
+A few examples of what you can do with {esql}.
 
 include::esql-get-started.asciidoc[]
 

diff --git a/docs/reference/esql/processing-commands/dissect.asciidoc b/docs/reference/esql/processing-commands/dissect.asciidoc
@@ -4,9 +4,9 @@
 
 **Syntax**
 
-[source,txt]
+[source,esql]
 ----
-DISSECT input "pattern" [ append_separator="<separator>"]
+DISSECT input "pattern" [ APPEND_SEPARATOR="<separator>"]
 ----
 
 *Parameters*
@@ -16,9 +16,9 @@ The column that contains the string you want to structure.  If the column has
 multiple values, `DISSECT` will process each value.
 
 `pattern`::
-A dissect pattern.
+A <<esql-dissect-patterns,dissect pattern>>.
 
-`append_separator="<separator>"`::
+`<separator>`::
 A string used as the separator between appended values, when using the <<esql-append-modifier,append modifier>>.
 
 *Description*
@@ -29,7 +29,7 @@ delimiter-based pattern, and extracts the specified keys as columns.
 
 Refer to <<esql-process-data-with-dissect>> for the syntax of dissect patterns.
 
-*Example*
+*Examples*
 
 // tag::examples[]
 The following example parses a string that contains a timestamp, some text, and

diff --git a/docs/reference/esql/processing-commands/drop.asciidoc b/docs/reference/esql/processing-commands/drop.asciidoc
@@ -2,7 +2,23 @@
 [[esql-drop]]
 === `DROP`
 
-Use `DROP` to remove columns:
+**Syntax**
+
+[source,esql]
+----
+DROP columns
+----
+
+*Parameters*
+
+`columns`::
+A comma-separated list of columns to remove. Supports wildcards.
+
+*Description*
+
+The `DROP` processing command removes one or more columns.
+
+*Examples*
 
 [source,esql]
 ----

diff --git a/docs/reference/esql/processing-commands/enrich.asciidoc b/docs/reference/esql/processing-commands/enrich.asciidoc
@@ -4,7 +4,7 @@
 
 **Syntax**
 
-[source,txt]
+[source,esql]
 ----
 ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2, ...]
 ----
@@ -15,18 +15,18 @@ ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2,
 The name of the enrich policy. You need to <<esql-set-up-enrich-policy,create>>
 and <<esql-execute-enrich-policy,execute>> the enrich policy first.
 
-`ON match_field`::
+`match_field`::
 The match field. `ENRICH` uses its value to look for records in the enrich
 index. If not specified, the match will be performed on the column with the same
 name as the `match_field` defined in the <<esql-enrich-policy,enrich policy>>.
 
-`WITH fieldX`::
+`fieldX`::
 The enrich fields from the enrich index that are added to the result as new
 columns. If a column with the same name as the enrich field already exists, the
 existing column will be replaced by the new column. If not specified, each of
 the enrich fields defined in the policy is added
 
-`new_nameX =`::
+`new_nameX`::
 Enables you to change the name of the column that's added for each of the enrich
 fields. Defaults to the enrich field name.
 
@@ -74,7 +74,7 @@ include::{esql-specs}/docs-IT_tests_only.csv-spec[tag=enrich_on-result]
 
 By default, each of the enrich fields defined in the policy is added as a
 column. To explicitly select the enrich fields that are added, use
-`WITH <field1>, <field2>...`:
+`WITH <field1>, <field2>, ...`:
 
 [source.merge.styled,esql]
 ----

diff --git a/docs/reference/esql/processing-commands/eval.asciidoc b/docs/reference/esql/processing-commands/eval.asciidoc
@@ -1,7 +1,30 @@
 [discrete]
 [[esql-eval]]
 === `EVAL`
-`EVAL` enables you to append new columns:
+
+**Syntax**
+
+[source,esql]
+----
+EVAL column1 = value1[, ..., columnN = valueN]
+----
+
+*Parameters*
+
+`columnX`::
+The column name.
+
+`valueX`::
+The value for the column. Can be a literal, an expression, or a
+<<esql-functions,function>>.
+
+*Description*
+
+The `EVAL` processing command enables you to append new columns with calculated
+values. `EVAL` supports various functions for calculating values. Refer to
+<<esql-functions,Functions>> for more information.
+
+*Examples*
 
 [source.merge.styled,esql]
 ----
@@ -23,8 +46,3 @@ include::{esql-specs}/docs.csv-spec[tag=evalReplace]
 |===
 include::{esql-specs}/docs.csv-spec[tag=evalReplace-result]
 |===
-
-[discrete]
-==== Functions
-`EVAL` supports various functions for calculating values. Refer to
-<<esql-functions,Functions>> for more information.
diff --git a/docs/reference/esql/processing-commands/grok.asciidoc b/docs/reference/esql/processing-commands/grok.asciidoc
@@ -4,7 +4,7 @@
 
 **Syntax**
 
-[source,txt]
+[source,esql]
 ----
 GROK input "pattern"
 ----

diff --git a/docs/reference/esql/processing-commands/keep.asciidoc b/docs/reference/esql/processing-commands/keep.asciidoc
@@ -2,11 +2,25 @@
 [[esql-keep]]
 === `KEEP`
 
-The `KEEP` command enables you to specify what columns are returned and the
-order in which they are returned.
+**Syntax**
 
-To limit the columns that are returned, use a comma-separated list of column
-names. The columns are returned in the specified order:
+[source,esql]
+----
+KEEP columns
+----
+
+*Parameters*
+`columns`::
+A comma-separated list of columns to keep. Supports wildcards.
+
+*Description*
+
+The `KEEP` processing command enables you to specify what columns are returned
+and the order in which they are returned.
+
+*Examples*
+
+The columns are returned in the specified order:
 
 [source.merge.styled,esql]
 ----
@@ -27,7 +41,7 @@ include::{esql-specs}/docs.csv-spec[tag=keepWildcard]
 
 The asterisk wildcard (`*`) by itself translates to all columns that do not
 match the other arguments. This query will first return all columns with a name
-that starts with an h, followed by all other columns:
+that starts with `h`, followed by all other columns:
 
 [source,esql]
 ----

diff --git a/docs/reference/esql/processing-commands/limit.asciidoc b/docs/reference/esql/processing-commands/limit.asciidoc
@@ -2,12 +2,30 @@
 [[esql-limit]]
 === `LIMIT`
 
-The `LIMIT` processing command enables you to limit the number of rows:
+**Syntax**
 
 [source,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=limit]
+LIMIT max_number_of_rows
 ----
 
-If not specified, `LIMIT` defaults to `500`. A single query will not return
-more than 10,000 rows, regardless of the `LIMIT` value.
+*Parameters*
+
+`max_number_of_rows`::
+The maximum number of rows to return.
+
+*Description*
+
+The `LIMIT` processing command enables you to limit the number of rows that are
+returned. If not specified, `LIMIT` defaults to `500`.
+
+A query does not return more than 10,000 rows, regardless of the `LIMIT` value.
+You can change this with the `esql.query.result_truncation_max_size` static
+cluster setting.
+
+*Example*
+
+[source,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=limit]
+----
diff --git a/docs/reference/esql/processing-commands/mv_expand.asciidoc b/docs/reference/esql/processing-commands/mv_expand.asciidoc
@@ -2,7 +2,24 @@
 [[esql-mv_expand]]
 === `MV_EXPAND`
 
-The `MV_EXPAND` processing command expands multivalued fields into one row per value, duplicating other fields:
+**Syntax**
+
+[source,esql]
+----
+MV_EXPAND column
+----
+
+*Parameters*
+
+`column`::
+The multivalued column to expand.
+
+*Description*
+
+The `MV_EXPAND` processing command expands multivalued columns into one row per
+value, duplicating other columns.
+
+*Example*
 
 [source.merge.styled,esql]
 ----

diff --git a/docs/reference/esql/processing-commands/rename.asciidoc b/docs/reference/esql/processing-commands/rename.asciidoc
@@ -2,22 +2,33 @@
 [[esql-rename]]
 === `RENAME`
 
-Use `RENAME` to rename a column using the following syntax:
+**Syntax**
 
 [source,esql]
 ----
-RENAME <old-name> AS <new-name>
+RENAME old_name1 AS new_name1[, ..., old_nameN AS new_nameN]
 ----
 
-For example:
+*Parameters*
+
+`old_nameX`::
+The name of a column you want to rename.
+
+`new_nameX`::
+The new name of the column.
+
+*Description*
+
+The `RENAME` processing command renames one or more columns. If a column with
+the new name already exists, it will be replaced by the new column.
+
+*Examples*
 
 [source,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=rename]
 ----
 
-If a column with the new name already exists, it will be replaced by the new
-column.
 
 Multiple columns can be renamed with a single `RENAME` command:
 

diff --git a/docs/reference/esql/processing-commands/sort.asciidoc b/docs/reference/esql/processing-commands/sort.asciidoc
@@ -1,35 +1,59 @@
 [discrete]
 [[esql-sort]]
 === `SORT`
-Use the `SORT` command to sort rows on one or more fields:
+
+**Syntax**
+
+[source,esql]
+----
+SORT column1 [ASC/DESC][NULLS FIRST/NULLS LAST][, ..., columnN [ASC/DESC][NULLS FIRST/NULLS LAST]]
+----
+
+*Parameters*
+
+`columnX`::
+The column to sort on.
+
+*Description*
+
+The `SORT` processing command sorts a table on one or more columns.
+
+The default sort order is ascending. Use `ASC` or `DESC` to specify an explicit
+sort order.
+
+Two rows with the same sort key are considered equal. You can provide additional
+sort expressions to act as tie breakers.
+
+Sorting on multivalued columns uses the lowest value when sorting ascending and
+the highest value when sorting descending.
+
+By default, `null` values are treated as being larger than any other value. With
+an ascending sort order, `null` values are sorted last, and with a descending
+sort order, `null` values are sorted first. You can change that by providing
+`NULLS FIRST` or `NULLS LAST`.
+
+*Examples*
 
 [source,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=sort]
 ----
 
-The default sort order is ascending. Set an explicit sort order using `ASC` or
-`DESC`:
+Explicitly sorting in ascending order with `ASC`:
 
 [source,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=sortDesc]
 ----
 
-Two rows with the same sort key are considered equal. You can provide additional
-sort expressions to act as tie breakers:
+Providing additional sort expressions to act as tie breakers:
 
 [source,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=sortTie]
 ----
 
-[discrete]
-==== `null` values
-By default, `null` values are treated as being larger than any other value. With
-an ascending sort order, `null` values are sorted last, and with a descending
-sort order, `null` values are sorted first. You can change that by providing
-`NULLS FIRST` or `NULLS LAST`:
+Sorting `null` values first using `NULLS FIRST`:
 
 [source,esql]
 ----