[ES|QL] Add/Modify annotations for spatial and conditional functions …

…for better doc generation (#107722) * annotation for spatial functions and conditional functions
elastic · May 10, 2024 · 11de886 · 11de886
1 parent 04d3b99
commit 11de886
Show file tree

Hide file tree

Showing 72 changed files with 860 additions and 522 deletions.
diff --git a/docs/reference/esql/functions/coalesce.asciidoc b/docs/reference/esql/functions/coalesce.asciidoc
diff --git a/docs/reference/esql/functions/conditional-functions-and-expressions.asciidoc b/docs/reference/esql/functions/conditional-functions-and-expressions.asciidoc
@@ -15,7 +15,7 @@ manner. {esql} supports these conditional functions:
 * <<esql-least>>
 // end::cond_list[]
 
-include::case.asciidoc[]
-include::coalesce.asciidoc[]
-include::greatest.asciidoc[]
-include::least.asciidoc[]
+include::layout/case.asciidoc[]
+include::layout/coalesce.asciidoc[]
+include::layout/greatest.asciidoc[]
+include::layout/least.asciidoc[]
diff --git a/docs/reference/esql/functions/description/case.asciidoc b/docs/reference/esql/functions/description/case.asciidoc
@@ -2,4 +2,4 @@
 
 *Description*
 
-Accepts pairs of conditions and values. The function returns the value that belongs to the first condition that evaluates to true.
+Accepts pairs of conditions and values. The function returns the value that belongs to the first condition that evaluates to `true`.  If the number of arguments is odd, the last argument is the default value which is returned when no condition matches. If the number of arguments is even, and no condition matches, the function returns `null`.
diff --git a/docs/reference/esql/functions/description/greatest.asciidoc b/docs/reference/esql/functions/description/greatest.asciidoc
@@ -2,4 +2,6 @@
 
 *Description*
 
-Returns the maximum value from many columns.
+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`.
diff --git a/docs/reference/esql/functions/description/least.asciidoc b/docs/reference/esql/functions/description/least.asciidoc
@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns the minimum value from many columns.
+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.
diff --git a/docs/reference/esql/functions/description/st_contains.asciidoc b/docs/reference/esql/functions/description/st_contains.asciidoc
@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns whether the first geometry contains the second geometry.
+Returns whether the first geometry contains the second geometry. This is the inverse of the <<esql-st_within,ST_WITHIN>> function.
diff --git a/docs/reference/esql/functions/description/st_disjoint.asciidoc b/docs/reference/esql/functions/description/st_disjoint.asciidoc
@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns whether the two geometries or geometry columns are disjoint.
+Returns whether the two geometries or geometry columns are disjoint. This is the inverse of the <<esql-st_intersects,ST_INTERSECTS>> function. In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅
diff --git a/docs/reference/esql/functions/description/st_intersects.asciidoc b/docs/reference/esql/functions/description/st_intersects.asciidoc
@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns whether the two geometries or geometry columns intersect.
+Returns true if two geometries intersect. They intersect if they have any point in common, including their interior points (points along lines or within polygons). This is the inverse of the <<esql-st_disjoint,ST_DISJOINT>> function. In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅
diff --git a/docs/reference/esql/functions/description/st_within.asciidoc b/docs/reference/esql/functions/description/st_within.asciidoc
@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns whether the first geometry is within the second geometry.
+Returns whether the first geometry is within the second geometry. This is the inverse of the <<esql-st_contains,ST_CONTAINS>> function.
diff --git a/docs/reference/esql/functions/description/st_x.asciidoc b/docs/reference/esql/functions/description/st_x.asciidoc
@@ -2,4 +2,4 @@
 
 *Description*
 
-Extracts the x-coordinate from a point geometry.
+Extracts the `x` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `longitude` value.
diff --git a/docs/reference/esql/functions/description/st_y.asciidoc b/docs/reference/esql/functions/description/st_y.asciidoc
@@ -2,4 +2,4 @@
 
 *Description*
 
-Extracts the y-coordinate from a point geometry.
+Extracts the `y` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `latitude` value.
diff --git a/docs/reference/esql/functions/examples/case.asciidoc b/docs/reference/esql/functions/examples/case.asciidoc
@@ -0,0 +1,32 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Examples*
+
+Determine whether employees are monolingual, bilingual, or polyglot:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=case]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=case-result]
+|===
+Calculate the total connection success rate based on log messages:
+[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.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]
+|===
+
diff --git a/docs/reference/esql/functions/examples/greatest.asciidoc b/docs/reference/esql/functions/examples/greatest.asciidoc
@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=greatest]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=greatest-result]
+|===
+
diff --git a/docs/reference/esql/functions/examples/least.asciidoc b/docs/reference/esql/functions/examples/least.asciidoc
@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=least]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=least-result]
+|===
+
diff --git a/docs/reference/esql/functions/examples/st_x.asciidoc b/docs/reference/esql/functions/examples/st_x.asciidoc
@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/spatial.csv-spec[tag=st_x_y]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/spatial.csv-spec[tag=st_x_y-result]
+|===
+
diff --git a/docs/reference/esql/functions/examples/st_y.asciidoc b/docs/reference/esql/functions/examples/st_y.asciidoc
@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/spatial.csv-spec[tag=st_x_y]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/spatial.csv-spec[tag=st_x_y-result]
+|===
+
diff --git a/docs/reference/esql/functions/greatest.asciidoc b/docs/reference/esql/functions/greatest.asciidoc