Merge pull request ESQL-1393 from abdonpijpelink/es-pipe-ql

[DOCS] Change ESQL into ES|QL and other docs improvements

docs/reference/esql/aggregation-functions.asciidoc

@@ -1,11 +1,9 @@
 [[esql-agg-functions]]
-== ESQL aggregation functions
+== {esql} aggregation functions
 
 ++++
 <titleabbrev>Aggregation functions</titleabbrev>
 ++++
-:keywords: {es}, ESQL, {es} query language, functions
-:description: ESQL supports various functions for calculating values.
 
 <<esql-stats-by>> support these functions:
 

docs/reference/esql/esql-functions.asciidoc

@@ -1,11 +1,9 @@
 [[esql-functions]]
-== ESQL functions
+== {esql} functions
 
 ++++
 <titleabbrev>Functions</titleabbrev>
 ++++
-:keywords: {es}, ESQL, {es} query language, functions
-:description: ESQL supports various functions for calculating values.
 
 <<esql-row,`ROW`>>, <<esql-eval,`EVAL`>> and <<esql-where,`WHERE`>> support
 these functions:

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

@@ -1,18 +1,16 @@
 [[esql-processing-commands]]
-== ESQL processing commands
+== {esql} processing commands
 
 ++++
 <titleabbrev>Processing commands</titleabbrev>
 ++++
-:keywords: {es}, ESQL, {es} query language, processing commands
-:description: ESQL 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
+{esql} processing commands change an input table by adding, removing, or changing
 rows and columns.
 
 image::images/esql/processing-command.svg[A processing command changing an input table,align="center"]
 
-ESQL supports these processing commands:
+{esql} supports these processing commands:
 
 * <<esql-dissect>>
 * <<esql-drop>>

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

@@ -1,17 +1,15 @@
 [[esql-source-commands]]
-== ESQL source commands
+== {esql} source commands
 
 ++++
 <titleabbrev>Source commands</titleabbrev>
 ++++
-:keywords: {es}, ESQL, {es} query language, source commands
-:description: An ESQL source command produces a table, typically with data from {es}.
 
-An ESQL source command produces a table, typically with data from {es}.
+An {esql} source command produces a table, typically with data from {es}.
 
 image::images/esql/source-command.svg[A source command producing a table from {es},align="center"]
 
-ESQL supports these source commands:
+{esql} supports these source commands:
 
 * <<esql-from>>
 * <<esql-row>>

docs/reference/esql/esql-syntax.asciidoc

@@ -1,17 +1,15 @@
 [[esql-syntax]]
-== ESQL syntax reference
+== {esql} syntax reference
 
 ++++
 <titleabbrev>Syntax reference</titleabbrev>
 ++++
-:keywords: {es}, ESQL, {es} query language, syntax
-:description: An ESQL query is composed of a source command followed by an optional series of processing commands, separated by a pipe character.
 
 [discrete]
 [[esql-basic-syntax]]
 === Basic syntax
 
-An ESQL query is composed of a <<esql-source-commands,source command>> followed
+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:
 
@@ -25,7 +23,7 @@ source-command
 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
+However, you can write an {esql} query as a single line. The following query is
 identical to the previous one:
 
 [source,esql]
@@ -36,7 +34,7 @@ source-command | processing-command1 | processing-command2
 [discrete]
 [[esql-comments]]
 === Comments
-ESQL uses C++ style comments:
+{esql} uses C++ style comments:
 
 * double slash `//` for single line comments
 * `/*` and `*/` for block comments

docs/reference/esql/functions/is_null.asciidoc

@@ -1,17 +1,23 @@
 [[esql-is_null]]
 === `IS_NULL`
-Returns a boolean than indicates whether its input is `null`.
+Returns a boolean that indicates whether its input is `null`.
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| WHERE IS_NULL(first_name)
+include::{esql-specs}/docs.csv-spec[tag=isNull]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=isNull-result]
+|===
 
 Combine this function with `NOT` to filter out any `null` data:
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| WHERE NOT IS_NULL(first_name)
+include::{esql-specs}/docs.csv-spec[tag=notIsNull]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=notIsNull-result]
+|===

docs/reference/esql/functions/pow.asciidoc

@@ -3,8 +3,11 @@
 Returns the the value of a base (first argument) raised to a power (second
 argument).
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-ROW base = 2.0, exponent = 2.0
-| EVAL s = POW(base, exponent)
+include::{esql-specs}/math.csv-spec[tag=pow]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=pow-result]
+|===

docs/reference/esql/functions/round.asciidoc

@@ -4,9 +4,11 @@ Rounds a number to the closest number with the specified number of digits.
 Defaults to 0 digits if no number of digits is provided. If the specified number
 of digits is negative, rounds to the number of digits left of the decimal point.
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| KEEP first_name, last_name, height
-| EVAL height = ROUND(height * 3.281, 1)
+include::{esql-specs}/docs.csv-spec[tag=round]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=round-result]
+|===

docs/reference/esql/functions/starts_with.asciidoc

@@ -3,9 +3,11 @@
 Returns a boolean that indicates whether a keyword string starts with another
 string:
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| KEEP first_name, last_name, height
-| EVAL ln_S = STARTS_WITH(last_name, "S")
+include::{esql-specs}/docs.csv-spec[tag=startsWith]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=startsWith-result]
+|===

docs/reference/esql/functions/substring.asciidoc

@@ -3,29 +3,35 @@
 Returns a substring of a string, specified by a start position and an optional
 length. This example returns the first three characters of every last name:
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| KEEP last_name
-| EVAL ln_sub = SUBSTRING(last_name, 1, 3)
+include::{esql-specs}/docs.csv-spec[tag=substring]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=substring-result]
+|===
 
 A negative start position is interpreted as being relative to the end of the
 string. This example returns the last three characters of of every last name:
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| KEEP last_name
-| EVAL ln_sub = SUBSTRING(last_name, -3, 3)
+include::{esql-specs}/docs.csv-spec[tag=substringEnd]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=substringEnd-result]
+|===
 
 If length is omitted, substring returns the remainder of the string. This
 example returns all characters except for the first:
 
-[source,esql]
+[source.merge.styled,esql]
 ----
-FROM employees
-| KEEP last_name
-| EVAL ln_sub = SUBSTRING(last_name, 2)
+include::{esql-specs}/docs.csv-spec[tag=substringRemainder]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=substringRemainder-result]
+|===

docs/reference/esql/index.asciidoc

@@ -1,18 +1,15 @@
 [[esql]]
-= ESQL
-
-:keywords: {es}, ESQL, {es} query language
-:description: ESQL is a query language that enables the iterative exploration of data.
+= {esql}
 
 :esql-tests: {xes-repo-dir}/../../plugin/esql/qa
 :esql-specs: {esql-tests}/testFixtures/src/main/resources
 
 [partintro]
 --
-The {es} Query Language (ESQL) is a query language that enables the iterative
+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
+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, typically with data from {es}.
 
@@ -33,12 +30,12 @@ The result of a query is the table produced by the final processing command.
 
 [discrete]
 [[esql-console]]
-=== Run an ESQL query
+=== Run an {esql} query
 
 [discrete]
-==== The ESQL API
+==== The {esql} API
 
-Use the `_esql` endpoint to run an ESQL query:
+Use the `_esql` endpoint to run an {esql} query:
 
 [source,console]
 ----
@@ -95,18 +92,18 @@ POST /_esql?format=txt
 [discrete]
 ==== {kib}
 
-ESQL can be used in Discover to explore a data set, and in Lens to visualize it.
+{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
-Discover or Lens, from the data view dropdown, select *ESQL*.
+Discover or Lens, from the data view dropdown, select *{esql}*.
 
-NOTE: ESQL queries in Discover and Lens are subject to the time range selected
+NOTE: {esql} queries in Discover and Lens are subject to the time range selected
 with the time filter.
 
 [discrete]
 [[esql-limitations]]
 === Limitations
 
-ESQL currently supports the following <<mapping-types,field types>>:
+{esql} currently supports the following <<mapping-types,field types>>:
 
 - `alias`
 - `boolean`

docs/reference/esql/multivalued-fields.asciidoc

@@ -1,11 +1,11 @@
 [[esql-multivalued-fields]]
-== ESQL multivalued fields
+== {esql} multivalued fields
 
 ++++
 <titleabbrev>Multivalued fields</titleabbrev>
 ++++
 
-ESQL is fine reading from multivalued fields:
+{esql} is fine reading from multivalued fields:
 
 [source,console,id=esql-multivalued-fields-reorders]
 ----
@@ -69,7 +69,7 @@ POST /_esql
 }
 ----
 
-And ESQL sees that removal:
+And {esql} sees that removal:
 
 [source,console-result]
 ----
@@ -110,7 +110,7 @@ POST /_esql
 }
 ----
 
-And ESQL also sees that:
+And {esql} also sees that:
 
 [source,console-result]
 ----

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

@@ -286,3 +286,132 @@ Tse            |Herber         |1.45
 Udi            |Jansch         |1.93
 Uri            |Lenart         |1.75
 ;
+
+docsSubstring
+// tag::substring[]
+FROM employees
+| KEEP last_name
+| EVAL ln_sub = SUBSTRING(last_name, 1, 3)
+// end::substring[]
+| SORT last_name ASC
+| LIMIT 5
+;
+
+// tag::substring-result[]
+last_name:keyword | ln_sub:keyword
+Awdeh          |Awd
+Azuma          |Azu
+Baek           |Bae
+Bamford        |Bam
+Bernatsky      |Ber
+// end::substring-result[]
+;
+
+docsSubstringEnd
+// tag::substringEnd[]
+FROM employees
+| KEEP last_name
+| EVAL ln_sub = SUBSTRING(last_name, -3, 3)
+// end::substringEnd[]
+| SORT last_name ASC
+| LIMIT 5
+;
+
+// tag::substringEnd-result[]
+last_name:keyword | ln_sub:keyword
+Awdeh          |deh
+Azuma          |uma
+Baek           |aek
+Bamford        |ord
+Bernatsky      |sky
+// end::substringEnd-result[]
+;
+
+docsSubstringRemainder
+// tag::substringRemainder[]
+FROM employees
+| KEEP last_name
+| EVAL ln_sub = SUBSTRING(last_name, 2)
+// end::substringRemainder[]
+| SORT last_name ASC
+| LIMIT 5
+;
+
+// tag::substringRemainder-result[]
+last_name:keyword | ln_sub:keyword
+Awdeh          |wdeh
+Azuma          |zuma
+Baek           |aek
+Bamford        |amford
+Bernatsky      |ernatsky
+// end::substringRemainder-result[]
+;
+
+docsStartsWith
+// tag::startsWith[]
+FROM employees
+| KEEP last_name
+| EVAL ln_S = STARTS_WITH(last_name, "B")
+// end::startsWith[]
+| SORT last_name ASC
+| LIMIT 5
+;
+
+// tag::startsWith-result[]
+last_name:keyword | ln_S:boolean
+Awdeh          |false
+Azuma          |false
+Baek           |true
+Bamford        |true
+Bernatsky      |true
+// end::startsWith-result[]
+;
+
+docsRound
+// tag::round[]
+FROM employees
+| KEEP first_name, last_name, height
+| EVAL height_ft = ROUND(height * 3.281, 1)
+// end::round[]
+| SORT height DESC, first_name ASC
+| LIMIT 3;
+
+// tag::round-result[]
+first_name:keyword | last_name:keyword | height:double | height_ft:double
+Arumugam       |Ossenbruggen   |2.1          |6.9
+Kwee           |Schusler       |2.1          |6.9
+Saniya         |Kalloufi       |2.1          |6.9
+// end::round-result[]
+;
+
+docsIsNull
+// tag::isNull[]
+FROM employees
+| KEEP first_name, last_name
+| WHERE IS_NULL(first_name)
+// end::isNull[]
+| LIMIT 3;
+
+// tag::isNull-result[]
+first_name:keyword | last_name:keyword
+null           |Demeyer
+null           |Joslin
+null           |Reistad
+// end::isNull-result[]
+;
+
+docsNotIsNull
+// tag::notIsNull[]
+FROM employees
+| KEEP first_name, last_name
+| WHERE NOT IS_NULL(first_name)
+// end::notIsNull[]
+| LIMIT 3;
+
+// tag::notIsNull-result[]
+first_name:keyword | last_name:keyword
+Georgi         |Facello
+Bezalel        |Simmel
+Parto          |Bamford
+// end::notIsNull-result[]
+;

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

@@ -169,8 +169,9 @@ NaN      | true
 log10
 // tag::log10[]
 ROW d = 1000.0 
-| EVAL s = LOG10(d);
+| EVAL s = LOG10(d)
 // end::log10[]
+;
 
 // tag::log10-result[]
 d: double | s:double
@@ -214,10 +215,16 @@ Infinity | true
 ;
 
 powDoubleDouble
-row base = 2.0, exponent = 2.0 | eval s = pow(base, exponent);
+// tag::pow[]
+ROW base = 2.0, exponent = 2.0
+| EVAL s = POW(base, exponent)
+// end::pow[]
+;
 
+// tag::pow-result[]
 base:double | exponent:double | s:double
 2.0         | 2.0             | 4.0
+// end::pow-result[]
 ;
 
 powDoubleInt

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

@@ -8,8 +8,9 @@ l:long
 maxOfInteger
 // tag::max[]
 FROM employees
-| STATS MAX(languages);
+| STATS MAX(languages)
 // end::max[]
+;
 
 // tag::max-result[]
 MAX(languages):integer
@@ -20,8 +21,9 @@ MAX(languages):integer
 minOfInteger
 // tag::min[]
 FROM employees
-| STATS MIN(languages);
+| STATS MIN(languages)
 // end::min[]
+;
 
 // tag::min-result[]
 MIN(languages):integer
@@ -186,8 +188,9 @@ l:long
 sumOfInteger
 // tag::sum[]
 FROM employees
-| STATS SUM(languages);
+| STATS SUM(languages)
 // end::sum[]
+;
 
 // tag::sum-result[]
 SUM(languages):long