[DOCS] Improve ES|QL functions reference for functions A-D (elastic#1…

…03447)

* Functions starting with A

* Functions starting with 'C'

* More 'C' functions

* Fix tests

* Fix missing snippet

* DATE_* functions

* Apply suggestions from code review

Co-authored-by: Bogdan Pintea <[email protected]>

---------

Co-authored-by: Bogdan Pintea <[email protected]>

docs/reference/esql/functions/abs.asciidoc

@@ -1,18 +1,41 @@
 [discrete]
 [[esql-abs]]
 === `ABS`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/abs.svg[Embedded,opts=inline]
 
+*Parameters*
+
+`n`::
+Numeric expression. If `null`, the function returns `null`.
+
+*Description*
+
 Returns the absolute value.
 
-[source,esql]
+*Supported types*
+
+include::types/abs.asciidoc[]
+
+*Examples*
+
+[source.merge.styled,esql]
 ----
-FROM employees
-| KEEP first_name, last_name, height
-| EVAL abs_height = ABS(0.0 - height)
+include::{esql-specs}/math.csv-spec[tag=docsAbs]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=docsAbs-result]
+|===
 
-Supported types:
-
-include::types/abs.asciidoc[]
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=docsAbsEmployees]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=docsAbsEmployees-result]
+|===

docs/reference/esql/functions/asin.asciidoc

@@ -1,10 +1,28 @@
 [discrete]
 [[esql-asin]]
 === `ASIN`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/asin.svg[Embedded,opts=inline]
 
-Inverse https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[sine] trigonometric function.
+*Parameters*
+
+`n`::
+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.
+
+*Supported types*
+
+include::types/asin.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -14,7 +32,3 @@ include::{esql-specs}/floats.csv-spec[tag=asin]
 |===
 include::{esql-specs}/floats.csv-spec[tag=asin-result]
 |===
-
-Supported types:
-
-include::types/asin.asciidoc[]

docs/reference/esql/functions/atan.asciidoc

@@ -1,10 +1,28 @@
 [discrete]
 [[esql-atan]]
 === `ATAN`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/atan.svg[Embedded,opts=inline]
 
-Inverse https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[tangent] trigonometric function.
+*Parameters*
+
+`n`::
+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.
+
+*Supported types*
+
+include::types/atan.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -13,8 +31,4 @@ include::{esql-specs}/floats.csv-spec[tag=atan]
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
 include::{esql-specs}/floats.csv-spec[tag=atan-result]
-|===
-
-Supported types:
-
-include::types/atan.asciidoc[]
+|===

docs/reference/esql/functions/atan2.asciidoc

@@ -1,11 +1,31 @@
 [discrete]
 [[esql-atan2]]
 === `ATAN2`
+
+*Syntax*
+
 [.text-center]
 image::esql/functions/signature/atan2.svg[Embedded,opts=inline]
 
-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.
+*Parameters*
+
+`y`::
+Numeric expression. If `null`, the function returns `null`.
+
+`x`::
+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.
+
+*Supported types*
+
+include::types/atan2.asciidoc[]
+
+*Example*
 
 [source.merge.styled,esql]
 ----
@@ -15,7 +35,3 @@ include::{esql-specs}/floats.csv-spec[tag=atan2]
 |===
 include::{esql-specs}/floats.csv-spec[tag=atan2-result]
 |===
-
-Supported types:
-
-include::types/atan2.asciidoc[]

docs/reference/esql/functions/auto_bucket.asciidoc

@@ -1,72 +1,118 @@
 [discrete]
 [[esql-auto_bucket]]
 === `AUTO_BUCKET`
-Creates human-friendly buckets and returns a `datetime` value for each row that
-corresponds to the resulting bucket the row falls into. Combine `AUTO_BUCKET`
-with <<esql-stats-by>> to create a date histogram.
 
-You provide a target number of buckets, a start date, and an end date, and it
-picks an appropriate bucket size to generate the target number of buckets or
-fewer. For example, this asks for at most 20 buckets over a whole year, which
-picks monthly buckets:
+*Syntax*
+
+[source,esql]
+----
+AUTO_BUCKET(field, buckets, from, to)
+----
+
+*Parameters*
+
+`field`::
+Numeric or date column from which to derive buckets.
+
+`buckets`::
+Target number of buckets.
+
+`from`::
+Start of the range. Can be a number or a date expressed as a string.
+
+`to`::
+End of the range. Can be a number or a date expressed as a string.
+
+*Description*
+
+Creates human-friendly buckets and returns a value for each row that corresponds
+to the resulting bucket the row falls into. 
+
+Using a target number of buckets, a start of a range, and an end of a range,
+`AUTO_BUCKET` picks an appropriate bucket size to generate the target number of
+buckets or fewer. For example, asking for at most 20 buckets over a year results
+in monthly buckets:
 
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/date.csv-spec[tag=auto_bucket_month]
+include::{esql-specs}/date.csv-spec[tag=docsAutoBucketMonth]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/date.csv-spec[tag=auto_bucket_month-result]
+include::{esql-specs}/date.csv-spec[tag=docsAutoBucketMonth-result]
 |===
 
 The goal isn't to provide *exactly* the target number of buckets, it's to pick a
-range that people are comfortable with that provides at most the target number of
-buckets.
+range that people are comfortable with that provides at most the target number
+of buckets.
 
-If you ask for more buckets then `AUTO_BUCKET` can pick a smaller range. For example,
-asking for at most 100 buckets in a year will get you week long buckets:
+Combine `AUTO_BUCKET` with
+<<esql-stats-by>> to create a histogram:
 
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/date.csv-spec[tag=auto_bucket_week]
+include::{esql-specs}/date.csv-spec[tag=docsAutoBucketMonthlyHistogram]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/date.csv-spec[tag=auto_bucket_week-result]
+include::{esql-specs}/date.csv-spec[tag=docsAutoBucketMonthlyHistogram-result]
 |===
 
-`AUTO_BUCKET` does not filter any rows. It only uses the provided time range to
-pick a good bucket size. For rows with a date outside of the range, it returns a
-`datetime` that corresponds to a bucket outside the range. Combine `AUTO_BUCKET`
-with <<esql-where>> to filter rows.
+NOTE: `AUTO_BUCKET` does not create buckets that don't match any documents.
+That's why this example is missing `1985-03-01` and other dates.
 
-A more complete example might look like:
+Asking for more buckets can result in a smaller range. For example, asking for
+at most 100 buckets in a year results in weekly buckets:
 
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/date.csv-spec[tag=auto_bucket_in_agg]
+include::{esql-specs}/date.csv-spec[tag=docsAutoBucketWeeklyHistogram]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/date.csv-spec[tag=auto_bucket_in_agg-result]
+include::{esql-specs}/date.csv-spec[tag=docsAutoBucketWeeklyHistogram-result]
 |===
 
-NOTE: `AUTO_BUCKET` does not create buckets that don't match any documents. That's
-why the example above is missing `1985-03-01` and other dates.
+NOTE: `AUTO_BUCKET` does not filter any rows. It only uses the provided range to
+pick a good bucket size. For rows with a value outside of the range, it returns
+a bucket value that corresponds to a bucket outside the range. Combine
+`AUTO_BUCKET` with <<esql-where>> to filter rows.
 
-==== Numeric fields
+`AUTO_BUCKET` can also operate on numeric fields. For example, to create a
+salary histogram:
 
-`auto_bucket` can also operate on numeric fields like this:
 [source.merge.styled,esql]
 ----
-include::{esql-specs}/ints.csv-spec[tag=auto_bucket]
+include::{esql-specs}/ints.csv-spec[tag=docsAutoBucketNumeric]
 ----
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-include::{esql-specs}/ints.csv-spec[tag=auto_bucket-result]
+include::{esql-specs}/ints.csv-spec[tag=docsAutoBucketNumeric-result]
 |===
 
-Unlike the example above where you are intentionally filtering on a date range,
-you rarely want to filter on a numeric range. So you have find the `min` and `max`
-separately. We don't yet have an easy way to do that automatically. Improvements
-coming!
+Unlike the earlier example that intentionally filters on a date range, you
+rarely want to filter on a numeric range. You have to find the `min` and `max`
+separately. {esql} doesn't yet have an easy way to do that automatically.
+
+*Examples*
+
+Create hourly buckets for the last 24 hours, and calculate the number of events
+per hour:
+
+
+[source.styled,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=docsAutoBucketLast24hr]
+----
+
+Create monthly buckets for the year 1985, and calculate the average salary by
+hiring month:
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=auto_bucket_in_agg]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/date.csv-spec[tag=auto_bucket_in_agg-result]
+|===

docs/reference/esql/functions/avg.asciidoc

@@ -1,8 +1,27 @@
 [discrete]
 [[esql-agg-avg]]
 === `AVG`
+
+*Syntax*
+
+[source,esql]
+----
+AVG(column)
+----
+
+`column`::
+Numeric column. If `null`, the function returns `null`.
+
+*Description*
+
 The average of a numeric field.
 
+*Supported types*
+
+The result is always a `double` no matter the input type.
+
+*Example*
+
 [source.merge.styled,esql]
 ----
 include::{esql-specs}/stats.csv-spec[tag=avg]
@@ -11,5 +30,3 @@ include::{esql-specs}/stats.csv-spec[tag=avg]
 |===
 include::{esql-specs}/stats.csv-spec[tag=avg-result]
 |===
-
-The result is always a `double` not matter the input type.

docs/reference/esql/functions/case.asciidoc

@@ -32,6 +32,8 @@ no condition matches, the function returns `null`.
 
 *Example*
 
+Determine whether employees are monolingual, bilingual, or polyglot:
+
 [source,esql]
 [source.merge.styled,esql]
 ----
@@ -41,3 +43,28 @@ include::{esql-specs}/docs.csv-spec[tag=case]
 |===
 include::{esql-specs}/docs.csv-spec[tag=case-result]
 |===
+
+Calculate the total connection success rate based on log messages:
+
+[source,esql]
+[source.merge.styled,esql]
+----
+include::{esql-specs}/conditional.csv-spec[tag=docsCaseSuccessRate]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/conditional.csv-spec[tag=docsCaseSuccessRate-result]
+|===
+
+Calculate an hourly error rate as a percentage of the total number of log
+messages:
+
+[source,esql]
+[source.merge.styled,esql]
+----
+include::{esql-specs}/conditional.csv-spec[tag=docsCaseHourlyErrorRate]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/conditional.csv-spec[tag=docsCaseHourlyErrorRate-result]
+|===