Edits

docs/reference/esql/esql-functions.asciidoc

@@ -1,7 +1,8 @@
 [[esql-functions]]
-== ESQL functions
+== Functions
 
-<<esql-eval,`EVAL`>> and <<esql-where,`WHERE`>> support these functions:
+<<esql-row,`ROW`>>, <<esql-eval,`EVAL`>> and <<esql-where,`WHERE`>> support
+these functions:
 
 * <<esql-abs>>
 * <<esql-concat>>

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

@@ -1,10 +1,10 @@
 [[esql-processing-commands]]
-== ESQL processing commands
+== Processing commands
 
-Processing commands change an input table by adding, removing, or changing rows
-and columns.
+ESQL processing commands change an input table by adding, removing, or changing
+rows and columns.
 
-image::images/esql/processing-command.svg[A processing command changes an input table,align="center"]
+image::images/esql/processing-command.svg[A processing command changing an input table,align="center"]
 
 ESQL supports these processing commands:
 
@@ -23,16 +23,42 @@ ESQL supports these processing commands:
 [[esql-dissect]]
 === `DISSECT`
 
-TODO
+`DISSECT` enables you to extract structured data out of a string. `DISSECT`
+matches the string against a delimiter-based pattern, and extracts the specified
+keys as columns. 
+
+Refer to the <<dissect-processor,dissect processor documentation>> for the
+syntax of dissect patterns.
+
+[source,esql]
+----
+ROW a = "1953-01-23T12:15:00Z - some text - 127.0.0.1" 
+| DISSECT a "%{Y}-%{M}-%{D}T%{h}:%{m}:%{s}Z - %{msg} - %{ip}"
+----
 
 [[esql-drop]]
 === `DROP`
 
-TODO
+Use `DROP` to remove columns from a table:
+
+[source,esql]
+----
+FROM employees
+| DROP height
+----
+
+Rather than specify each column by name, you can use wildcards to drop all
+columns with a name that matches a pattern:
+
+[source,esql]
+----
+FROM employees
+| DROP height*
+----
 
 [[esql-eval]]
 === `EVAL`
-`EVAL` enables you to add new columns to the end of the table:
+`EVAL` enables you to add new columns to the end of a table:
 
 [source,esql]
 ----
@@ -59,7 +85,18 @@ FROM employees
 [[esql-grok]]
 === `GROK`
 
-TODO
+`GROK` enables you to extract structured data out of a string. `GROK` matches
+the string against patterns, based on regular expressions, and extracts the
+specified patterns as columns. 
+
+Refer to the <<grok-processor,grok processor documentation>> for the syntax for
+of grok patterns.
+
+[source,esql]
+----
+ROW a = "12 15.5 15.6 true" 
+| GROK a "%{NUMBER:b:int} %{NUMBER:c:float} %{NUMBER:d:double} %{WORD:e:boolean}"
+----
 
 [[esql-limit]]
 === `LIMIT`
@@ -75,11 +112,8 @@ FROM employees
 [[esql-project]]
 === `PROJECT`
 
-The `PROJECT` command enables you to change:
-
-* the columns that are returned,
-* the order in which they are returned,
-* and the name with which they are returned.
+The `PROJECT` command enables you to specify what columns are returned and the
+order in which they are returned.
 
 To limit the columns that are returned, use a comma-separated list of column
 names. The columns are returned in the specified order:
@@ -109,27 +143,28 @@ FROM employees
 | PROJECT h*, *
 ----
 
-Use a dash to specify columns you do not want returned:
+[[esql-rename]]
+=== `RENAME`
+
+Use `RENAME` to rename a column. If a column with the new name already exists,
+it will be replaced by the new column.
 
 [source,esql]
 ----
 FROM employees
-| PROJECT -h*
+| PROJECT first_name, last_name, still_hired
+| RENAME employed = still_hired
 ----
 
-Use `=` to rename columns:
+Multiple columns can be renamed with a single `RENAME` command:
 
 [source,esql]
 ----
 FROM employees
-| PROJECT current_employee = still_hired, *
+| PROJECT first_name, last_name
+| RENAME fn = first_name, ln = last_name
 ----
 
-[[esql-rename]]
-=== `RENAME`
-
-TODO
-
 [[esql-sort]]
 === `SORT`
 Use the `SORT` command to sort rows on one or more fields:

docs/reference/esql/esql-source-commands.asciidoc

@@ -1,18 +1,23 @@
 [[esql-source-commands]]
-== ESQL source commands
+== Source commands
 
-A source command produces a table from Elasticsearch. 
+An ESQL source command produces a table, typically with data from {es}. 
 
-image::images/esql/source-command.svg[A source command produces a table from {es},align="center"]
+image::images/esql/source-command.svg[A source command producing a table from {es},align="center"]
+
+ESQL supports these source commands:
+
+* <<esql-from>>
+* <<esql-row>>
+* <<esql-show>>
 
-[discrete]
 [[esql-from]]
 === `FROM`
 
 The `FROM` source command returns a table with up to 10,000 documents from a
 data stream, index, or alias. Each row in the resulting table represents a
-document. Each column corresponds to a field, and can be accessed by the name of
-that field.
+document. Each column corresponds to a field, and can be accessed by the name
+of that field.
 
 [source,esql]
 ----
@@ -36,7 +41,24 @@ or aliases:
 FROM employees-00001,employees-*
 ----
 
-[discrete]
+[[esql-row]]
+=== `ROW`
+
+The `ROW` source command produces a row with one or more columns with values
+that you specify. This can be useful for testing.
+
+[source,esql]
+----
+ROW a = 1, b = "two", c = null
+----
+
+`ROW` supports the use of <<esql-functions,functions>>:
+
+[source,esql]
+----
+ROW a = ROUND(1.23, 0)
+----
+
 [[esql-show]]
 === `SHOW <item>`
 
@@ -46,9 +68,3 @@ its capabilities:
 * Use `SHOW INFO` to return the deployment's version, build date and hash.
 * Use `SHOW FUNCTIONS` to return a list of all supported functions and a 
 synopsis of each function.
-
-[discrete]
-[[esql-row]]
-=== `ROW`
-
-TODO

docs/reference/esql/esql-syntax.asciidoc

@@ -0,0 +1,81 @@
+[[esql-syntax]]
+== Syntax reference
+
+[discrete]
+[[esql-basic-syntax]]
+=== Basic syntax
+
+An ESQL query is composed of a <<esql-source-commands,source command>> followed
+by an optional series of <<esql-processing-commands,processing commands>>,
+separated by a pipe character: `|`. For example:
+
+[source,esql]
+----
+source-command 
+| processing-command1 
+| processing-command2
+----
+
+The result of a query is the table produced by the final processing command.
+
+For readability, this documentation puts each processing command on a new line.
+However, you can write an ESQL query as a single line. The following query is
+identical to the previous one:
+
+[source,esql]
+----
+source-command | processing-command1 | processing-command2
+----
+
+[discrete]
+[[esql-comments]]
+=== Comments
+ESQL uses C++ style comments: 
+
+* double slash `//` for single line comments
+* `/*` and `*/` for block comments
+
+[source,esql]
+----
+// Query the employees index
+FROM employees
+| WHERE height > 2
+----
+
+[source,esql]
+----
+FROM /* Query the employees index */ employees
+| WHERE height > 2
+----
+
+[source,esql]
+----
+FROM employees
+/* Query the 
+*  employees
+*  index */
+| WHERE height > 2
+----
+
+[discrete]
+[[esql-timespan-literals]]
+=== ESQL timespan literals
+
+Datetime intervals and timespans can be expressed using timespan literals.
+Timespan literals are a combination of a number and a qualifier. These
+qualifiers are supported:
+
+* `millisecond`/`milliseconds`
+* `second`/`seconds`
+* `minute`/`minutes`
+* `hour`/`hours`
+* `day`/`days`
+* `week`/`weeks`
+* `month`/`months`
+* `year`/`years`
+
+Timespan literals are not whitespace sensitive. These expressions are all valid:
+
+* `1day`
+* `1 day`
+* `1       day`

docs/reference/esql/esql-timespan-literals.asciidoc

@@ -1,21 +0,0 @@
-[[esql-timespan-literals]]
-== ESQL timespan literals
-
-Datetime intervals and timespans can be expressed using timespan literals.
-Timespan literals are a combination of a number and a qualifier. These
-qualifiers are supported:
-
-* `millisecond`/`milliseconds`
-* `second`/`seconds`
-* `minute`/`minutes`
-* `hour`/`hours`
-* `day`/`days`
-* `week`/`weeks`
-* `month`/`months`
-* `year`/`years`
-
-Timespan literals are not whitespace sensitive. These expressions are all valid:
-
-* `1day`
-* `1 day`
-* `1       day`

docs/reference/esql/from.asciidoc

@@ -1,17 +0,0 @@
-
-== `from`
-
-The `from` keyword in ESQL chooses which index to query.
-
-[source,esql]
-----
-include::{esql-specs}/docs.csv-spec[tag=from]
-----
-
-You can match indices with a glob pattern:
-
-<insert example>
-
-And you can use commas to separate multiple patterns:
-
-<insert example>

docs/reference/esql/index.asciidoc

@@ -6,27 +6,28 @@
 
 [partintro]
 --
-
-The Elasticsearch Query Language (ESQL) is a query language that enables the
-iterative exploration of data.
+The {es} Query Language (ESQL) is a query language that enables the iterative 
+exploration of data.
 
 An ESQL query consists of a series of commands, separated by pipes. Each query
 starts with a <<esql-source-commands,source command>>. A source command produces
-a table from {es}.
+a table, typically with data from {es}.
 
-image::images/esql/source-command.svg[A source command produces a table from {es},align="center"]
+image::images/esql/source-command.svg[A source command producing a table from {es},align="center"]
 
 A source command can be followed by one or more
 <<esql-processing-commands,processing commands>>. Processing commands change an
 input table by adding, removing, or changing rows and columns.
 
-image::images/esql/processing-command.svg[A processing command changes an input table,align="center"]
+image::images/esql/processing-command.svg[A processing command changing an input table,align="center"]
 
 You can chain processing commands, separated by a pipe character: `|`. Each
 processing command works on the output table of the previous command.
 
 image::images/esql/chaining-processing-commands.svg[Processing commands can be chained,align="center"]
 
+The result of a query is the table produced by the final processing command.
+
 [discrete]
 [[esql-console]]
 === Run an ESQL query
@@ -89,7 +90,7 @@ POST /_esql?format=txt
 // TEST[continued]
 
 [discrete]
-==== Discover and Lens
+==== {kib}
 
 ESQL can be used in Discover to explore a data set, and in Lens to visualize it.
 First, enable the `enableTextBased` setting in *Advanced Settings*. Next, in
@@ -112,13 +113,11 @@ ESQL currently supports only the following field types:
 
 --
 
+include::esql-get-started.asciidoc[]
+include::esql-syntax.asciidoc[]
 include::esql-source-commands.asciidoc[]
 include::esql-processing-commands.asciidoc[]
 include::esql-functions.asciidoc[]
-include::esql-timespan-literals.asciidoc[]
-
-include::from.asciidoc[]
-
 
 :esql-tests!:
 :esql-specs!: