[8.12] [DOCS] More ES|QL backtick examples (elastic#103995) (elastic#104049)

* Merge conflict

* Fix borked merge conflict resolution

Author: abdonpijpelink

docs/reference/esql/esql-get-started.asciidoc

@@ -205,6 +205,31 @@ calculate the median duration per client IP:
 include::{esql-specs}/stats.csv-spec[tag=gs-stats-by]
 ----
 
+[discrete]
+[[esql-getting-started-access-columns]]
+=== Access columns
+
+You can access columns by their name. If a name contains special characters,
+<<esql-identifiers,it needs to be quoted>> with backticks (+{backtick}+).
+
+Assigning an explicit name to a column created by `EVAL` or `STATS` is optional.
+If you don't provide a name, the new column name is equal to the function
+expression. For example:
+
+[source,esql]
+----
+include::{esql-specs}/eval.csv-spec[tag=gs-eval-no-column-name]
+----
+
+In this query, `EVAL` adds a new column named `event_duration/1000000.0`.
+Because its name contains special characters, to access this column, quote it
+with backticks:
+
+[source,esql]
+----
+include::{esql-specs}/eval.csv-spec[tag=gs-eval-stats-backticks]
+----
+
 [discrete]
 [[esql-getting-started-histogram]]
 === Create a histogram

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

@@ -6,7 +6,7 @@
 
 [source,esql]
 ----
-EVAL column1 = value1[, ..., columnN = valueN]
+EVAL [column1 =] value1[, ..., [columnN =] valueN]
 ----
 
 *Parameters*
@@ -28,21 +28,46 @@ values. `EVAL` supports various functions for calculating values. Refer to
 
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=eval]
+include::{esql-specs}/eval.csv-spec[tag=eval]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/docs.csv-spec[tag=eval-result]
+include::{esql-specs}/eval.csv-spec[tag=eval-result]
 |===
 
 If the specified column already exists, the existing column will be dropped, and
 the new column will be appended to the table:
 
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=evalReplace]
+include::{esql-specs}/eval.csv-spec[tag=evalReplace]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/docs.csv-spec[tag=evalReplace-result]
+include::{esql-specs}/eval.csv-spec[tag=evalReplace-result]
+|===
+
+Specifying the output column name is optional. If not specified, the new column
+name is equal to the expression. The following query adds a column named
+`height*3.281`:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/eval.csv-spec[tag=evalUnnamedColumn]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/eval.csv-spec[tag=evalUnnamedColumn-result]
+|===
+
+Because this name contains special characters, <<esql-identifiers,it needs to be
+quoted>> with backticks (+{backtick}+) when using it in subsequent commands:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/eval.csv-spec[tag=evalUnnamedColumnStats]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/eval.csv-spec[tag=evalUnnamedColumnStats-result]
 |===

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

@@ -47,36 +47,61 @@ Calculating a statistic and grouping by the values of another column:
 
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=stats]
+include::{esql-specs}/stats.csv-spec[tag=stats]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/docs.csv-spec[tag=stats-result]
+include::{esql-specs}/stats.csv-spec[tag=stats-result]
 |===
 
 Omitting `BY` returns one row with the aggregations applied over the entire
 dataset:
 
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=statsWithoutBy]
+include::{esql-specs}/stats.csv-spec[tag=statsWithoutBy]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/docs.csv-spec[tag=statsWithoutBy-result]
+include::{esql-specs}/stats.csv-spec[tag=statsWithoutBy-result]
 |===
 
 It's possible to calculate multiple values:
 
 [source,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=statsCalcMultipleValues]
+include::{esql-specs}/stats.csv-spec[tag=statsCalcMultipleValues]
 ----
 
 It's also possible to group by multiple values (only supported for long and
 keyword family fields):
 
 [source,esql]
 ----
-include::{esql-specs}/docs.csv-spec[tag=statsGroupByMultipleValues]
+include::{esql-specs}/stats.csv-spec[tag=statsGroupByMultipleValues]
 ----
+
+Specifying the output column name is optional. If not specified, the new column
+name is equal to the expression. The following query returns a column named
+`AVG(salary)`:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/stats.csv-spec[tag=statsUnnamedColumn]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/stats.csv-spec[tag=statsUnnamedColumn-result]
+|===
+
+Because this name contains special characters, <<esql-identifiers,it needs to be
+quoted>> with backticks (+{backtick}+) when using it in subsequent commands:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/stats.csv-spec[tag=statsUnnamedColumnEval]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/stats.csv-spec[tag=statsUnnamedColumnEval-result]
+|===

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

@@ -18,38 +18,6 @@ FROM employees
 avg_worked_seconds:long | birth_date:date | emp_no:integer | first_name:keyword | gender:keyword | hire_date:date | is_rehired:boolean | job_positions:keyword | languages:integer | languages.byte:integer | languages.long:long | languages.short:integer | last_name:keyword | salary:integer | salary_change:double | salary_change.int:integer |salary_change.keyword:keyword |salary_change.long:long | still_hired:boolean
 ;
 
-docsEval
-// tag::eval[]
-FROM employees
-| SORT emp_no
-| KEEP first_name, last_name, height
-| EVAL height_feet = height * 3.281, height_cm = height * 100
-// end::eval[]
-| WHERE first_name == "Georgi"
-| LIMIT 1;
-
-// tag::eval-result[]
-first_name:keyword | last_name:keyword | height:double | height_feet:double | height_cm:double
-Georgi |Facello | 2.03 | 6.66043 | 202.99999999999997
-// end::eval-result[]
-;
-
-docsEvalReplace
-// tag::evalReplace[]
-FROM employees
-| SORT emp_no
-| KEEP first_name, last_name, height
-| EVAL height = height * 3.281
-// end::evalReplace[]
-| WHERE first_name == "Georgi"
-| LIMIT 1;
-
-// tag::evalReplace-result[]
-first_name:keyword | last_name:keyword | height:double
-Georgi | Facello | 6.66043
-// end::evalReplace-result[]
-;
-
 docsLimit
 // tag::limit[]
 FROM employees
@@ -187,67 +155,6 @@ null           |Lortz          |1.53
 null           |Brender        |1.55
 ;
 
-docsStats
-// tag::stats[]
-FROM employees
-| STATS count = COUNT(emp_no) BY languages
-| SORT languages
-// end::stats[]
-;
-
-// tag::stats-result[]
-    count:long | languages:integer
-15             |1
-19             |2
-17             |3
-18             |4
-21             |5
-10             |null
-// end::stats-result[]
-;
-
-docsStatsWithoutBy
-// tag::statsWithoutBy[]
-FROM employees
-| STATS avg_lang = AVG(languages)
-// end::statsWithoutBy[]
-;
-
-// tag::statsWithoutBy-result[]
-avg_lang:double
-3.1222222222222222
-// end::statsWithoutBy-result[]
-;
-
-docsStatsMultiple
-// tag::statsCalcMultipleValues[]
-FROM employees
-| STATS avg_lang = AVG(languages), max_lang = MAX(languages)
-// end::statsCalcMultipleValues[]
-;
-
-avg_lang:double | max_lang:integer
-3.1222222222222222|5
-;
-
-docsStatsGroupByMultipleValues
-// tag::statsGroupByMultipleValues[]
-FROM employees
-| EVAL hired = DATE_FORMAT("YYYY", hire_date)
-| STATS avg_salary = AVG(salary) BY hired, languages.long
-| EVAL avg_salary = ROUND(avg_salary)
-| SORT hired, languages.long
-// end::statsGroupByMultipleValues[]
-| LIMIT 4
-;
-
-hired:keyword |languages.long:long | avg_salary:double
-1985           |1              |54668.0        
-1985           |3              |47723.0        
-1985           |4              |44817.0        
-1985           |5              |47720.0  
-;
-
 docsWhere
 // tag::where[]
 FROM employees

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

@@ -243,7 +243,7 @@ Anneke         |Preusig        |Anneke Preusig
 docsGettingStartedEval
 // tag::gs-eval[]
 FROM sample_data
-| EVAL duration_ms = event_duration / 1000000.0
+| EVAL duration_ms = event_duration/1000000.0
 // end::gs-eval[]
 | LIMIT 0
 ;
@@ -254,10 +254,98 @@ FROM sample_data
 docsGettingStartedRound
 // tag::gs-round[]
 FROM sample_data
-| EVAL duration_ms = ROUND(event_duration / 1000000.0, 1)
+| EVAL duration_ms = ROUND(event_duration/1000000.0, 1)
 // end::gs-round[]
 | LIMIT 0
 ;
 
 @timestamp:date | client_ip:ip | event_duration:long | message:keyword |  duration_ms:double
 ;
+
+docsGettingStartedEvalNoColumnName
+// tag::gs-eval-no-column-name[]
+FROM sample_data
+| EVAL event_duration/1000000.0
+// end::gs-eval-no-column-name[]
+| LIMIT 0
+;
+
+@timestamp:date | client_ip:ip | event_duration:long | message:keyword |  event_duration/1000000.0:double
+;
+
+docsGettingStartedEvalStatsBackticks
+// tag::gs-eval-stats-backticks[]
+FROM sample_data
+| EVAL event_duration/1000000.0
+| STATS MEDIAN(`event_duration/1000000.0`)
+// end::gs-eval-stats-backticks[]
+;
+
+MEDIAN(`event_duration/1000000.0`):double
+2.764889
+;
+
+docsEval
+// tag::eval[]
+FROM employees
+| SORT emp_no
+| KEEP first_name, last_name, height
+| EVAL height_feet = height * 3.281, height_cm = height * 100
+// end::eval[]
+| LIMIT 3;
+
+// tag::eval-result[]
+first_name:keyword | last_name:keyword | height:double | height_feet:double | height_cm:double
+Georgi         |Facello        |2.03           |6.66043           |202.99999999999997
+Bezalel        |Simmel         |2.08           |6.82448           |208.0             
+Parto          |Bamford        |1.83           |6.004230000000001 |183.0  
+// end::eval-result[]
+;
+
+docsEvalReplace
+// tag::evalReplace[]
+FROM employees
+| SORT emp_no
+| KEEP first_name, last_name, height
+| EVAL height = height * 3.281
+// end::evalReplace[]
+| LIMIT 3;
+
+// tag::evalReplace-result[]
+first_name:keyword | last_name:keyword | height:double
+Georgi         |Facello        |6.66043           
+Bezalel        |Simmel         |6.82448           
+Parto          |Bamford        |6.004230000000001 
+// end::evalReplace-result[]
+;
+
+docsEvalUnnamedColumn
+// tag::evalUnnamedColumn[]
+FROM employees
+| SORT emp_no
+| KEEP first_name, last_name, height
+| EVAL height * 3.281
+// end::evalUnnamedColumn[]
+| LIMIT 3;
+
+// tag::evalUnnamedColumn-result[]
+first_name:keyword | last_name:keyword | height:double | height*3.281:double
+Georgi         |Facello        |2.03           |6.66043           
+Bezalel        |Simmel         |2.08           |6.82448           
+Parto          |Bamford        |1.83           |6.004230000000001
+// end::evalUnnamedColumn-result[]
+;
+
+docsEvalUnnamedColumnStats
+// tag::evalUnnamedColumnStats[]
+FROM employees
+| EVAL height * 3.281
+| STATS avg_height_feet = AVG(`height*3.281`)
+// end::evalUnnamedColumnStats[]
+;
+
+// tag::evalUnnamedColumnStats-result[]
+avg_height_feet:double
+5.801464200000001
+// end::evalUnnamedColumnStats-result[]
+;