[ES|QL] Update function metadata (elastic#226710)

This PR updates the function definitions and inline docs based on the
latest metadata from Elasticsearch.

Author: kibanamachine

src/platform/packages/private/kbn-language-documentation/src/sections/generated/aggregation_functions.tsx

@@ -160,11 +160,12 @@ export const functions = {
   ### MEDIAN
   The value that is greater than half of all values and less than half of all values, also known as the 50% [\`PERCENTILE\`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile).
 
+  Note: Like [\`PERCENTILE\`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile), \`MEDIAN\` is [usually approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile-approximate).
+
   \`\`\`esql
   FROM employees
   | STATS MEDIAN(salary), PERCENTILE(salary, 50)
   \`\`\`
-  Note: Like [\`PERCENTILE\`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile), \`MEDIAN\` is [usually approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile-approximate).
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -194,11 +195,12 @@ export const functions = {
 
   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 [\`PERCENTILE\`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile), \`MEDIAN_ABSOLUTE_DEVIATION\` is [usually approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile-approximate).
+
   \`\`\`esql
   FROM employees
   | STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary)
   \`\`\`
-  Note: Like [\`PERCENTILE\`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile), \`MEDIAN_ABSOLUTE_DEVIATION\` is [usually approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile-approximate).
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',

src/platform/packages/private/kbn-language-documentation/src/sections/generated/operators.tsx

@@ -38,7 +38,6 @@ export const functions = {
               defaultMessage: `
   ### ADD \`+\`
   Add two numbers together. If either field is [multivalued](https://www.elastic.co/docs/reference/query-languages/esql/esql-multivalued-fields) then the result is \`null\`.
-
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -240,6 +239,12 @@ export const functions = {
   Returns \`false\` if the value is \`NULL\`, \`true\` otherwise.
 
   Note: If a field is only in some documents it will be \`NULL\` in the documents that did not contain it.
+
+  \`\`\`esql
+  FROM employees
+  | WHERE is_rehired IS NOT NULL
+  | STATS COUNT(emp_no)
+  \`\`\`
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -268,6 +273,11 @@ export const functions = {
   Returns \`true\` if the value is \`NULL\`, \`false\` otherwise.
 
   Note: If a field is only in some documents it will be \`NULL\` in the documents that did not contain it.
+
+  \`\`\`esql
+  FROM employees
+  | WHERE birth_date IS NULL
+  \`\`\`
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -352,8 +362,7 @@ export const functions = {
   Use \`LIKE\` to filter data based on string patterns using wildcards. \`LIKE\`
   usually acts on a field placed on the left-hand side of the operator, but it can
   also act on a constant (literal) expression. The right-hand side of the operator
-  represents the pattern or a list of patterns. If a list of patterns is provided,
-  the expression will return true if any of the patterns match.
+  represents the pattern.
 
   The following wildcard characters are supported:
 
@@ -430,7 +439,6 @@ export const functions = {
               defaultMessage: `
   ### MODULO \`%\`
   Divide one number by another and return the remainder. If either field is [multivalued](https://www.elastic.co/docs/reference/query-languages/esql/esql-multivalued-fields) then the result is \`null\`.
-
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -457,7 +465,6 @@ export const functions = {
               defaultMessage: `
   ### MULTIPLY \`*\`
   Multiply two numbers together. If either field is [multivalued](https://www.elastic.co/docs/reference/query-languages/esql/esql-multivalued-fields) then the result is \`null\`.
-
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -484,7 +491,6 @@ export const functions = {
               defaultMessage: `
   ### NEGATE \`-\`
   Returns the negation of the argument.
-
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -574,7 +580,6 @@ export const functions = {
               defaultMessage: `
   ### SUBTRACT \`-\`
   Subtract one number from another. If either field is [multivalued](https://www.elastic.co/docs/reference/query-languages/esql/esql-multivalued-fields) then the result is \`null\`.
-
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',

src/platform/packages/private/kbn-language-documentation/src/sections/generated/scalar_functions.tsx

@@ -187,13 +187,14 @@ export const functions = {
   ### BIT LENGTH
   Returns the bit length of a string.
 
+  Note: All strings are in UTF-8, so a single character can use multiple bytes.
+
   \`\`\`esql
   FROM airports
   | WHERE country == "India"
   | KEEP city
   | EVAL fn_length = LENGTH(city), fn_bit_length = BIT_LENGTH(city)
   \`\`\`
-  Note: All strings are in UTF-8, so a single character can use multiple bytes.
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -221,13 +222,14 @@ export const functions = {
   ### BYTE LENGTH
   Returns the byte length of a string.
 
+  Note: All strings are in UTF-8, so a single character can use multiple bytes.
+
   \`\`\`esql
   FROM airports
   | WHERE country == "India"
   | KEEP city
   | EVAL fn_length = LENGTH(city), fn_byte_length = BYTE_LENGTH(city)
   \`\`\`
-  Note: All strings are in UTF-8, so a single character can use multiple bytes.
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -319,11 +321,12 @@ export const functions = {
   ### CEIL
   Round a number up 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 [Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#ceil(double)).
+
   \`\`\`esql
   ROW a=1.8
   | EVAL a=CEIL(a)
   \`\`\`
-  Note: This is a noop for \`long\` (including unsigned) and \`integer\`. For \`double\` this picks the closest \`double\` value to the integer similar to [Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#ceil(double)).
   `,
             description:
               'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -747,13 +750,14 @@ export const functions = {
   ### FLOOR
   Round 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 [Math.floor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#floor(double)).
+
   \`\`\`esql
   ROW a=1.8
   | EVAL a=FLOOR(a)
   \`\`\`
-  Note: This is a noop for \`long\` (including unsigned) and \`integer\`.
-  For \`double\` this picks the closest \`double\` value to the integer
-  similar to [Math.floor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#floor(double)).
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -813,11 +817,12 @@ export const functions = {
   Returns the maximum value from multiple columns. This is similar to [\`MV_MAX\`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/mv-functions#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\`.
+
   \`\`\`esql
   ROW a = 10, b = 20
   | EVAL g = GREATEST(a, b)
   \`\`\`
-  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\`.
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -1026,13 +1031,14 @@ export const functions = {
   ### LENGTH
   Returns the character length of a string.
 
+  Note: All strings are in UTF-8, so a single character can use multiple bytes.
+
   \`\`\`esql
   FROM airports
   | WHERE country == "India"
   | KEEP city
   | EVAL fn_length = LENGTH(city)
   \`\`\`
-  Note: All strings are in UTF-8, so a single character can use multiple bytes.
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -1447,11 +1453,12 @@ export const functions = {
   ### MV DEDUPE
   Remove duplicate values from a multivalued field.
 
+  Note: \`MV_DEDUPE\` may, but won’t always, sort the values in the column.
+
   \`\`\`esql
   ROW a=["foo", "foo", "bar", "foo"]
   | EVAL dedupe_a = MV_DEDUPE(a)
   \`\`\`
-  Note: \`MV_DEDUPE\` may, but won’t always, sort the values in the column.
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -1612,11 +1619,12 @@ export const functions = {
 
   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: If the field has an even number of values, the medians will be calculated as the average of the middle two values. If the value is not a floating point number, the averages are rounded towards 0.
+
   \`\`\`esql
   ROW values = [0, 2, 5, 6]
   | EVAL median_absolute_deviation = MV_MEDIAN_ABSOLUTE_DEVIATION(values), median = MV_MEDIAN(values)
   \`\`\`
-  Note: If the field has an even number of values, the medians will be calculated as the average of the middle two values. If the value is not a floating point number, the averages are rounded towards 0.
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -1917,11 +1925,12 @@ export const functions = {
   ### POW
   Returns the value of \`base\` raised to the power of \`exponent\`.
 
+  Note: It is still possible to overflow a double result here; in that case, null will be returned.
+
   \`\`\`esql
   ROW base = 2.0, exponent = 2
   | EVAL result = POW(base, exponent)
   \`\`\`
-  Note: It is still possible to overflow a double result here; in that case, null will be returned.
   `,
             description:
               'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -3198,13 +3207,14 @@ export const functions = {
   ### TO DATE NANOS
   Converts an input to a nanosecond-resolution date value (aka date_nanos).
 
+  Note: The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attempting to convert values outside of that range will result in null with a warning.  Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch.
+
   \`\`\`esql
   FROM date_nanos
   | WHERE MV_MIN(nanos) < TO_DATE_NANOS("2023-10-23T12:27:28.948Z")
       AND millis > "2000-01-01"
   | SORT nanos DESC
   \`\`\`
-  Note: The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attempting to convert values outside of that range will result in null with a warning.  Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch.
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',
@@ -3265,11 +3275,12 @@ export const functions = {
   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 [\`DATE_PARSE\`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/date-time-functions#esql-date_parse).
 
+  Note: Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is truncated, not rounded.
+
   \`\`\`esql
   ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"]
   | EVAL datetime = TO_DATETIME(string)
   \`\`\`
-  Note: Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is truncated, not rounded.
   `,
               description:
                 'Text is in markdown. Do not translate function names, special characters, or field names like sum(bytes)',

src/platform/packages/shared/kbn-esql-validation-autocomplete/src/definitions/generated/function_names.ts

@@ -56,6 +56,7 @@ export const esqlFunctionNames = [
   'E',
   'ENDS_WITH',
   'EXP',
+  'FIRST_OVER_TIME',
   'FLOOR',
   'FROM_BASE64',
   'GREATEST',
@@ -64,6 +65,7 @@ export const esqlFunctionNames = [
   'IP_PREFIX',
   'KNN',
   'KQL',
+  'LAST_OVER_TIME',
   'LEAST',
   'LEFT',
   'LENGTH',
@@ -103,6 +105,7 @@ export const esqlFunctionNames = [
   'PI',
   'POW',
   'QSTR',
+  'RATE',
   'REPEAT',
   'REPLACE',
   'REVERSE',
@@ -197,7 +200,6 @@ export const esqlFunctionNames = [
   'NOT_LIKE',
   'NOT_RLIKE',
   'NOT_EQUALS',
-  'PREDICATES',
   'RLIKE',
   'SUB',
 ];

src/platform/packages/shared/kbn-esql-validation-autocomplete/src/definitions/generated/operators.ts

@@ -2256,7 +2256,7 @@ const isNotNullDefinition: FunctionDefinition = {
     Location.COMPLETION,
   ],
   validate: undefined,
-  examples: [],
+  examples: ['FROM employees\n| WHERE is_rehired IS NOT NULL\n| STATS COUNT(emp_no)'],
 };
 
 // Do not edit this manually... generated by scripts/generate_function_definitions.ts
@@ -2459,7 +2459,7 @@ const isNullDefinition: FunctionDefinition = {
     Location.COMPLETION,
   ],
   validate: undefined,
-  examples: [],
+  examples: ['FROM employees\n| WHERE birth_date IS NULL'],
 };
 
 // Do not edit this manually... generated by scripts/generate_function_definitions.ts
@@ -3235,7 +3235,7 @@ const likeDefinition: FunctionDefinition = {
   name: 'like',
   description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.like', {
     defaultMessage:
-      'Use `LIKE` to filter data based on string patterns using wildcards. `LIKE`\nusually acts on a field placed on the left-hand side of the operator, but it can\nalso act on a constant (literal) expression. The right-hand side of the operator\nrepresents the pattern or a list of patterns. If a list of patterns is provided,\nthe expression will return true if any of the patterns match.\n\nThe following wildcard characters are supported:\n\n* `*` matches zero or more characters.\n* `?` matches one character.',
+      'Use `LIKE` to filter data based on string patterns using wildcards. `LIKE`\nusually acts on a field placed on the left-hand side of the operator, but it can\nalso act on a constant (literal) expression. The right-hand side of the operator\nrepresents the pattern.\n\nThe following wildcard characters are supported:\n\n* `*` matches zero or more characters.\n* `?` matches one character.',
   }),
   preview: false,
   alias: undefined,
@@ -4492,7 +4492,7 @@ const notLikeDefinition: FunctionDefinition = {
   name: 'not like',
   description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.not_like', {
     defaultMessage:
-      'Use `LIKE` to filter data based on string patterns using wildcards. `LIKE`\nusually acts on a field placed on the left-hand side of the operator, but it can\nalso act on a constant (literal) expression. The right-hand side of the operator\nrepresents the pattern or a list of patterns. If a list of patterns is provided,\nthe expression will return true if any of the patterns match.\n\nThe following wildcard characters are supported:\n\n* `*` matches zero or more characters.\n* `?` matches one character.',
+      'Use `LIKE` to filter data based on string patterns using wildcards. `LIKE`\nusually acts on a field placed on the left-hand side of the operator, but it can\nalso act on a constant (literal) expression. The right-hand side of the operator\nrepresents the pattern.\n\nThe following wildcard characters are supported:\n\n* `*` matches zero or more characters.\n* `?` matches one character.',
   }),
   preview: false,
   alias: undefined,

src/platform/packages/shared/kbn-esql-validation-autocomplete/src/definitions/generated/scalar_functions.ts

@@ -2966,8 +2966,7 @@ const knnDefinition: FunctionDefinition = {
   ],
   validate: undefined,
   examples: [
-    'from colors metadata _score\n| where knn(rgb_vector, [0, 120, 0])\n| sort _score desc, color asc',
-    'from colors metadata _score\n| where knn(rgb_vector, [0,255,255], {"k": 4})\n| sort _score desc, color asc',
+    'from colors metadata _score\n| where knn(rgb_vector, [0, 120, 0], 10)\n| sort _score desc, color asc',
   ],
 };