From c6723a3c1d94a8086a010a47cd15fb9f76ee85a0 Mon Sep 17 00:00:00 2001 From: Abdon Pijpelink Date: Mon, 8 Jan 2024 12:13:33 +0100 Subject: [PATCH] [DOCS] More ES|QL backtick examples (#103995) --- docs/reference/esql/esql-get-started.asciidoc | 25 +++++ .../esql/processing-commands/eval.asciidoc | 35 ++++++- .../esql/processing-commands/stats.asciidoc | 37 ++++++-- .../src/main/resources/docs.csv-spec | 93 ------------------- .../src/main/resources/eval.csv-spec | 92 +++++++++++++++++- .../src/main/resources/stats.csv-spec | 88 ++++++++++++++++++ 6 files changed, 264 insertions(+), 106 deletions(-) diff --git a/docs/reference/esql/esql-get-started.asciidoc b/docs/reference/esql/esql-get-started.asciidoc index 454edc3af2be..631a961b023a 100644 --- a/docs/reference/esql/esql-get-started.asciidoc +++ b/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, +<> 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 diff --git a/docs/reference/esql/processing-commands/eval.asciidoc b/docs/reference/esql/processing-commands/eval.asciidoc index eb69a587014a..9b34fca7ceef 100644 --- a/docs/reference/esql/processing-commands/eval.asciidoc +++ b/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, <> 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] |=== diff --git a/docs/reference/esql/processing-commands/stats.asciidoc b/docs/reference/esql/processing-commands/stats.asciidoc index cbdb74d350fb..a34bc444578d 100644 --- a/docs/reference/esql/processing-commands/stats.asciidoc +++ b/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, <> 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] +|=== diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec index 42c5401742e6..3fe19942bdfa 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec +++ b/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 diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/eval.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/eval.csv-spec index 39d8a8bfa57e..e4f1726b3e1f 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/eval.csv-spec +++ b/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[] +; \ No newline at end of file diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec index e216d004ba64..ded080023f5c 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/stats.csv-spec +++ b/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[] +;