From fbbe2ac1df9a0c05502332f5391ee5a3e6823d72 Mon Sep 17 00:00:00 2001
From: Abdon Pijpelink <abdon.pijpelink@elastic.co>
Date: Tue, 23 Jan 2024 17:21:56 +0100
Subject: [PATCH] ES|QL in-product help update for 8.12 (#175300)

This PR updates the ES|QL in-product help with the following:

- New functions: TO_GEOPOINT, TO_CARTESIANPOINT
- Added erroneously omitted function: ENDS_WIDTH
- Updated description of POW

(cherry picked from commit 95b81318f948193c2c8495181e659b8a557e9650)
---
 .../src/esql_documentation_sections.tsx       | 125 +++++++++++++-----
 1 file changed, 93 insertions(+), 32 deletions(-)

diff --git a/packages/kbn-text-based-editor/src/esql_documentation_sections.tsx b/packages/kbn-text-based-editor/src/esql_documentation_sections.tsx
index 4114ab021bf71..50c85a35d3d9b 100644
--- a/packages/kbn-text-based-editor/src/esql_documentation_sections.tsx
+++ b/packages/kbn-text-based-editor/src/esql_documentation_sections.tsx
@@ -1226,6 +1226,34 @@ Euler’s number.
 
 \`\`\`
 ROW E()
+\`\`\`
+              `,
+              description:
+                'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
+            }
+          )}
+        />
+      ),
+    },
+    {
+      label: i18n.translate(
+        'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.endsWithFunction',
+        {
+          defaultMessage: 'ENDS_WITH',
+        }
+      ),
+      description: (
+        <Markdown
+          markdown={i18n.translate(
+            'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.endsWithFunction.markdown',
+            {
+              defaultMessage: `### ENDS_WITH
+Returns a boolean that indicates whether a keyword string ends with another string:
+
+\`\`\`
+FROM employees
+| KEEP last_name
+| EVAL ln_E = ENDS_WITH(last_name, "d")
 \`\`\`
               `,
               description:
@@ -1908,44 +1936,13 @@ ROW PI()
             'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.powFunction.markdown',
             {
               defaultMessage: `### POW
-Returns the the value of a base (first argument) raised to a power (second argument). Both arguments must be numeric.
+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.
 
 \`\`\`
 ROW base = 2.0, exponent = 2.0 
 | EVAL s = POW(base, exponent)
 \`\`\`
 
-#### Type rules
-
-The type of the returned value is determined by the types of the base and exponent. The following rules are applied to determine the result type:
-
-* If either of the base or exponent are of a floating point type, the result will be a double
-* Otherwise, if either the base or the exponent are 64-bit (long or unsigned long), the result will be a long
-* Otherwise, the result will be a 32-bit integer (this covers all other numeric types, including int, short and byte)
-
-For example, using simple integers as arguments will lead to an integer result:
-
-\`\`\`
-ROW base = 2, exponent = 2
-| EVAL s = POW(base, exponent)
-\`\`\`
-
-Note: the actual power function is performed using double precision values for all cases. This means that for very large non-floating point values there is a small chance that the operation can lead to slightly different answers than expected. However, a more likely outcome of very large non-floating point values is numerical overflow.
-
-#### Arithmetic errors
-
-Arithmetic errors and numeric overflow do not result in an error. Instead, the result will be \`null\` and a warning for the \`ArithmeticException\` added. For example:
-
-\`\`\`
-ROW x = POW(9223372036854775808, 2)
-\`\`\`
-
-If it is desired to protect against numerical overruns, use \`TO_DOUBLE\` on either of the arguments:
-
-\`\`\`
-ROW x = POW(9223372036854775808, TO_DOUBLE(1))
-\`\`\`
-
 #### 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:
@@ -2361,6 +2358,38 @@ Alias: TO_BOOL
         />
       ),
     },
+    {
+      label: i18n.translate(
+        'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.toCartesianpointFunction',
+        {
+          defaultMessage: 'TO_CARTESIANPOINT',
+        }
+      ),
+      description: (
+        <Markdown
+          markdown={i18n.translate(
+            'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.toCartesianpointFunction.markdown',
+            {
+              defaultMessage: `### 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.
+
+A string will only be successfully converted if it respects the [WKT Point](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format:
+
+\`\`\`
+ROW wkt = ["POINT(4297.11 -1475.53)", "POINT(7580.93 2272.77)"]
+| MV_EXPAND wkt
+| EVAL pt = TO_CARTESIANPOINT(wkt)
+\`\`\`
+              `,
+              description:
+                'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
+            }
+          )}
+        />
+      ),
+    },
     {
       label: i18n.translate(
         'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.toDatetimeFunction',
@@ -2489,6 +2518,38 @@ Alias: TO_DBL
         />
       ),
     },
+    {
+      label: i18n.translate(
+        'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.toGeopointFunction',
+        {
+          defaultMessage: 'TO_GEOPOINT',
+        }
+      ),
+      description: (
+        <Markdown
+          openLinksInNewTab={true}
+          markdown={i18n.translate(
+            'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.toGeopointFunction.markdown',
+            {
+              defaultMessage: `### TO_GEOPOINT
+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\`.
+
+A string will only be successfully converted if it respects the [WKT Point](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format:
+
+\`\`\`
+ROW wkt = "POINT(42.97109630194 14.7552534413725)"
+| EVAL pt = TO_GEOPOINT(wkt)
+\`\`\`
+              `,
+              description:
+                'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
+            }
+          )}
+        />
+      ),
+    },
     {
       label: i18n.translate(
         'textBasedEditor.query.textBasedLanguagesEditor.documentationESQL.toIntegerFunction',