[Obs AI Assistant] Update ES|QL docs for 8.14 (#180757)

Updates the ES|QL docs for 8.14. Biggest change is probably the rename
of AUTO_BUCKET to BUCKET, and the fact that aggregation functions now
support expressions.

x-pack/plugins/observability_solution/observability_ai_assistant/scripts/load_esql_docs/load_esql_docs.ts

@@ -31,7 +31,7 @@ yargs(process.argv.slice(2))
     (argv) => {
       run(
         async ({ log }) => {
-          const builtDocsDir = Path.join(__dirname, '../../../../../../built-docs');
+          const builtDocsDir = Path.join(__dirname, '../../../../../../../built-docs');
 
           log.debug(`Looking in ${builtDocsDir} for built-docs repository`);
 
@@ -205,7 +205,10 @@ yargs(process.argv.slice(2))
             return !doc.title.startsWith('ES|QL');
           });
 
-          const outDir = Path.join(__dirname, '../../server/functions/esql/docs');
+          const outDir = Path.join(
+            __dirname,
+            '../../../observability_ai_assistant_app/server/functions/query/esql_docs'
+          );
 
           log.info(`Writing ${flattened.length} documents to disk to ${outDir}`);
 

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.test.ts

@@ -82,4 +82,16 @@ describe('correctCommonEsqlMistakes', () => {
       `FROM logs-*\n| KEEP date, whatever\n| RENAME whatever AS forever\n| SORT forever DESC`
     );
   });
+
+  it(`escapes the column name if SORT uses an expression`, () => {
+    expectQuery(
+      'FROM logs-* \n| STATS COUNT(*) by service.name\n| SORT COUNT(*) DESC',
+      'FROM logs-*\n| STATS COUNT(*) by service.name\n| SORT `COUNT(*)` DESC'
+    );
+
+    expectQuery(
+      'FROM logs-* \n| STATS COUNT(*) by service.name\n| SORT COUNT(*) DESC, @timestamp ASC',
+      'FROM logs-*\n| STATS COUNT(*) by service.name\n| SORT `COUNT(*)` DESC, @timestamp ASC'
+    );
+  });
 });

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/correct_common_esql_mistakes.ts

@@ -146,6 +146,27 @@ function verifyKeepColumns(
   return `KEEP ${columnsInKeep.join(', ')}`;
 }
 
+function escapeExpressionsInSort(sortCommand: string) {
+  const columnsInSort = split(sortCommand.replace(/^SORT\s*/, ''), ',')
+    .map((statement) => split(statement, '=')?.[0].trim())
+    .map((columnAndSortOrder) => {
+      let [, column, sortOrder = ''] = columnAndSortOrder.match(/^(.*?)\s*(ASC|DESC)?$/i) || [];
+      if (!column) {
+        return columnAndSortOrder;
+      }
+
+      if (sortOrder) sortOrder = ` ${sortOrder}`;
+
+      if (!column.match(/^[a-zA-Z0-9_\.@]+$/)) {
+        column = `\`${column}\``;
+      }
+
+      return `${column}${sortOrder}`;
+    });
+
+  return `SORT ${columnsInSort.join(', ')}`;
+}
+
 export function correctCommonEsqlMistakes(content: string, log: Logger) {
   return content.replaceAll(/```esql\n(.*?)\n```/gms, (_, query: string) => {
     const commands = splitIntoCommands(query);
@@ -172,6 +193,10 @@ export function correctCommonEsqlMistakes(content: string, log: Logger) {
         case 'KEEP':
           formattedCommand = verifyKeepColumns(formattedCommand, commands.slice(index + 1));
           break;
+
+        case 'SORT':
+          formattedCommand = escapeExpressionsInSort(formattedCommand);
+          break;
       }
       return formattedCommand;
     });

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-abs.txt

@@ -2,7 +2,7 @@ ABS
 
 Syntax
 Parameters
-n
+number
 Numeric expression. If null, the function returns null.
 DescriptionReturns the absolute value.Supported types
 Examples

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-acos.txt

@@ -2,10 +2,9 @@ ACOS
 
 Syntax
 Parameters
-n
-Numeric expression. If null, the function returns null.
-DescriptionReturns the arccosine of n as an
-angle, expressed in radians.Supported types
+number
+Number between -1 and 1. If null, the function returns null.
+DescriptionReturns the arccosine of n as an angle, expressed in radians.Supported types
 Example
 ```esql
 ROW a=.9

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-asin.txt

@@ -2,11 +2,9 @@ ASIN
 
 Syntax
 Parameters
-n
-Numeric expression. If null, the function returns null.
-DescriptionReturns the
-arcsine
-of the input numeric expression as an angle, expressed in radians.Supported types
+number
+Number between -1 and 1. If null, the function returns null.
+DescriptionReturns the arcsine of the input numeric expression as an angle, expressed in radians.Supported types
 Example
 ```esql
 ROW a=.9

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan.txt

@@ -2,11 +2,9 @@ ATAN
 
 Syntax
 Parameters
-n
+number
 Numeric expression. If null, the function returns null.
-DescriptionReturns the
-arctangent of the
-input numeric expression as an angle, expressed in radians.Supported types
+DescriptionReturns the arctangent of the input numeric expression as an angle, expressed in radians.Supported types
 Example
 ```esql
 ROW a=12.9

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-atan2.txt

@@ -2,13 +2,11 @@ ATAN2
 
 Syntax
 Parameters
-y
-Numeric expression. If null, the function returns null.
-x
-Numeric expression. If null, the function returns null.
-DescriptionThe 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
+y_coordinate
+y coordinate. If null, the function returns null.
+x_coordinate
+x coordinate. If null, the function returns null.
+DescriptionThe 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
 Example
 ```esql
 ROW y=12.9, x=.6

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-avg.txt

@@ -1,11 +1,19 @@
 AVG
 
 Syntax
-AVG(column)
-column
-Numeric column. If null, the function returns null.
-DescriptionThe average of a numeric field.Supported typesThe result is always a double no matter the input type.Example
+AVG(expression)
+expression
+Numeric expression.
+DescriptionThe average of a numeric expression.Supported typesThe result is always a double no matter the input type.Examples
 ```esql
 FROM employees
 | STATS AVG(height)
 ```
+
+The expression can use inline functions. For example, to calculate the average
+over a multivalued column, first use MV_AVG to average the multiple values per
+row, and use the result with the AVG function:
+```esql
+FROM employees
+| STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10)
+```

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-auto_bucket.txt → x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-bucket.txt

@@ -1,10 +1,10 @@
-AUTO_BUCKET
+BUCKET
 
 Syntax
-AUTO_BUCKET(field, buckets, from, to)
+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.
 from
@@ -13,50 +13,50 @@ to
 End of the range. Can be a number or a date expressed as a string.
 DescriptionCreates 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
+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:
 ```esql
 FROM employees
 | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
-| EVAL month = AUTO_BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
+| EVAL month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
 | KEEP hire_date, month
 | SORT hire_date
 ```
 
 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.Combine AUTO_BUCKET with
+of buckets.Combine BUCKET with
 STATS ... BY to create a histogram:
 ```esql
 FROM employees
 | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
-| EVAL month = AUTO_BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
+| EVAL month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
 | STATS hires_per_month = COUNT(*) BY month
 | SORT month
 ```
 
-AUTO_BUCKET does not create buckets that don’t match any documents.
+BUCKET does not create buckets that don’t match any documents.
 That’s why this example is missing 1985-03-01 and other dates.
 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:
 ```esql
 FROM employees
 | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
-| EVAL week = AUTO_BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
+| EVAL week = BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
 | STATS hires_per_week = COUNT(*) BY week
 | SORT week
 ```
 
-AUTO_BUCKET does not filter any rows. It only uses the provided range to
+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 WHERE to filter rows.
-AUTO_BUCKET can also operate on numeric fields. For example, to create a
+BUCKET with WHERE to filter rows.
+BUCKET can also operate on numeric fields. For example, to create a
 salary histogram:
 ```esql
 FROM employees
-| EVAL bs = AUTO_BUCKET(salary, 20, 25324, 74999)
+| EVAL bs = BUCKET(salary, 20, 25324, 74999)
 | STATS COUNT(*) by bs
 | SORT bs
 ```
@@ -68,7 +68,7 @@ per hour:
 ```esql
 FROM sample_data
 | WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW()
-| EVAL bucket = AUTO_BUCKET(@timestamp, 25, DATE_FORMAT(NOW() - 1 day), DATE_FORMAT(NOW()))
+| EVAL bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW())
 | STATS COUNT(*) BY bucket
 ```
 
@@ -77,7 +77,7 @@ hiring month:
 ```esql
 FROM employees
 | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
-| EVAL bucket = AUTO_BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
+| EVAL bucket = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
 | STATS AVG(salary) BY bucket
 | SORT bucket
 ```

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-ceil.txt

@@ -2,12 +2,10 @@ CEIL
 
 Syntax
 Parameters
-n
+number
 Numeric expression. If null, the function returns null.
 DescriptionRound a number up to the nearest integer.
-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.
+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.
 Supported types
 Example
 ```esql

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-coalesce.txt

@@ -3,10 +3,11 @@ COALESCE
 Syntax
 COALESCE(expression1 [, ..., expressionN])
 Parameters
-expressionX
-Expression to evaluate.
-DescriptionReturns the first of its arguments that is not null. If all arguments are null,
-it returns null.Example
+first
+Expression to evaluate
+rest
+Other expression to evaluate
+DescriptionReturns the first of its arguments that is not null. If all arguments are null, it returns null.Example
 ```esql
 ROW a=null, b="b"
 | EVAL COALESCE(a, b)

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cos.txt

@@ -2,10 +2,9 @@ COS
 
 Syntax
 Parameters
-n
-Numeric expression. If null, the function returns null.
-DescriptionReturns the cosine of n. Input
-expected in radians.Supported types
+angle
+An angle, in radians. If null, the function returns null.
+DescriptionReturns the cosine of an angle.Supported types
 Example
 ```esql
 ROW a=1.8

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-cosh.txt

@@ -2,11 +2,10 @@ COSH
 
 Syntax
 Parameters
-n
-Numeric expression. If null, the function returns null.
-Supported types
-DescriptionReturns the hyperbolic
-cosine.Example
+angle
+An angle, in radians. If null, the function returns null.
+DescriptionReturns the hyperbolic cosine of an angle.Supported types
+Example
 ```esql
 ROW a=1.8
 | EVAL cosh=COSH(a)

x-pack/plugins/observability_solution/observability_ai_assistant_app/server/functions/query/esql_docs/esql-count.txt

@@ -1,11 +1,11 @@
 COUNT
 
 Syntax
-COUNT([input])
+COUNT([expression])
 Parameters
-input
-Column or literal for which to count the number of values. If omitted, returns a
-count all (the number of rows).
+expression
+Expression that outputs values to be counted.
+If omitted, equivalent to COUNT(*) (the number of rows).
 DescriptionReturns the total number (count) of input values.Supported typesCan take any field type as input.Examples
 ```esql
 FROM employees
@@ -18,3 +18,10 @@ FROM employees
 | STATS count = COUNT(*) BY languages
 | SORT languages DESC
 ```
+
+The expression can use inline functions. This example splits a string into
+multiple values using the SPLIT function and counts the values:
+```esql
+ROW words="foo;bar;baz;qux;quux;foo"
+| STATS word_count = COUNT(SPLIT(words, ";"))
+```