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

…04623) * Functions E-Z * Incorporate changes from elastic#103686 * More functions * More functions * Update docs/reference/esql/functions/floor.asciidoc Co-authored-by: Liam Thompson <[email protected]> * Update docs/reference/esql/functions/left.asciidoc Co-authored-by: Liam Thompson <[email protected]> * Apply suggestions from code review Co-authored-by: Alexander Spies <[email protected]> * Review feedback * Fix geo_shape description * Change 'colum'/'field' into 'expressions' * Review feedback * One more --------- Co-authored-by: Liam Thompson <[email protected]> Co-authored-by: Alexander Spies <[email protected]> Co-authored-by: Elastic Machine <[email protected]>
jakelandis · Jan 25, 2024 · e87c49c · e87c49c
1 parent 05c7377
commit e87c49c
Show file tree

Hide file tree

Showing 70 changed files with 1,330 additions and 404 deletions.
diff --git a/docs/reference/esql/functions/asin.asciidoc b/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*
 

diff --git a/docs/reference/esql/functions/atan.asciidoc b/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*
 

diff --git a/docs/reference/esql/functions/atan2.asciidoc b/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*
 

diff --git a/docs/reference/esql/functions/auto_bucket.asciidoc b/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.

diff --git a/docs/reference/esql/functions/avg.asciidoc b/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*
 

diff --git a/docs/reference/esql/functions/cos.asciidoc b/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*
 

diff --git a/docs/reference/esql/functions/cosh.asciidoc b/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*
 

diff --git a/docs/reference/esql/functions/count-distinct.asciidoc b/docs/reference/esql/functions/count-distinct.asciidoc
@@ -6,16 +6,18 @@
 
 [source,esql]
 ----
-COUNT_DISTINCT(column[, precision])
+COUNT_DISTINCT(column[, precision_threshold])
 ----
 
 *Parameters*
 
 `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]
 ----

diff --git a/docs/reference/esql/functions/e.asciidoc b/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]
 ----

diff --git a/docs/reference/esql/functions/ends_with.asciidoc b/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[]
diff --git a/docs/reference/esql/functions/floor.asciidoc b/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[]
diff --git a/docs/reference/esql/functions/greatest.asciidoc b/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[]
diff --git a/docs/reference/esql/functions/least.asciidoc b/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[]
diff --git a/docs/reference/esql/functions/left.asciidoc b/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[]