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

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,11 +28,11 @@ 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
@@ -40,9 +40,34 @@ 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,11 +47,11 @@ 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
@@ -59,18 +59,18 @@ 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
@@ -78,5 +78,30 @@ 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[]
+;

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

@@ -791,3 +791,91 @@ FROM sample_data
 count(`event_duration`):l
 7
 ;
+
+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  
+;
+
+docsStatsUnnamedColumn
+// tag::statsUnnamedColumn[]
+FROM employees
+| STATS AVG(salary)
+// end::statsUnnamedColumn[]
+;
+
+// tag::statsUnnamedColumn-result[]
+AVG(salary):double
+48248.55
+// end::statsUnnamedColumn-result[]
+;
+
+docsStatsUnnamedColumnEval
+// tag::statsUnnamedColumnEval[]
+FROM employees
+| STATS AVG(salary)
+| EVAL avg_salary_rounded = ROUND(`AVG(salary)`)
+// end::statsUnnamedColumnEval[]
+;
+
+// tag::statsUnnamedColumnEval-result[]
+AVG(salary):double | avg_salary_rounded:double
+48248.55           | 48249.0
+// end::statsUnnamedColumnEval-result[]
+;