[ES|QL] METRICS command definition and validation

packages/kbn-esql-ast/index.ts

@@ -24,6 +24,7 @@ export type {
   ESQLLiteral,
   AstProviderFn,
   EditorError,
+  ESQLAstNode,
 } from './src/types';
 
 // Low level functions to parse grammar

packages/kbn-esql-ast/src/__tests__/ast_parser.metrics.test.ts

@@ -19,7 +19,7 @@ describe('METRICS', () => {
         {
           type: 'command',
           name: 'metrics',
-          indices: [
+          sources: [
             {
               type: 'source',
               name: 'foo',
@@ -30,7 +30,7 @@ describe('METRICS', () => {
       ]);
     });
 
-    it('can parse multiple "indices"', () => {
+    it('can parse multiple "sources"', () => {
       const text = 'METRICS foo ,\nbar\t,\t\nbaz \n';
       const { ast, errors } = parse(text);
 
@@ -39,7 +39,7 @@ describe('METRICS', () => {
         {
           type: 'command',
           name: 'metrics',
-          indices: [
+          sources: [
             {
               type: 'source',
               name: 'foo',
@@ -69,7 +69,7 @@ describe('METRICS', () => {
         {
           type: 'command',
           name: 'metrics',
-          indices: [
+          sources: [
             {
               type: 'source',
               name: 'foo',
@@ -99,7 +99,7 @@ describe('METRICS', () => {
         {
           type: 'command',
           name: 'metrics',
-          indices: [
+          sources: [
             {
               type: 'source',
               name: 'foo',

packages/kbn-esql-ast/src/ast_factory.ts

@@ -44,7 +44,7 @@ import {
 import { getPosition } from './ast_position_utils';
 import {
   collectAllSourceIdentifiers,
-  collectAllFieldsStatements,
+  collectAllFields,
   visitByOption,
   collectAllColumnIdentifiers,
   visitRenameClauses,
@@ -120,7 +120,7 @@ export class AstListener implements ESQLParserListener {
   exitRowCommand(ctx: RowCommandContext) {
     const command = createCommand('row', ctx);
     this.ast.push(command);
-    command.args.push(...collectAllFieldsStatements(ctx.fields()));
+    command.args.push(...collectAllFields(ctx.fields()));
   }
 
   /**
@@ -153,20 +153,20 @@ export class AstListener implements ESQLParserListener {
       ...createAstBaseItem('metrics', ctx),
       type: 'command',
       args: [],
-      indices: ctx
+      sources: ctx
         .getTypedRuleContexts(IndexIdentifierContext)
         .map((sourceCtx) => createSource(sourceCtx)),
     };
     this.ast.push(node);
-    const aggregates = collectAllFieldsStatements(ctx.fields(0));
-    const grouping = collectAllFieldsStatements(ctx.fields(1));
+    const aggregates = collectAllFields(ctx.fields(0));
+    const grouping = collectAllFields(ctx.fields(1));
     if (aggregates && aggregates.length) {
       node.aggregates = aggregates;
     }
     if (grouping && grouping.length) {
       node.grouping = grouping;
     }
-    node.args.push(...node.indices, ...aggregates, ...grouping);
+    node.args.push(...node.sources, ...aggregates, ...grouping);
   }
 
   /**
@@ -176,7 +176,7 @@ export class AstListener implements ESQLParserListener {
   exitEvalCommand(ctx: EvalCommandContext) {
     const commandAst = createCommand('eval', ctx);
     this.ast.push(commandAst);
-    commandAst.args.push(...collectAllFieldsStatements(ctx.fields()));
+    commandAst.args.push(...collectAllFields(ctx.fields()));
   }
 
   /**
@@ -189,7 +189,7 @@ export class AstListener implements ESQLParserListener {
 
     // STATS expression is optional
     if (ctx._stats) {
-      command.args.push(...collectAllFieldsStatements(ctx.fields(0)));
+      command.args.push(...collectAllFields(ctx.fields(0)));
     }
     if (ctx._grouping) {
       command.args.push(...visitByOption(ctx, ctx._stats ? ctx.fields(1) : ctx.fields(0)));

packages/kbn-esql-ast/src/ast_walker.ts

@@ -84,6 +84,7 @@ import type {
   ESQLFunction,
   ESQLCommandOption,
   ESQLAstItem,
+  ESQLAstField,
 } from './types';
 
 export function collectAllSourceIdentifiers(ctx: FromCommandContext): ESQLAstItem[] {
@@ -474,14 +475,14 @@ export function visitField(ctx: FieldContext) {
   return collectBooleanExpression(ctx.booleanExpression());
 }
 
-export function collectAllFieldsStatements(ctx: FieldsContext | undefined): ESQLAstItem[] {
-  const ast: ESQLAstItem[] = [];
+export function collectAllFields(ctx: FieldsContext | undefined): ESQLAstField[] {
+  const ast: ESQLAstField[] = [];
   if (!ctx) {
     return ast;
   }
   try {
     for (const field of ctx.field_list()) {
-      ast.push(...visitField(field));
+      ast.push(...(visitField(field) as ESQLAstField[]));
     }
   } catch (e) {
     // do nothing
@@ -494,7 +495,7 @@ export function visitByOption(ctx: StatsCommandContext, expr: FieldsContext | un
     return [];
   }
   const option = createOption(ctx.BY()!.getText().toLowerCase(), ctx);
-  option.args.push(...collectAllFieldsStatements(expr));
+  option.args.push(...collectAllFields(expr));
   return [option];
 }
 

packages/kbn-esql-ast/src/types.ts

@@ -10,6 +10,8 @@ export type ESQLAst = ESQLAstCommand[];
 
 export type ESQLAstCommand = ESQLCommand | ESQLAstMetricsCommand;
 
+export type ESQLAstNode = ESQLAstCommand | ESQLAstItem;
+
 export type ESQLSingleAstItem =
   | ESQLFunction
   | ESQLCommandOption
@@ -20,6 +22,8 @@ export type ESQLSingleAstItem =
   | ESQLLiteral
   | ESQLCommandMode;
 
+export type ESQLAstField = ESQLFunction | ESQLColumn;
+
 export type ESQLAstItem = ESQLSingleAstItem | ESQLAstItem[];
 
 export interface ESQLLocation {
@@ -40,9 +44,9 @@ export interface ESQLCommand<Name = string> extends ESQLAstBaseItem<Name> {
 }
 
 export interface ESQLAstMetricsCommand extends ESQLCommand<'metrics'> {
-  indices: ESQLSource[];
-  aggregates?: ESQLAstItem[];
-  grouping?: ESQLAstItem[];
+  sources: ESQLSource[];
+  aggregates?: ESQLAstField[];
+  grouping?: ESQLAstField[];
 }
 
 export interface ESQLCommandOption extends ESQLAstBaseItem {

packages/kbn-esql-validation-autocomplete/src/definitions/aggs.ts

@@ -28,7 +28,7 @@ function createNumericAggDefinition({
     name,
     type: 'agg',
     description,
-    supportedCommands: ['stats'],
+    supportedCommands: ['stats', 'metrics'],
     signatures: [
       {
         params: [
@@ -98,7 +98,7 @@ export const statsAggregationFunctionDefinitions: FunctionDefinition[] = [
         defaultMessage: 'Returns the maximum value in a field.',
       }),
       type: 'agg',
-      supportedCommands: ['stats'],
+      supportedCommands: ['stats', 'metrics'],
       signatures: [
         {
           params: [{ name: 'column', type: 'number', noNestingFunctions: true }],
@@ -117,7 +117,7 @@ export const statsAggregationFunctionDefinitions: FunctionDefinition[] = [
         defaultMessage: 'Returns the minimum value in a field.',
       }),
       type: 'agg',
-      supportedCommands: ['stats'],
+      supportedCommands: ['stats', 'metrics'],
       signatures: [
         {
           params: [{ name: 'column', type: 'number', noNestingFunctions: true }],
@@ -138,7 +138,7 @@ export const statsAggregationFunctionDefinitions: FunctionDefinition[] = [
       description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.countDoc', {
         defaultMessage: 'Returns the count of the values in a field.',
       }),
-      supportedCommands: ['stats'],
+      supportedCommands: ['stats', 'metrics'],
       signatures: [
         {
           params: [
@@ -164,7 +164,7 @@ export const statsAggregationFunctionDefinitions: FunctionDefinition[] = [
           defaultMessage: 'Returns the count of distinct values in a field.',
         }
       ),
-      supportedCommands: ['stats'],
+      supportedCommands: ['stats', 'metrics'],
       signatures: [
         {
           params: [
@@ -188,7 +188,7 @@ export const statsAggregationFunctionDefinitions: FunctionDefinition[] = [
           defaultMessage: 'Returns the count of distinct values in a field.',
         }
       ),
-      supportedCommands: ['stats'],
+      supportedCommands: ['stats', 'metrics'],
       signatures: [
         {
           params: [{ name: 'column', type: 'cartesian_point', noNestingFunctions: true }],
@@ -212,7 +212,7 @@ export const statsAggregationFunctionDefinitions: FunctionDefinition[] = [
       description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.values', {
         defaultMessage: 'Returns all values in a group as an array.',
       }),
-      supportedCommands: ['stats'],
+      supportedCommands: ['stats', 'metrics'],
       signatures: [
         {
           params: [{ name: 'expression', type: 'any', noNestingFunctions: true }],

packages/kbn-esql-validation-autocomplete/src/definitions/builtin.ts

@@ -22,7 +22,7 @@ function createMathDefinition(
     type: 'builtin',
     name,
     description,
-    supportedCommands: ['eval', 'where', 'row', 'stats', 'sort'],
+    supportedCommands: ['eval', 'where', 'row', 'stats', 'metrics', 'sort'],
     supportedOptions: ['by'],
     signatures: types.map((type) => {
       if (Array.isArray(type)) {
@@ -507,7 +507,7 @@ const otherDefinitions: FunctionDefinition[] = [
     description: i18n.translate('kbn-esql-validation-autocomplete.esql.definition.assignDoc', {
       defaultMessage: 'Assign (=)',
     }),
-    supportedCommands: ['eval', 'stats', 'row', 'dissect', 'where', 'enrich'],
+    supportedCommands: ['eval', 'stats', 'metrics', 'metrics', 'row', 'dissect', 'where', 'enrich'],
     supportedOptions: ['by', 'with'],
     signatures: [
       {

packages/kbn-esql-validation-autocomplete/src/definitions/commands.ts

@@ -88,6 +88,36 @@ export const commandDefinitions: CommandDefinition[] = [
       params: [{ name: 'functions', type: 'function' }],
     },
   },
+  {
+    name: 'metrics',
+    description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.metricsDoc', {
+      defaultMessage:
+        'A metrics-specific source command, use this command to load data from TSDB indices. ' +
+        'Similar to STATS command on can calculate aggregate statistics, such as average, count, and sum, over the incoming search results set. ' +
+        'When used without a BY clause, only one row is returned, which is the aggregation over the entire incoming search results set. ' +
+        'When you use a BY clause, one row is returned for each distinct value in the field specified in the BY clause. ' +
+        'The command returns only the fields in the aggregation, and you can use a wide range of statistical functions with the stats command. ' +
+        'When you perform more than one aggregation, separate each aggregation with a comma.',
+    }),
+    examples: [
+      'metrics index',
+      'metrics index, index2',
+      'metrics index avg = avg(a)',
+      'metrics index sum(b) by b',
+      'metrics index, index2 sum(b) by b % 2',
+      'metrics <sources> [ <aggregates> [ by <grouping> ]]',
+      'metrics src1, src2 agg1, agg2 by field1, field2',
+    ],
+    options: [],
+    modes: [],
+    signature: {
+      multipleParams: true,
+      params: [
+        { name: 'index', type: 'source', wildcards: true },
+        { name: 'expression', type: 'function', optional: true },
+      ],
+    },
+  },
   {
     name: 'stats',
     description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.statsDoc', {