[DOCS] Improve ES|QL functions reference for functions E-Z (#104623)

* Functions E-Z

* Incorporate changes from #103686

* More functions

* More functions

* Update docs/reference/esql/functions/floor.asciidoc

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

* Update docs/reference/esql/functions/left.asciidoc

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Alexander Spies <alexander.spies@elastic.co>

* Review feedback

* Fix geo_shape description

* Change 'colum'/'field' into 'expressions'

* Review feedback

* One more

---------

Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>
Co-authored-by: Alexander Spies <alexander.spies@elastic.co>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

docs/reference/esql/functions/asin.asciidoc

@@ -14,9 +14,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-Returns the
-https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arcsine]
-of the input numeric expression as an angle, expressed in radians.
+Returns the {wikipedia}/Inverse_trigonometric_functions[arcsine] of the input
+numeric expression as an angle, expressed in radians.
 
 *Supported types*
 

docs/reference/esql/functions/atan.asciidoc

@@ -14,9 +14,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-Returns the
-https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arctangent] of the
-input numeric expression as an angle, expressed in radians.
+Returns the {wikipedia}/Inverse_trigonometric_functions[arctangent] of the input
+numeric expression as an angle, expressed in radians.
 
 *Supported types*
 

docs/reference/esql/functions/atan2.asciidoc

@@ -17,9 +17,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-The https://en.wikipedia.org/wiki/Atan2[angle] between the positive x-axis and
-the ray from the origin to the point (x , y) in the Cartesian plane, expressed
-in radians.
+The {wikipedia}/Atan2[angle] between the positive x-axis and the ray from the
+origin to the point (x , y) in the Cartesian plane, expressed in radians.
 
 *Supported types*
 

docs/reference/esql/functions/auto_bucket.asciidoc

@@ -6,13 +6,13 @@
 
 [source,esql]
 ----
-AUTO_BUCKET(field, buckets, from, to)
+AUTO_BUCKET(expression, buckets, from, to)
 ----
 
 *Parameters*
 
 `field`::
-Numeric or date column from which to derive buckets.
+Numeric or date expression from which to derive buckets.
 
 `buckets`::
 Target number of buckets.

docs/reference/esql/functions/avg.asciidoc

@@ -6,15 +6,15 @@
 
 [source,esql]
 ----
-AVG(column)
+AVG(expression)
 ----
 
-`column`::
-Numeric column. If `null`, the function returns `null`.
+`expression`::
+Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-The average of a numeric field.
+The average of a numeric expression.
 
 *Supported types*
 

docs/reference/esql/functions/cos.asciidoc

@@ -14,8 +14,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-Returns the https://en.wikipedia.org/wiki/Sine_and_cosine[cosine] of `n`. Input
-expected in radians.
+Returns the {wikipedia}/Sine_and_cosine[cosine] of `n`. Input expected in
+radians.
 
 *Supported types*
 

docs/reference/esql/functions/cosh.asciidoc

@@ -12,14 +12,13 @@ image::esql/functions/signature/cosh.svg[Embedded,opts=inline]
 `n`::
 Numeric expression. If `null`, the function returns `null`.
 
-*Supported types*
+*Description*
 
-include::types/cosh.asciidoc[]
+Returns the {wikipedia}/Hyperbolic_functions[hyperbolic cosine].
 
-*Description*
+*Supported types*
 
-Returns the https://en.wikipedia.org/wiki/Hyperbolic_functions[hyperbolic
-cosine].
+include::types/cosh.asciidoc[]
 
 *Example*
 

docs/reference/esql/functions/count-distinct.asciidoc

@@ -6,7 +6,7 @@
 
 [source,esql]
 ----
-COUNT_DISTINCT(column[, precision])
+COUNT_DISTINCT(column[, precision_threshold])
 ----
 
 *Parameters*
@@ -14,8 +14,10 @@ COUNT_DISTINCT(column[, precision])
 `column`::
 Column for which to count the number of distinct values.
 
-`precision`::
-Precision. Refer to <<esql-agg-count-distinct-approximate>>.
+`precision_threshold`::
+Precision threshold. Refer to <<esql-agg-count-distinct-approximate>>. The
+maximum supported value is 40000. Thresholds above this number will have the
+same effect as a threshold of 40000. The default value is 3000.
 
 *Description*
 
@@ -37,8 +39,12 @@ properties:
 
 include::../../aggregations/metrics/cardinality-aggregation.asciidoc[tag=explanation]
 
-The `COUNT_DISTINCT` function takes an optional second parameter to configure the
-precision.
+The `COUNT_DISTINCT` function takes an optional second parameter to configure
+the precision threshold. The precision_threshold options allows to trade memory
+for accuracy, and defines a unique count below which counts are expected to be
+close to accurate. Above this value, counts might become a bit more fuzzy. The
+maximum supported value is 40000, thresholds above this number will have the
+same effect as a threshold of 40000. The default value is `3000`.
 
 *Supported types*
 
@@ -55,7 +61,7 @@ include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct]
 include::{esql-specs}/stats_count_distinct.csv-spec[tag=count-distinct-result]
 |===
 
-With the optional second parameter to configure the precision:
+With the optional second parameter to configure the precision threshold:
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/e.asciidoc

@@ -1,10 +1,17 @@
 [discrete]
 [[esql-e]]
 === `E`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/e.svg[Embedded,opts=inline]
 
-{wikipedia}/E_(mathematical_constant)[Euler's number].
+*Description*
+
+Returns {wikipedia}/E_(mathematical_constant)[Euler's number].
+
+*Example*
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/ends_with.asciidoc

@@ -1,11 +1,30 @@
 [discrete]
 [[esql-ends_with]]
 === `ENDS_WITH`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/ends_with.svg[Embedded,opts=inline]
 
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+`suffix`::
+String expression. If `null`, the function returns `null`.
+
+*Description*
+
 Returns a boolean that indicates whether a keyword string ends with another
-string:
+string.
+
+*Supported types*
+
+include::types/ends_with.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -15,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=endsWith]
 |===
 include::{esql-specs}/string.csv-spec[tag=endsWith-result]
 |===
-
-Supported types:
-
-include::types/ends_with.asciidoc[]

docs/reference/esql/functions/floor.asciidoc

@@ -1,10 +1,30 @@
 [discrete]
 [[esql-floor]]
 === `FLOOR`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/floor.svg[Embedded,opts=inline]
 
-Round a number down to the nearest integer.
+*Parameters*
+
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
+Rounds a number down to the nearest integer.
+
+NOTE: This is a noop for `long` (including unsigned) and `integer`.
+      For `double` this picks the closest `double` value to the integer 
+      similar to {javadoc}/java.base/java/lang/Math.html#floor(double)[Math.floor].
+
+*Supported types*
+
+include::types/floor.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,11 +34,3 @@ include::{esql-specs}/math.csv-spec[tag=floor]
 |===
 include::{esql-specs}/math.csv-spec[tag=floor-result]
 |===
-
-NOTE: This is a noop for `long` (including unsigned) and `integer`.
-      For `double` this picks the the closest `double` value to the integer ala
-      {javadoc}/java.base/java/lang/Math.html#floor(double)[Math.floor].
-
-Supported types:
-
-include::types/floor.asciidoc[]

docs/reference/esql/functions/greatest.asciidoc

@@ -1,11 +1,34 @@
 [discrete]
 [[esql-greatest]]
 === `GREATEST`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/greatest.svg[Embedded,opts=inline]
 
-Returns the maximum value from many columns. This is similar to <<esql-mv_max>>
-except it's intended to run on multiple columns at once.
+*Parameters*
+
+`first`::
+First of the columns to evaluate.
+
+`rest`::
+The rest of the columns to evaluate.
+
+*Description*
+
+Returns the maximum value from multiple columns. This is similar to <<esql-mv_max>>
+except it is intended to run on multiple columns at once.
+
+NOTE: When run on `keyword` or `text` fields, this returns the last string
+      in alphabetical order. When run on `boolean` columns this will return
+      `true` if any values are `true`.
+
+*Supported types*
+
+include::types/greatest.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -15,11 +38,3 @@ include::{esql-specs}/math.csv-spec[tag=greatest]
 |===
 include::{esql-specs}/math.csv-spec[tag=greatest-result]
 |===
-
-NOTE: When run on `keyword` or `text` fields, this'll return the last string
-      in alphabetical order. When run on `boolean` columns this will return
-      `true` if any values are `true`.
-
-Supported types:
-
-include::types/greatest.asciidoc[]

docs/reference/esql/functions/least.asciidoc

@@ -1,11 +1,34 @@
 [discrete]
 [[esql-least]]
 === `LEAST`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/least.svg[Embedded,opts=inline]
 
-Returns the minimum value from many columns. This is similar to <<esql-mv_min>>
-except it's intended to run on multiple columns at once.
+*Parameters*
+
+`first`::
+First of the columns to evaluate.
+
+`rest`::
+The rest of the columns to evaluate.
+
+*Description*
+
+Returns the minimum value from multiple columns. This is similar to
+<<esql-mv_min>> except it is intended to run on multiple columns at once.
+
+NOTE: When run on `keyword` or `text` fields, this returns the first string
+      in alphabetical order. When run on `boolean` columns this will return
+      `false` if any values are `false`.
+
+*Supported types*
+
+include::types/least.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -15,11 +38,3 @@ include::{esql-specs}/math.csv-spec[tag=least]
 |===
 include::{esql-specs}/math.csv-spec[tag=least-result]
 |===
-
-NOTE: When run on `keyword` or `text` fields, this'll return the first string
-      in alphabetical order. When run on `boolean` columns this will return
-      `false` if any values are `false`.
-
-Supported types:
-
-include::types/least.asciidoc[]

docs/reference/esql/functions/left.asciidoc

@@ -1,10 +1,30 @@
 [discrete]
 [[esql-left]]
 === `LEFT`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/left.svg[Embedded,opts=inline]
 
-Return the substring that extracts 'length' chars from the 'string' starting from the left.
+*Parameters*
+
+`str`::
+The string from which to return a substring.
+
+`length`::
+The number of characters to return.
+
+*Description*
+
+Returns the substring that extracts 'length' chars from 'str' starting
+from the left.
+
+*Supported types*
+
+include::types/left.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=left]
 |===
 include::{esql-specs}/string.csv-spec[tag=left-result]
 |===
-
-Supported types:
-
-include::types/left.asciidoc[]

docs/reference/esql/functions/length.asciidoc

@@ -1,11 +1,30 @@
 [discrete]
 [[esql-length]]
 === `LENGTH`
-Returns the character length of a string.
+
+*Syntax*
 
 [source,esql]
 ----
-FROM employees
-| KEEP first_name, last_name, height
-| EVAL fn_length = LENGTH(first_name)
+LENGTH(str)
+----
+
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+*Description*
+
+Returns the character length of a string.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/eval.csv-spec[tag=length]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/eval.csv-spec[tag=length-result]
+|===

docs/reference/esql/functions/log10.asciidoc

@@ -1,13 +1,27 @@
 [discrete]
 [[esql-log10]]
 === `LOG10`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/log10.svg[Embedded,opts=inline]
 
-Returns the log base 10.  The input can be any numeric value, the return value
-is always a double.
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
 
-Logs of negative numbers are NaN. Logs of infinites are infinite, as is the log of 0.
+Returns the logarithm to base 10. The input can be any numeric value, the return
+value is always a double.
+
+Logs of 0, negative numbers, and infinites return `null` as well as a warning.
+
+*Supported types*
+
+include::types/log10.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -17,7 +31,3 @@ include::{esql-specs}/math.csv-spec[tag=log10]
 |===
 include::{esql-specs}/math.csv-spec[tag=log10-result]
 |===
-
-Supported types:
-
-include::types/log10.asciidoc[]

docs/reference/esql/functions/ltrim.asciidoc

@@ -1,11 +1,27 @@
 [discrete]
 [[esql-ltrim]]
 === `LTRIM`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/ltrim.svg[Embedded,opts=inline]
 
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+*Description*
+
 Removes leading whitespaces from strings.
 
+*Supported types*
+
+include::types/rtrim.asciidoc[]
+
+*Example*
+
 [source.merge.styled,esql]
 ----
 include::{esql-specs}/string.csv-spec[tag=ltrim]
@@ -13,8 +29,4 @@ include::{esql-specs}/string.csv-spec[tag=ltrim]
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
 include::{esql-specs}/string.csv-spec[tag=ltrim-result]
-|===
-
-Supported types:
-
-include::types/rtrim.asciidoc[]
+|===

docs/reference/esql/functions/max.asciidoc

@@ -1,7 +1,24 @@
 [discrete]
 [[esql-agg-max]]
 === `MAX`
-The maximum value of a numeric field.
+
+*Syntax*
+
+[source,esql]
+----
+MAX(column)
+----
+
+*Parameters*
+
+`column`::
+Column from which to return the maximum value.
+
+*Description*
+
+Returns the maximum value of a numeric column.
+
+*Example*
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/median-absolute-deviation.asciidoc

@@ -1,23 +1,29 @@
 [discrete]
 [[esql-agg-median-absolute-deviation]]
 === `MEDIAN_ABSOLUTE_DEVIATION`
-The median absolute deviation, a measure of variability. It is a robust
-statistic, meaning that it is useful for describing data that may have outliers,
-or may not be normally distributed. For such data it can be more descriptive than
-standard deviation.
 
-It is calculated as the median of each data point’s deviation from the median of
-the entire sample. That is, for a random variable `X`, the median absolute deviation
-is `median(|median(X) - Xi|)`.
+*Syntax*
 
-[source.merge.styled,esql]
+[source,esql]
 ----
-include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation]
+MEDIAN_ABSOLUTE_DEVIATION(column)
 ----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation-result]
-|===
+
+*Parameters*
+
+`column`::
+Column from which to return the median absolute deviation.
+
+*Description*
+
+Returns the median absolute deviation, a measure of variability. It is a robust
+statistic, meaning that it is useful for describing data that may have outliers,
+or may not be normally distributed. For such data it can be more descriptive
+than standard deviation.
+
+It is calculated as the median of each data point's deviation from the median of
+the entire sample. That is, for a random variable `X`, the median absolute
+deviation is `median(|median(X) - X|)`.
 
 NOTE: Like <<esql-agg-percentile>>, `MEDIAN_ABSOLUTE_DEVIATION` is
       <<esql-agg-percentile-approximate,usually approximate>>.
@@ -27,3 +33,14 @@ NOTE: Like <<esql-agg-percentile>>, `MEDIAN_ABSOLUTE_DEVIATION` is
 `MEDIAN_ABSOLUTE_DEVIATION` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic].
 This means you can get slightly different results using the same data.
 ====
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/stats_percentile.csv-spec[tag=median-absolute-deviation-result]
+|===

docs/reference/esql/functions/median.asciidoc

@@ -1,17 +1,23 @@
 [discrete]
 [[esql-agg-median]]
 === `MEDIAN`
-The value that is greater than half of all values and less than half of
-all values, also known as the 50% <<esql-agg-percentile>>.
 
-[source.merge.styled,esql]
+*Syntax*
+
+[source,esql]
 ----
-include::{esql-specs}/stats_percentile.csv-spec[tag=median]
+MEDIAN(column)
 ----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/stats_percentile.csv-spec[tag=median-result]
-|===
+
+*Parameters*
+
+`column`::
+Column from which to return the median value.
+
+*Description*
+
+Returns the value that is greater than half of all values and less than half of
+all values, also known as the 50% <<esql-agg-percentile>>.
 
 NOTE: Like <<esql-agg-percentile>>, `MEDIAN` is <<esql-agg-percentile-approximate,usually approximate>>.
 
@@ -20,3 +26,14 @@ NOTE: Like <<esql-agg-percentile>>, `MEDIAN` is <<esql-agg-percentile-approximat
 `MEDIAN` is also {wikipedia}/Nondeterministic_algorithm[non-deterministic].
 This means you can get slightly different results using the same data.
 ====
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/stats_percentile.csv-spec[tag=median]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/stats_percentile.csv-spec[tag=median-result]
+|===

docs/reference/esql/functions/min.asciidoc

@@ -1,7 +1,24 @@
 [discrete]
 [[esql-agg-min]]
 === `MIN`
-The minimum value of a numeric field.
+
+*Syntax*
+
+[source,esql]
+----
+MIN(column)
+----
+
+*Parameters*
+
+`column`::
+Column from which to return the minimum value.
+
+*Description*
+
+Returns the minimum value of a numeric column.
+
+*Example*
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/mv_avg.asciidoc

@@ -1,8 +1,29 @@
 [discrete]
 [[esql-mv_avg]]
 === `MV_AVG`
-Converts a multivalued field into a single valued field containing the average
-of all of the values. For example:
+
+*Syntax*
+
+[source,esql]
+----
+MV_AVG(expression)
+----
+
+*Parameters*
+
+`expression`::
+Multivalue expression.
+
+*Description*
+
+Converts a multivalued expression into a single valued column containing the
+average of all of the values.
+
+*Supported types*
+
+include::types/mv_avg.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -12,6 +33,3 @@ include::{esql-specs}/math.csv-spec[tag=mv_avg]
 |===
 include::{esql-specs}/math.csv-spec[tag=mv_avg-result]
 |===
-
-
-NOTE: The output type is always a `double` and the input type can be any number.

docs/reference/esql/functions/mv_concat.asciidoc

@@ -1,11 +1,30 @@
 [discrete]
 [[esql-mv_concat]]
 === `MV_CONCAT`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/mv_concat.svg[Embedded,opts=inline]
 
-Converts a multivalued string field into a single valued field containing the
-concatenation of all values separated by a delimiter:
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+`delim`::
+Delimiter.
+
+*Description*
+
+Converts a multivalued string expression into a single valued column containing
+the concatenation of all values separated by a delimiter.
+
+*Supported types*
+
+include::types/mv_concat.asciidoc[]
+
+*Examples*
 
 [source.merge.styled,esql]
 ----
@@ -16,7 +35,7 @@ include::{esql-specs}/string.csv-spec[tag=mv_concat]
 include::{esql-specs}/string.csv-spec[tag=mv_concat-result]
 |===
 
-If you want to concat non-string fields call <<esql-to_string>> on them first:
+To concat non-string columns, call <<esql-to_string>> first:
 
 [source.merge.styled,esql]
 ----
@@ -26,7 +45,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_concat-to_string]
 |===
 include::{esql-specs}/string.csv-spec[tag=mv_concat-to_string-result]
 |===
-
-Supported types:
-
-include::types/mv_concat.asciidoc[]

docs/reference/esql/functions/mv_count.asciidoc

@@ -1,11 +1,27 @@
 [discrete]
 [[esql-mv_count]]
 === `MV_COUNT`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/mv_count.svg[Embedded,opts=inline]
 
-Converts a multivalued field into a single valued field containing a count of the number
-of values:
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+*Description*
+
+Converts a multivalued expression into a single valued column containing a count
+of the number of values.
+
+*Supported types*
+
+include::types/mv_count.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -15,7 +31,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_count]
 |===
 include::{esql-specs}/string.csv-spec[tag=mv_count-result]
 |===
-
-Supported types:
-
-include::types/mv_count.asciidoc[]

docs/reference/esql/functions/mv_dedupe.asciidoc

@@ -1,10 +1,28 @@
 [discrete]
 [[esql-mv_dedupe]]
 === `MV_DEDUPE`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/mv_dedupe.svg[Embedded,opts=inline]
 
-Removes duplicates from a multivalued field. For example:
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+*Description*
+
+Removes duplicates from a multivalue expression.
+
+NOTE: `MV_DEDUPE` may, but won't always, sort the values in the column.
+
+*Supported types*
+
+include::types/mv_dedupe.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,9 +32,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_dedupe]
 |===
 include::{esql-specs}/string.csv-spec[tag=mv_dedupe-result]
 |===
-
-Supported types:
-
-include::types/mv_dedupe.asciidoc[]
-
-NOTE: `MV_DEDUPE` may, but won't always, sort the values in the field.

docs/reference/esql/functions/mv_first.asciidoc

@@ -1,11 +1,34 @@
 [discrete]
 [[esql-mv_first]]
 === `MV_FIRST`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/mv_first.svg[Embedded,opts=inline]
 
-Converts a multivalued field into a single valued field containing the first value. This is most
-useful when reading from a function that emits multivalued fields in a known order like <<esql-split>>:
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+*Description*
+
+Converts a multivalued expression into a single valued column containing the
+first value. This is most useful when reading from a function that emits
+multivalued columns in a known order like <<esql-split>>.
+
+The order that <<esql-multivalued-fields, multivalued fields>> are read from
+underlying storage is not guaranteed. It is *frequently* ascending, but don't
+rely on that. If you need the minimum value use <<esql-mv_min>> instead of
+`MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn't a
+performance benefit to `MV_FIRST`.
+
+*Supported types*
+
+include::types/mv_first.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -15,13 +38,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_first]
 |===
 include::{esql-specs}/string.csv-spec[tag=mv_first-result]
 |===
-
-The order that <<esql-multivalued-fields, multivalued fields>> are read from underlying storage is not
-guaranteed. It is *frequently* ascending, but don't rely on that. If you need the minimum field value
-use <<esql-mv_min>> instead of `MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn't
-a performance benefit to `MV_FIRST`. `MV_FIRST` is mostly useful with functions that create multivalued
-fields like `SPLIT`.
-
-Supported types:
-
-include::types/mv_first.asciidoc[]

docs/reference/esql/functions/mv_last.asciidoc

@@ -1,11 +1,34 @@
 [discrete]
 [[esql-mv_last]]
 === `MV_LAST`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/mv_last.svg[Embedded,opts=inline]
 
-Converts a multivalued field into a single valued field containing the last value. This is most
-useful when reading from a function that emits multivalued fields in a known order like <<esql-split>>:
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+*Description*
+
+Converts a multivalue expression into a single valued column containing the last
+value. This is most useful when reading from a function that emits multivalued
+columns in a known order like <<esql-split>>.
+
+The order that <<esql-multivalued-fields, multivalued fields>> are read from
+underlying storage is not guaranteed. It is *frequently* ascending, but don't
+rely on that. If you need the maximum value use <<esql-mv_max>> instead of
+`MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn't a
+performance benefit to `MV_LAST`.
+
+*Supported types*
+
+include::types/mv_last.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -15,13 +38,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_last]
 |===
 include::{esql-specs}/string.csv-spec[tag=mv_last-result]
 |===
-
-The order that <<esql-multivalued-fields, multivalued fields>> are read from underlying storage is not
-guaranteed. It is *frequently* ascending, but don't rely on that. If you need the maximum field value
-use <<esql-mv_max>> instead of `MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn't
-a performance benefit to `MV_LAST`. `MV_LAST` is mostly useful with functions that create multivalued
-fields like `SPLIT`.
-
-Supported types:
-
-include::types/mv_last.asciidoc[]

docs/reference/esql/functions/mv_max.asciidoc

@@ -1,10 +1,27 @@
 [discrete]
 [[esql-mv_max]]
 === `MV_MAX`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/mv_max.svg[Embedded,opts=inline]
 
-Converts a multivalued field into a single valued field containing the maximum value. For example:
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+*Description*
+
+Converts a multivalued expression into a single valued column containing the
+maximum value.
+
+*Supported types*
+
+include::types/mv_max.asciidoc[]
+
+*Examples*
 
 [source.merge.styled,esql]
 ----
@@ -15,8 +32,8 @@ include::{esql-specs}/math.csv-spec[tag=mv_max]
 include::{esql-specs}/math.csv-spec[tag=mv_max-result]
 |===
 
-It can be used by any field type, including `keyword` fields. In that case picks the
-last string, comparing their utf-8 representation byte by byte:
+It can be used by any column type, including `keyword` columns. In that case
+it picks the last string, comparing their utf-8 representation byte by byte:
 
 [source.merge.styled,esql]
 ----
@@ -26,7 +43,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_max]
 |===
 include::{esql-specs}/string.csv-spec[tag=mv_max-result]
 |===
-
-Supported types:
-
-include::types/mv_max.asciidoc[]

docs/reference/esql/functions/mv_median.asciidoc

@@ -1,7 +1,27 @@
 [discrete]
 [[esql-mv_median]]
 === `MV_MEDIAN`
-Converts a multivalued field into a single valued field containing the median value. For example:
+
+[source,esql]
+----
+MV_MEDIAN(v)
+----
+
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+*Description*
+
+Converts a multivalued column into a single valued column containing the median
+value.
+
+*Supported types*
+
+include::types/mv_median.asciidoc[]
+
+*Examples*
 
 [source.merge.styled,esql]
 ----
@@ -12,9 +32,9 @@ include::{esql-specs}/math.csv-spec[tag=mv_median]
 include::{esql-specs}/math.csv-spec[tag=mv_median-result]
 |===
 
-It can be used by any numeric field type and returns a value of the same type. If the
-row has an even number of values for a column the result will be the average of the
-middle two entries. If the field is not floating point then the average rounds *down*:
+If the row has an even number of values for a column, the result will be the
+average of the middle two entries. If the column is not floating point, the
+average rounds *down*:
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/mv_min.asciidoc

@@ -1,10 +1,27 @@
 [discrete]
 [[esql-mv_min]]
 === `MV_MIN`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/mv_min.svg[Embedded,opts=inline]
 
-Converts a multivalued field into a single valued field containing the minimum value. For example:
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+*Description*
+
+Converts a multivalued expression into a single valued column containing the
+minimum value.
+
+*Supported types*
+
+include::types/mv_min.asciidoc[]
+
+*Examples*
 
 [source.merge.styled,esql]
 ----
@@ -15,8 +32,8 @@ include::{esql-specs}/math.csv-spec[tag=mv_min]
 include::{esql-specs}/math.csv-spec[tag=mv_min-result]
 |===
 
-It can be used by any field type, including `keyword` fields. In that case picks the
-first string, comparing their utf-8 representation byte by byte:
+It can be used by any column type, including `keyword` columns. In that case,
+it picks the first string, comparing their utf-8 representation byte by byte:
 
 [source.merge.styled,esql]
 ----
@@ -26,7 +43,3 @@ include::{esql-specs}/string.csv-spec[tag=mv_min]
 |===
 include::{esql-specs}/string.csv-spec[tag=mv_min-result]
 |===
-
-Supported types:
-
-include::types/mv_min.asciidoc[]

docs/reference/esql/functions/mv_sum.asciidoc

@@ -1,8 +1,27 @@
 [discrete]
 [[esql-mv_sum]]
 === `MV_SUM`
-Converts a multivalued field into a single valued field containing the sum
-of all of the values. For example:
+
+[source,esql]
+----
+MV_SUM(v)
+----
+
+*Parameters*
+
+`v`::
+Multivalue expression.
+
+*Description*
+
+Converts a multivalued column into a single valued column containing the sum
+of all of the values.
+
+*Supported types*
+
+include::types/mv_sum.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -12,5 +31,3 @@ include::{esql-specs}/math.csv-spec[tag=mv_sum]
 |===
 include::{esql-specs}/math.csv-spec[tag=mv_sum-result]
 |===
-
-NOTE: The input type can be any number and the output type is the same as the input type.

docs/reference/esql/functions/now.asciidoc

@@ -1,9 +1,28 @@
 [discrete]
 [[esql-now]]
 === `NOW`
+
+*Syntax*
+
+[source,esql]
+----
+NOW()
+----
+
+*Description*
+
 Returns current date and time.
 
+*Example*
+
 [source,esql]
 ----
-ROW current_date = NOW()
+include::{esql-specs}/date.csv-spec[tag=docsNow]
+----
+
+To retrieve logs from the last hour:
+
+[source,esql]
 ----
+include::{esql-specs}/date.csv-spec[tag=docsNowWhere]
+----

docs/reference/esql/functions/percentile.asciidoc

@@ -1,18 +1,27 @@
 [discrete]
 [[esql-agg-percentile]]
 === `PERCENTILE`
-The value at which a certain percentage of observed values occur. For example,
-the 95th percentile is the value which is greater than 95% of the observed values and
-the 50th percentile is the <<esql-agg-median>>.
 
-[source.merge.styled,esql]
+*Syntax*
+
+[source,esql]
 ----
-include::{esql-specs}/stats_percentile.csv-spec[tag=percentile]
+PERCENTILE(column, percentile)
 ----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/stats_percentile.csv-spec[tag=percentile-result]
-|===
+
+*Parameters*
+
+`column`::
+Column to convert from multiple values to single value.
+
+`percentile`::
+A constant numeric expression.
+
+*Description*
+
+Returns the value at which a certain percentage of observed values occur. For
+example, the 95th percentile is the value which is greater than 95% of the
+observed values and the 50th percentile is the <<esql-agg-median>>.
 
 [discrete]
 [[esql-agg-percentile-approximate]]
@@ -26,5 +35,13 @@ include::../../aggregations/metrics/percentile-aggregation.asciidoc[tag=approxim
 This means you can get slightly different results using the same data.
 ====
 
+*Example*
 
-
+[source.merge.styled,esql]
+----
+include::{esql-specs}/stats_percentile.csv-spec[tag=percentile]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/stats_percentile.csv-spec[tag=percentile-result]
+|===

docs/reference/esql/functions/pi.asciidoc

@@ -1,10 +1,17 @@
 [discrete]
 [[esql-pi]]
 === `PI`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/pi.svg[Embedded,opts=inline]
 
-The {wikipedia}/Pi[ratio] of a circle's circumference to its diameter.
+*Description*
+
+Returns the {wikipedia}/Pi[ratio] of a circle's circumference to its diameter.
+
+*Example*
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/pow.asciidoc

@@ -1,12 +1,31 @@
 [discrete]
 [[esql-pow]]
 === `POW`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/pow.svg[Embedded,opts=inline]
 
-Returns the value of a base (first argument) raised to the power of an exponent (second argument).
-Both arguments must be numeric. The output is always a double.  Note that it is still possible to overflow
-a double result here; in that case, null will be returned.
+*Parameters*
+
+`base`::
+Numeric expression. If `null`, the function returns `null`.
+
+`exponent`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
+Returns the value of `base` raised to the power of `exponent`. Both arguments
+must be numeric. The output is always a double.  Note that it is still possible
+to overflow a double result here; in that case, null will be returned.
+
+*Supported types*
+
+include::types/pow.asciidoc[]
+
+*Examples*
 
 [source.merge.styled,esql]
 ----
@@ -17,10 +36,6 @@ include::{esql-specs}/math.csv-spec[tag=powDI]
 include::{esql-specs}/math.csv-spec[tag=powDI-result]
 |===
 
-
-[discrete]
-==== Fractional exponents
-
 The exponent can be a fraction, which is similar to performing a root.
 For example, the exponent of `0.5` will give the square root of the base:
 
@@ -32,10 +47,3 @@ include::{esql-specs}/math.csv-spec[tag=powID-sqrt]
 |===
 include::{esql-specs}/math.csv-spec[tag=powID-sqrt-result]
 |===
-
-[discrete]
-==== Table of supported input and output types
-
-For clarity, the following table describes the output result type for all combinations of numeric input types:
-
-include::types/pow.asciidoc[]

docs/reference/esql/functions/replace.asciidoc

@@ -1,11 +1,38 @@
 [discrete]
 [[esql-replace]]
 === `REPLACE`
-The function substitutes in the string (1st argument) any match of the regular expression (2nd argument) with the replacement string (3rd argument).
 
-If any of the arguments are `NULL`, the result is `NULL`.
+*Syntax*
 
-. This example replaces an occurrence of the word "World" with the word "Universe":
+[.text-center]
+image::esql/functions/signature/replace.svg[Embedded,opts=inline]
+
+*Parameters*
+
+`str`::
+String expression.
+
+`regex`::
+Regular expression.
+
+`newStr`::
+Replacement string.
+
+*Description*
+
+The function substitutes in the string `str` any match of the regular expression
+`regex` with the replacement string `newStr`.
+
+If any of the arguments is `null`, the result is `null`.
+
+*Supported types*
+
+include::types/replace.asciidoc[]
+
+*Example*
+
+This example replaces any occurrence of the word "World" with the word
+"Universe":
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/right.asciidoc

@@ -1,10 +1,30 @@
 [discrete]
 [[esql-right]]
 === `RIGHT`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/right.svg[Embedded,opts=inline]
 
-Return the substring that extracts 'length' chars from the 'string' starting from the right.
+*Parameters*
+
+`str`::
+The string from which to returns a substring.
+
+`length`::
+The number of characters to return.
+
+*Description*
+
+Return the substring that extracts 'length' chars from 'str' starting
+from the right.
+
+*Supported types*
+
+include::types/right.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +34,3 @@ include::{esql-specs}/string.csv-spec[tag=right]
 |===
 include::{esql-specs}/string.csv-spec[tag=right-result]
 |===
-
-Supported types:
-
-include::types/right.asciidoc[]

docs/reference/esql/functions/round.asciidoc

@@ -1,10 +1,31 @@
 [discrete]
 [[esql-round]]
 === `ROUND`
+*Syntax*
+
+[.text-center]
+image::esql/functions/signature/round.svg[Embedded,opts=inline]
+
+*Parameters*
+
+`value`::
+Numeric expression. If `null`, the function returns `null`.
+
+`decimals`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
 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.
 
+*Supported types*
+
+include::types/round.asciidoc[]
+
+*Example*
+
 [source.merge.styled,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=round]

docs/reference/esql/functions/rtrim.asciidoc

@@ -1,11 +1,27 @@
 [discrete]
 [[esql-rtrim]]
 === `RTRIM`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/rtrim.svg[Embedded,opts=inline]
 
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+*Description*
+
 Removes trailing whitespaces from strings.
 
+*Supported types*
+
+include::types/rtrim.asciidoc[]
+
+*Example*
+
 [source.merge.styled,esql]
 ----
 include::{esql-specs}/string.csv-spec[tag=rtrim]
@@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=rtrim]
 |===
 include::{esql-specs}/string.csv-spec[tag=rtrim-result]
 |===
-
-Supported types:
-
-include::types/rtrim.asciidoc[]

docs/reference/esql/functions/sin.asciidoc

@@ -1,10 +1,27 @@
 [discrete]
 [[esql-sin]]
 === `SIN`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/sin.svg[Embedded,opts=inline]
 
-https://en.wikipedia.org/wiki/Sine_and_cosine[Sine] trigonometric function. Input expected in radians.
+*Parameters*
+
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
+{wikipedia}/Sine_and_cosine[Sine] trigonometric function. Input expected in
+radians.
+
+*Supported types*
+
+include::types/sin.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=sin]
 |===
 include::{esql-specs}/floats.csv-spec[tag=sin-result]
 |===
-
-Supported types:
-
-include::types/sin.asciidoc[]

docs/reference/esql/functions/sinh.asciidoc

@@ -1,10 +1,26 @@
 [discrete]
 [[esql-sinh]]
 === `SINH`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/sinh.svg[Embedded,opts=inline]
 
-https://en.wikipedia.org/wiki/Hyperbolic_functions[Sine] hyperbolic function.
+*Parameters*
+
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
+{wikipedia}/Hyperbolic_functions[Sine] hyperbolic function.
+
+*Supported types*
+
+include::types/sinh.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +30,3 @@ include::{esql-specs}/floats.csv-spec[tag=sinh]
 |===
 include::{esql-specs}/floats.csv-spec[tag=sinh-result]
 |===
-
-Supported types:
-
-include::types/sinh.asciidoc[]

docs/reference/esql/functions/split.asciidoc

@@ -1,18 +1,33 @@
 [discrete]
 [[esql-split]]
 === `SPLIT`
-Split a single valued string into multiple strings. For example:
 
-[source,esql]
+[.text-center]
+image::esql/functions/signature/split.svg[Embedded,opts=inline]
+
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+`delim`::
+Delimiter. Only single byte delimiters are currently supported.
+
+*Description*
+
+Splits a single valued string into multiple strings.
+
+*Supported types*
+
+include::types/split.asciidoc[]
+
+*Example*
+
+[source.merge.styled,esql]
 ----
 include::{esql-specs}/string.csv-spec[tag=split]
 ----
-
-Which splits `"foo;bar;baz;qux;quux;corge"` on `;` and returns an array:
-
-[%header,format=dsv,separator=|]
+[%header.monospaced.styled,format=dsv,separator=|]
 |===
 include::{esql-specs}/string.csv-spec[tag=split-result]
 |===
-
-WARNING: Only single byte delimiters are currently supported.

docs/reference/esql/functions/sqrt.asciidoc

@@ -1,13 +1,30 @@
 [discrete]
 [[esql-sqrt]]
 === `SQRT`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/sqrt.svg[Embedded,opts=inline]
 
-Returns the square root of a number.  The input can be any numeric value, the return value
-is always a double.
+*Parameters*
+
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
+Returns the square root of a number.  The input can be any numeric value, the
+return value is always a double.
+
+Square roots of negative numbers are NaN. Square roots of infinites are
+infinite.
 
-Square roots of negative numbers are NaN. Square roots of infinites are infinite.
+*Supported types*
+
+include::types/sqrt.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -17,7 +34,3 @@ include::{esql-specs}/math.csv-spec[tag=sqrt]
 |===
 include::{esql-specs}/math.csv-spec[tag=sqrt-result]
 |===
-
-Supported types:
-
-include::types/sqrt.asciidoc[]

docs/reference/esql/functions/starts_with.asciidoc

@@ -1,11 +1,30 @@
 [discrete]
 [[esql-starts_with]]
 === `STARTS_WITH`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/starts_with.svg[Embedded,opts=inline]
 
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+`prefix`::
+String expression. If `null`, the function returns `null`.
+
+*Description*
+
 Returns a boolean that indicates whether a keyword string starts with another
-string:
+string.
+
+*Supported types*
+
+include::types/starts_with.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -15,7 +34,3 @@ include::{esql-specs}/docs.csv-spec[tag=startsWith]
 |===
 include::{esql-specs}/docs.csv-spec[tag=startsWith-result]
 |===
-
-Supported types:
-
-include::types/starts_with.asciidoc[]

docs/reference/esql/functions/substring.asciidoc

@@ -1,8 +1,36 @@
 [discrete]
 [[esql-substring]]
 === `SUBSTRING`
+
+*Syntax*
+
+[.text-center]
+image::esql/functions/signature/substring.svg[Embedded,opts=inline]
+
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+`start`::
+Start position.
+
+`length`::
+Length of the substring from the start position. Optional; if omitted, all
+positions after `start` are returned.
+
+*Description*
+
 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:
+length.
+
+*Supported types*
+
+include::types/substring.asciidoc[]
+
+*Examples*
+
+This example returns the first three characters of every last name:
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/sum.asciidoc

@@ -1,7 +1,22 @@
 [discrete]
 [[esql-agg-sum]]
 === `SUM`
-The sum of a numeric field.
+
+*Syntax*
+
+[source,esql]
+----
+SUM(column)
+----
+
+`column`::
+Numeric column.
+
+*Description*
+
+Returns the sum of a numeric column.
+
+*Example*
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/tan.asciidoc

@@ -1,10 +1,27 @@
 [discrete]
 [[esql-tan]]
 === `TAN`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/tan.svg[Embedded,opts=inline]
 
-https://en.wikipedia.org/wiki/Sine_and_cosine[Tangent] trigonometric function. Input expected in radians.
+*Parameters*
+
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
+{wikipedia}/Sine_and_cosine[Tangent] trigonometric function. Input expected in
+radians.
+
+*Supported types*
+
+include::types/tan.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +31,3 @@ include::{esql-specs}/floats.csv-spec[tag=tan]
 |===
 include::{esql-specs}/floats.csv-spec[tag=tan-result]
 |===
-
-Supported types:
-
-include::types/tan.asciidoc[]

docs/reference/esql/functions/tanh.asciidoc

@@ -1,10 +1,26 @@
 [discrete]
 [[esql-tanh]]
 === `TANH`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/tanh.svg[Embedded,opts=inline]
 
-https://en.wikipedia.org/wiki/Hyperbolic_functions[Tangent] hyperbolic function.
+*Parameters*
+
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
+{wikipedia}/Hyperbolic_functions[Tangent] hyperbolic function.
+
+*Supported types*
+
+include::types/tanh.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +30,3 @@ include::{esql-specs}/floats.csv-spec[tag=tanh]
 |===
 include::{esql-specs}/floats.csv-spec[tag=tanh-result]
 |===
-
-Supported types:
-
-include::types/tanh.asciidoc[]

docs/reference/esql/functions/tau.asciidoc

@@ -1,10 +1,18 @@
 [discrete]
 [[esql-tau]]
 === `TAU`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/tau.svg[Embedded,opts=inline]
 
-The https://tauday.com/tau-manifesto[ratio] of a circle's circumference to its radius.
+*Description*
+
+Returns the https://tauday.com/tau-manifesto[ratio] of a circle's circumference
+to its radius.
+
+*Example*
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/to_boolean.asciidoc

@@ -1,14 +1,39 @@
 [discrete]
 [[esql-to_boolean]]
 === `TO_BOOLEAN`
-Converts an input value to a boolean value.
 
-The input can be a single- or multi-valued field or an expression. The input
-type must be of a string or numeric type.
+*Alias*
+
+`TO_BOOL`
+
+*Syntax*
+
+[source,esql]
+----
+TO_BOOLEAN(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
+Converts an input value to a boolean value.
 
 A string value of *"true"* will be case-insensitive converted to the Boolean
 *true*. For anything else, including the empty string, the function will
-return *false*. For example:
+return *false*.
+
+The numerical value of *0* will be converted to *false*, anything else will be
+converted to *true*.
+
+*Supported types*
+
+The input type must be of a string or numeric type.
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -18,8 +43,3 @@ include::{esql-specs}/boolean.csv-spec[tag=to_boolean]
 |===
 include::{esql-specs}/boolean.csv-spec[tag=to_boolean-result]
 |===
-
-The numerical value of *0* will be converted to *false*, anything else will be
-converted to *true*.
-
-Alias: TO_BOOL

docs/reference/esql/functions/to_cartesianpoint.asciidoc

@@ -1,13 +1,31 @@
 [discrete]
 [[esql-to_cartesianpoint]]
 === `TO_CARTESIANPOINT`
-Converts an input value to a `point` value.
 
-The input can be a single- or multi-valued field or an expression.
-The input type must be a string or a cartesian `point`.
+*Syntax*
+
+[source,esql]
+----
+TO_CARTESIANPOINT(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
+Converts an input value to a `point` value.
 
 A string will only be successfully converted if it respects the
-https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT Point] format:
+{wikipedia}/Well-known_text_representation_of_geometry[WKT Point] format.
+
+*Supported types*
+
+include::types/to_cartesianpoint.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -17,7 +35,3 @@ include::{esql-specs}/spatial.csv-spec[tag=to_cartesianpoint-str]
 |===
 include::{esql-specs}/spatial.csv-spec[tag=to_cartesianpoint-str-result]
 |===
-
-Supported types:
-
-include::types/to_cartesianpoint.asciidoc[]

docs/reference/esql/functions/to_cartesianshape.asciidoc

@@ -1,13 +1,32 @@
 [discrete]
 [[esql-to_cartesianshape]]
 === `TO_CARTESIANSHAPE`
-Converts an input value to a `cartesian_shape` value.
 
-The input can be a single- or multi-valued field or an expression.
+*Syntax*
+
+[source,esql]
+----
+TO_CARTESIANSHAPE(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
 The input type must be a string or a `cartesian_shape`.
 
+*Description*
+
+Converts an input value to a `cartesian_shape` value.
+
 A string will only be successfully converted if it respects the
-https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT] format:
+{wikipedia}/Well-known_text_representation_of_geometry[WKT] format.
+
+*Supported types*
+
+include::types/to_cartesianshape.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -17,7 +36,3 @@ include::{esql-specs}/spatial_shapes.csv-spec[tag=to_cartesianshape-str]
 |===
 include::{esql-specs}/spatial_shapes.csv-spec[tag=to_cartesianshape-str-result]
 |===
-
-Supported types:
-
-include::types/to_cartesianshape.asciidoc[]

docs/reference/esql/functions/to_datetime.asciidoc

@@ -1,13 +1,36 @@
 [discrete]
 [[esql-to_datetime]]
 === `TO_DATETIME`
-Converts an input value to a date value.
 
-The input can be a single- or multi-valued field or an expression. The input
-type must be of a string or numeric type.
+*Alias*
+
+`TO_DT`
+
+*Syntax*
+
+[source,esql]
+----
+TO_DATETIME(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
+Converts an input value to a date value.
 
 A string will only be successfully converted if it's respecting the format
-`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` (to convert dates in other formats, use <<esql-date_parse>>). For example:
+`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. To convert dates in other formats, use
+<<esql-date_parse>>.
+
+*Supported types*
+
+The input type must be of a string or numeric type.
+
+*Examples*
 
 [source.merge.styled,esql]
 ----
@@ -30,10 +53,8 @@ A following header will contain the failure reason and the offending value:
 
 `"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"`
 
-
 If the input parameter is of a numeric type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch].
-For example:
+milliseconds since the {wikipedia}/Unix_time[Unix epoch]. For example:
 
 [source.merge.styled,esql]
 ----
@@ -43,5 +64,3 @@ include::{esql-specs}/date.csv-spec[tag=to_datetime-int]
 |===
 include::{esql-specs}/date.csv-spec[tag=to_datetime-int-result]
 |===
-
-Alias: TO_DT

docs/reference/esql/functions/to_degrees.asciidoc

@@ -1,13 +1,29 @@
 [discrete]
 [[esql-to_degrees]]
 === `TO_DEGREES`
-Converts a number in https://en.wikipedia.org/wiki/Radian[radians]
-to https://en.wikipedia.org/wiki/Degree_(angle)[degrees].
 
-The input can be a single- or multi-valued field or an expression. The input
-type must be of a numeric type and result is always `double`.
+*Syntax*
 
-Example:
+[source,esql]
+----
+TO_DEGREES(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
+Converts a number in {wikipedia}/Radian[radians] to
+{wikipedia}/Degree_(angle)[degrees].
+
+*Supported types*
+
+The input type must be of a numeric type and result is always `double`.
+
+*Example*
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/to_double.asciidoc

@@ -1,12 +1,37 @@
 [discrete]
 [[esql-to_double]]
 === `TO_DOUBLE`
+
+*Alias*
+
+`TO_DBL`
+
+*Syntax*
+
+[source,esql]
+----
+TO_DOUBLE(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
 Converts an input value to a double value.
 
-The input can be a single- or multi-valued field or an expression. The input
-type must be of a boolean, date, string or numeric type.
+If the input parameter is of a date type, its value will be interpreted as
+milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to double.
 
-Example:
+Boolean *true* will be converted to double *1.0*, *false* to *0.0*.
+
+*Supported types*
+
+The input type must be of a boolean, date, string or numeric type.
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -17,22 +42,13 @@ include::{esql-specs}/floats.csv-spec[tag=to_double-str]
 include::{esql-specs}/floats.csv-spec[tag=to_double-str-result]
 |===
 
-Note that in this example, the last conversion of the string isn't
-possible. When this happens, the result is a *null* value. In this case a
-_Warning_ header is added to the response. The header will provide information
-on the source of the failure:
+Note that in this example, the last conversion of the string isn't possible.
+When this happens, the result is a *null* value. In this case a _Warning_ header
+is added to the response. The header will provide information on the source of
+the failure:
 
 `"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. Only first 20 failures recorded."`
 
 A following header will contain the failure reason and the offending value:
 
 `"java.lang.NumberFormatException: For input string: \"foo\""`
-
-
-If the input parameter is of a date type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
-converted to double.
-
-Boolean *true* will be converted to double *1.0*, *false* to *0.0*.
-
-Alias: TO_DBL

docs/reference/esql/functions/to_geopoint.asciidoc

@@ -1,13 +1,32 @@
 [discrete]
 [[esql-to_geopoint]]
 === `TO_GEOPOINT`
-Converts an input value to a `geo_point` value.
 
-The input can be a single- or multi-valued field or an expression.
+*Syntax*
+
+[source,esql]
+----
+TO_GEOPOINT(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
 The input type must be a string or a `geo_point`.
 
+*Description*
+
+Converts an input value to a `geo_point` value.
+
+*Supported types*
+
+include::types/to_geopoint.asciidoc[]
+
 A string will only be successfully converted if it respects the
-https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT Point] format:
+{wikipedia}/Well-known_text_representation_of_geometry[WKT Point] format.
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -17,7 +36,3 @@ include::{esql-specs}/spatial.csv-spec[tag=to_geopoint-str]
 |===
 include::{esql-specs}/spatial.csv-spec[tag=to_geopoint-str-result]
 |===
-
-Supported types:
-
-include::types/to_geopoint.asciidoc[]

docs/reference/esql/functions/to_geoshape.asciidoc

@@ -1,13 +1,32 @@
 [discrete]
 [[esql-to_geoshape]]
 === `TO_GEOSHAPE`
-Converts an input value to a `geo_point` value.
 
-The input can be a single- or multi-valued field or an expression.
-The input type must be a string or a `geo_point`.
+*Syntax*
+
+[source,esql]
+----
+TO_GEOPOINT(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+The input type must be a string or a `geo_shape`.
+
+*Description*
+
+Converts an input value to a `geo_shape` value.
 
 A string will only be successfully converted if it respects the
-https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT] format:
+{wikipedia}/Well-known_text_representation_of_geometry[WKT] format.
+
+*Supported types*
+
+include::types/to_geoshape.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -17,7 +36,3 @@ include::{esql-specs}/spatial_shapes.csv-spec[tag=to_geoshape-str]
 |===
 include::{esql-specs}/spatial_shapes.csv-spec[tag=to_geoshape-str-result]
 |===
-
-Supported types:
-
-include::types/to_geoshape.asciidoc[]

docs/reference/esql/functions/to_integer.asciidoc

@@ -1,12 +1,37 @@
 [discrete]
 [[esql-to_integer]]
 === `TO_INTEGER`
+
+*Alias*
+
+`TO_INT`
+
+*Syntax*
+
+[source,esql]
+----
+TO_INTEGER(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
 Converts an input value to an integer  value.
 
-The input can be a single- or multi-valued field or an expression. The input
-type must be of a boolean, date, string or numeric type.
+If the input parameter is of a date type, its value will be interpreted as
+milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to integer.
 
-Example:
+Boolean *true* will be converted to integer *1*, *false* to *0*.
+
+*Supported types*
+
+The input type must be of a boolean, date, string or numeric type.
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -27,12 +52,3 @@ provide information on the source of the failure:
 A following header will contain the failure reason and the offending value:
 
 `"org.elasticsearch.xpack.ql.InvalidArgumentException: [501379200000] out of [integer] range"`
-
-
-If the input parameter is of a date type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
-converted to integer.
-
-Boolean *true* will be converted to integer *1*, *false* to *0*.
-
-Alias: TO_INT

docs/reference/esql/functions/to_ip.asciidoc

@@ -1,11 +1,24 @@
 [discrete]
 [[esql-to_ip]]
 === `TO_IP`
-Converts an input string to an IP value.
 
-The input can be a single- or multi-valued field or an expression.
+*Syntax*
+
+[source,esql]
+----
+TO_IP(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
+Converts an input string to an IP value.
 
-Example:
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -16,10 +29,10 @@ include::{esql-specs}/ip.csv-spec[tag=to_ip]
 include::{esql-specs}/ip.csv-spec[tag=to_ip-result]
 |===
 
-Note that in the example above the last conversion of the string isn't
-possible. When this happens, the result is a *null* value. In this case a
-_Warning_ header is added to the response. The header will provide information
-on the source of the failure:
+Note that in this example, the last conversion of the string isn't possible.
+When this happens, the result is a *null* value. In this case a _Warning_ header
+is added to the response. The header will provide information on the source of
+the failure:
 
 `"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."`
 

docs/reference/esql/functions/to_long.asciidoc

@@ -1,12 +1,33 @@
 [discrete]
 [[esql-to_long]]
 === `TO_LONG`
+
+*Syntax*
+
+[source,esql]
+----
+TO_LONG(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
 Converts an input value to a long value.
 
-The input can be a single- or multi-valued field or an expression. The input
-type must be of a boolean, date, string or numeric type.
+If the input parameter is of a date type, its value will be interpreted as
+milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to long.
+
+Boolean *true* will be converted to long *1*, *false* to *0*.
+
+*Supported types*
 
-Example:
+The input type must be of a boolean, date, string or numeric type.
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -27,10 +48,3 @@ on the source of the failure:
 A following header will contain the failure reason and the offending value:
 
 `"java.lang.NumberFormatException: For input string: \"foo\""`
-
-
-If the input parameter is of a date type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
-converted to long.
-
-Boolean *true* will be converted to long *1*, *false* to *0*.

docs/reference/esql/functions/to_lower.asciidoc

@@ -1,10 +1,26 @@
 [discrete]
 [[esql-to_lower]]
 === `TO_LOWER`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/to_lower.svg[Embedded,opts=inline]
 
-Returns a new string representing the input string converted to lower case
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+*Description*
+
+Returns a new string representing the input string converted to lower case.
+
+*Supported types*
+
+include::types/to_lower.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=to_lower]
 |===
 include::{esql-specs}/string.csv-spec[tag=to_lower-result]
 |===
-
-Supported types:
-
-include::types/to_lower.asciidoc[]

docs/reference/esql/functions/to_radians.asciidoc

@@ -1,13 +1,29 @@
 [discrete]
 [[esql-to_radians]]
 === `TO_RADIANS`
-Converts a number in https://en.wikipedia.org/wiki/Degree_(angle)[degrees] to
-https://en.wikipedia.org/wiki/Radian[radians].
 
-The input can be a single- or multi-valued field or an expression. The input
-type must be of a numeric type and result is always `double`.
+*Syntax*
 
-Example:
+[source,esql]
+----
+TO_RADIANS(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
+Converts a number in {wikipedia}/Degree_(angle)[degrees] to
+{wikipedia}/Radian[radians].
+
+*Supported types*
+
+The input type must be of a numeric type and result is always `double`.
+
+*Example*
 
 [source.merge.styled,esql]
 ----

docs/reference/esql/functions/to_string.asciidoc

@@ -1,10 +1,28 @@
 [discrete]
 [[esql-to_string]]
 === `TO_STRING`
+
+*Alias*
+
+`TO_STR`
+
 [.text-center]
 image::esql/functions/signature/to_string.svg[Embedded,opts=inline]
 
-Converts a field into a string. For example:
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
+Converts an input value into a string.
+
+*Supported types*
+
+include::types/to_string.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -25,9 +43,3 @@ include::{esql-specs}/string.csv-spec[tag=to_string_multivalue]
 |===
 include::{esql-specs}/string.csv-spec[tag=to_string_multivalue-result]
 |===
-
-Alias: TO_STR
-
-Supported types:
-
-include::types/to_string.asciidoc[]

docs/reference/esql/functions/to_unsigned_long.asciidoc

@@ -1,12 +1,38 @@
 [discrete]
 [[esql-to_unsigned_long]]
 === `TO_UNSIGNED_LONG`
+
+*Aliases*
+
+`TO_ULONG`, `TO_UL`
+
+*Syntax*
+
+[source,esql]
+----
+TO_UNSIGNED_LONG(v)
+----
+
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
 Converts an input value to an unsigned long value.
 
-The input can be a single- or multi-valued field or an expression. The input
-type must be of a boolean, date, string or numeric type.
+*Supported types*
 
-Example:
+The input type must be of a boolean, date, string or numeric type.
+
+If the input parameter is of a date type, its value will be interpreted as
+milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to unsigned
+long.
+
+Boolean *true* will be converted to unsigned long *1*, *false* to *0*.
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -27,12 +53,3 @@ on the source of the failure:
 A following header will contain the failure reason and the offending value:
 
 `"java.lang.NumberFormatException: Character f is neither a decimal digit number, decimal point, nor \"e\" notation exponential mark."`
-
-
-If the input parameter is of a date type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
-converted to unsigned long.
-
-Boolean *true* will be converted to unsigned long *1*, *false* to *0*.
-
-Alias: TO_ULONG, TO_UL

docs/reference/esql/functions/to_upper.asciidoc

@@ -1,10 +1,26 @@
 [discrete]
 [[esql-to_upper]]
 === `TO_UPPER`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/to_upper.svg[Embedded,opts=inline]
 
-Returns a new string representing the input string converted to upper case
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+*Description*
+
+Returns a new string representing the input string converted to upper case.
+
+*Supported types*
+
+include::types/to_upper.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=to_upper]
 |===
 include::{esql-specs}/string.csv-spec[tag=to_upper-result]
 |===
-
-Supported types:
-
-include::types/to_upper.asciidoc[]

docs/reference/esql/functions/to_version.asciidoc

@@ -1,10 +1,30 @@
 [discrete]
 [[esql-to_version]]
 === `TO_VERSION`
+
+*Alias*
+
+`TO_VER`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/to_version.svg[Embedded,opts=inline]
 
-Converts an input string to a version value. For example:
+*Parameters*
+
+`v`::
+Input value. The input can be a single- or multi-valued column or an expression.
+
+*Description*
+
+Converts an input string to a version value.
+
+*Supported types*
+
+include::types/to_version.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,11 +34,3 @@ include::{esql-specs}/version.csv-spec[tag=to_version]
 |===
 include::{esql-specs}/version.csv-spec[tag=to_version-result]
 |===
-
-The input can be a single- or multi-valued field or an expression.
-
-Alias: TO_VER
-
-Supported types:
-
-include::types/to_version.asciidoc[]

docs/reference/esql/functions/trim.asciidoc

@@ -1,11 +1,27 @@
 [discrete]
 [[esql-trim]]
 === `TRIM`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/trim.svg[Embedded,opts=inline]
 
+*Parameters*
+
+`str`::
+String expression. If `null`, the function returns `null`.
+
+*Description*
+
 Removes leading and trailing whitespaces from strings.
 
+*Supported types*
+
+include::types/trim.asciidoc[]
+
+*Example*
+
 [source.merge.styled,esql]
 ----
 include::{esql-specs}/string.csv-spec[tag=trim]
@@ -14,7 +30,3 @@ include::{esql-specs}/string.csv-spec[tag=trim]
 |===
 include::{esql-specs}/string.csv-spec[tag=trim-result]
 |===
-
-Supported types:
-
-include::types/trim.asciidoc[]

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

@@ -33,6 +33,14 @@ Which, if `still_hired` is a boolean field, can be simplified to:
 include::{esql-specs}/docs.csv-spec[tag=whereBoolean]
 ----
 
+Use date math to retrieve data from a specific time range. For example, to 
+retrieve the last hour of logs:
+
+[source,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=docsNowWhere]
+----
+
 `WHERE` supports various <<esql-functions,functions>>. For example the
 <<esql-length>> function:
 

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

@@ -1048,3 +1048,29 @@ hires:long     | year:date
 1              |1999-01-01T00:00:00.000Z
 // end::docsDateTruncHistogram-result[]
 ;
+
+docsNow
+// tag::docsNow[]
+ROW current_date = NOW()
+// end::docsNow[]
+| EVAL y = SUBSTRING(DATE_FORMAT("yyyy", current_date), 0, 2)
+| KEEP y
+;
+
+// tag::docsNow-result[]
+y:keyword
+20
+// end::docsNow-result[]  
+;
+
+docsNowWhere
+// tag::docsNowWhere[]
+FROM sample_data
+| WHERE @timestamp > NOW() - 1 hour
+// end::docsNowWhere[]
+;
+
+// tag::docsNowWhere-result[]
+@timestamp:date   | client_ip:ip | event_duration:long | message:keyword
+// end::docsNowWhere-result[]
+;

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

@@ -262,6 +262,24 @@ FROM sample_data
 @timestamp:date | client_ip:ip | event_duration:long | message:keyword |  duration_ms:double
 ;
 
+docsLength
+// tag::length[]
+FROM employees
+| KEEP first_name, last_name
+| EVAL fn_length = LENGTH(first_name)
+// end::length[]
+| SORT first_name
+| LIMIT 3
+;
+
+// tag::length-result[]
+first_name:keyword   | last_name:keyword   | fn_length:integer
+Alejandro      |McAlpine       |9              
+Amabile        |Gomatam        |7              
+Anneke         |Preusig        |6
+// end::length-result[]
+;
+
 docsGettingStartedEvalNoColumnName
 // tag::gs-eval-no-column-name[]
 FROM sample_data