[ES|QL] add validation for VALUES and MV_SORT

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

@@ -113,14 +113,25 @@ export function createLiteral(
     return;
   }
   const text = node.getText();
-  return {
+
+  const partialLiteral: Omit<ESQLLiteral, 'literalType' | 'value'> = {
     type: 'literal',
-    literalType: type,
     text,
     name: text,
-    value: type === 'number' ? Number(text) : text,
     location: getPosition(node.symbol),
-    incomplete: isMissingText(node.getText()),
+    incomplete: isMissingText(text),
+  };
+  if (type === 'number') {
+    return {
+      ...partialLiteral,
+      literalType: type,
+      value: Number(text),
+    };
+  }
+  return {
+    ...partialLiteral,
+    literalType: type,
+    value: text,
   };
 }
 

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

@@ -72,10 +72,38 @@ export interface ESQLList extends ESQLAstBaseItem {
   values: ESQLLiteral[];
 }
 
-export interface ESQLLiteral extends ESQLAstBaseItem {
+export type ESQLLiteral =
+  | ESQLNumberLiteral
+  | ESQLBooleanLiteral
+  | ESQLNullLiteral
+  | ESQLStringLiteral;
+
+// @internal
+export interface ESQLNumberLiteral extends ESQLAstBaseItem {
   type: 'literal';
-  literalType: 'string' | 'number' | 'boolean' | 'null';
-  value: string | number;
+  literalType: 'number';
+  value: number;
+}
+
+// @internal
+export interface ESQLBooleanLiteral extends ESQLAstBaseItem {
+  type: 'literal';
+  literalType: 'boolean';
+  value: string;
+}
+
+// @internal
+export interface ESQLNullLiteral extends ESQLAstBaseItem {
+  type: 'literal';
+  literalType: 'null';
+  value: string;
+}
+
+// @internal
+export interface ESQLStringLiteral extends ESQLAstBaseItem {
+  type: 'literal';
+  literalType: 'string';
+  value: string;
 }
 
 export interface ESQLMessage {

packages/kbn-esql-validation-autocomplete/src/autocomplete/autocomplete.test.ts

@@ -245,7 +245,7 @@ describe('autocomplete', () => {
           // simulate the editor behaviour for sorting suggestions
           .sort((a, b) => (a.sortText || '').localeCompare(b.sortText || ''));
         for (const [index, receivedSuggestion] of suggestionInertTextSorted.entries()) {
-          if (typeof expected[index] === 'string') {
+          if (typeof expected[index] !== 'object') {
             expect(receivedSuggestion.text).toEqual(expected[index]);
           } else {
             // check all properties that are defined in the expected suggestion
@@ -1054,38 +1054,47 @@ describe('autocomplete', () => {
       if (fn.name !== 'auto_bucket') {
         for (const signature of fn.signatures) {
           signature.params.forEach((param, i) => {
-            if (i < signature.params.length - 1) {
+            if (i < signature.params.length) {
               const canHaveMoreArgs =
+                i + 1 < (signature.minParams ?? 0) ||
                 signature.params.filter(({ optional }, j) => !optional && j > i).length > i;
               testSuggestions(
                 `from a | eval ${fn.name}(${Array(i).fill('field').join(', ')}${i ? ',' : ''} )`,
-                [
-                  ...getFieldNamesByType(param.type).map((f) => (canHaveMoreArgs ? `${f},` : f)),
-                  ...getFunctionSignaturesByReturnType(
-                    'eval',
-                    param.type,
-                    { evalMath: true },
-                    undefined,
-                    [fn.name]
-                  ).map((l) => (canHaveMoreArgs ? `${l},` : l)),
-                  ...getLiteralsByType(param.type).map((d) => (canHaveMoreArgs ? `${d},` : d)),
-                ]
+                param.literalOptions?.length
+                  ? param.literalOptions.map((option) => `"${option}"${canHaveMoreArgs ? ',' : ''}`)
+                  : [
+                      ...getFieldNamesByType(param.type).map((f) =>
+                        canHaveMoreArgs ? `${f},` : f
+                      ),
+                      ...getFunctionSignaturesByReturnType(
+                        'eval',
+                        param.type,
+                        { evalMath: true },
+                        undefined,
+                        [fn.name]
+                      ).map((l) => (canHaveMoreArgs ? `${l},` : l)),
+                      ...getLiteralsByType(param.type).map((d) => (canHaveMoreArgs ? `${d},` : d)),
+                    ]
               );
               testSuggestions(
                 `from a | eval var0 = ${fn.name}(${Array(i).fill('field').join(', ')}${
                   i ? ',' : ''
                 } )`,
-                [
-                  ...getFieldNamesByType(param.type).map((f) => (canHaveMoreArgs ? `${f},` : f)),
-                  ...getFunctionSignaturesByReturnType(
-                    'eval',
-                    param.type,
-                    { evalMath: true },
-                    undefined,
-                    [fn.name]
-                  ).map((l) => (canHaveMoreArgs ? `${l},` : l)),
-                  ...getLiteralsByType(param.type).map((d) => (canHaveMoreArgs ? `${d},` : d)),
-                ]
+                param.literalOptions?.length
+                  ? param.literalOptions.map((option) => `"${option}"${canHaveMoreArgs ? ',' : ''}`)
+                  : [
+                      ...getFieldNamesByType(param.type).map((f) =>
+                        canHaveMoreArgs ? `${f},` : f
+                      ),
+                      ...getFunctionSignaturesByReturnType(
+                        'eval',
+                        param.type,
+                        { evalMath: true },
+                        undefined,
+                        [fn.name]
+                      ).map((l) => (canHaveMoreArgs ? `${l},` : l)),
+                      ...getLiteralsByType(param.type).map((d) => (canHaveMoreArgs ? `${d},` : d)),
+                    ]
               );
             }
           });

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

@@ -68,6 +68,7 @@ import {
   buildVariablesDefinitions,
   buildOptionDefinition,
   buildSettingDefinitions,
+  buildValueDefinitions,
 } from './factories';
 import { EDITOR_MARKER, SINGLE_BACKTICK } from '../shared/constants';
 import { getAstContext, removeMarkerArgFromArgsList } from '../shared/context';
@@ -1082,6 +1083,15 @@ async function getFunctionArgsSuggestions(
     return [];
   });
 
+  const literalOptions = fnDefinition.signatures.reduce<string[]>((acc, signature) => {
+    const literalOptionsForThisParameter = signature.params[argIndex]?.literalOptions;
+    return literalOptionsForThisParameter ? acc.concat(literalOptionsForThisParameter) : acc;
+  }, [] as string[]);
+
+  if (literalOptions.length) {
+    return buildValueDefinitions(literalOptions);
+  }
+
   const arg = node.args[argIndex];
 
   // the first signature is used as reference

packages/kbn-esql-validation-autocomplete/src/autocomplete/factories.ts

@@ -165,6 +165,16 @@ export const buildConstantsDefinitions = (
     sortText: 'A',
   }));
 
+export const buildValueDefinitions = (values: string[]): SuggestionRawDefinition[] =>
+  values.map((value) => ({
+    label: `"${value}"`,
+    text: `"${value}"`,
+    detail: i18n.translate('kbn-esql-validation-autocomplete.esql.autocomplete.valueDefinition', {
+      defaultMessage: 'Literal value',
+    }),
+    kind: 'Value',
+  }));
+
 export const buildNewVarDefinition = (label: string): SuggestionRawDefinition => {
   return {
     label,

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

@@ -175,4 +175,22 @@ export const statsAggregationFunctionDefinitions: FunctionDefinition[] = [
         },
       ],
     },
+    {
+      name: 'values',
+      type: 'agg',
+      description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.values', {
+        defaultMessage: 'Returns all values in a group as an array.',
+      }),
+      supportedCommands: ['stats'],
+      signatures: [
+        {
+          params: [{ name: 'expression', type: 'any', noNestingFunctions: true }],
+          returnType: 'any',
+          examples: [
+            'from index | stats all_agents=values(agents.keyword)',
+            'from index | stats all_sorted_agents=mv_sort(values(agents.keyword))',
+          ],
+        },
+      ],
+    },
   ]);

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

@@ -97,7 +97,6 @@ export const evalFunctionsDefinitions: FunctionDefinition[] = [
     ],
     validate: validateLogFunctions,
   },
-
   {
     name: 'log',
     description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.logDoc', {
@@ -481,14 +480,9 @@ export const evalFunctionsDefinitions: FunctionDefinition[] = [
     signatures: [
       {
         params: [{ name: 'field', type: 'string' }],
-        returnType: 'version',
+        returnType: 'string',
         examples: [`from index | EVAL version = to_version(stringField)`],
       },
-      {
-        params: [{ name: 'field', type: 'version' }],
-        returnType: 'version',
-        examples: [`from index | EVAL version = to_version(versionField)`],
-      },
     ],
   },
   {
@@ -924,6 +918,30 @@ export const evalFunctionsDefinitions: FunctionDefinition[] = [
       },
     ],
   },
+  {
+    name: 'mv_sort',
+    description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.mvSortDoc', {
+      defaultMessage: 'Sorts a multivalue expression in lexicographical order.',
+    }),
+    signatures: [
+      {
+        params: [
+          { name: 'field', type: 'any' },
+          {
+            name: 'order',
+            type: 'string',
+            optional: true,
+            literalOptions: ['asc', 'desc'],
+          },
+        ],
+        returnType: 'any',
+        examples: [
+          'row a = [4, 2, -3, 2] | eval sorted = mv_sort(a)',
+          'row a = ["b", "c", "a"] | sorted = mv_sort(a, "DESC")',
+        ],
+      },
+    ],
+  },
   {
     name: 'mv_avg',
     description: i18n.translate('kbn-esql-validation-autocomplete.esql.definitions.mvAvgDoc', {

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

@@ -23,7 +23,22 @@ export interface FunctionDefinition {
       optional?: boolean;
       noNestingFunctions?: boolean;
       supportsWildcard?: boolean;
+      /**
+       * if set this indicates that the value must be a literal
+       * but can be any literal of the correct type
+       */
       literalOnly?: boolean;
+      /**
+       * if provided this means that the value must be one
+       * of the options in the array iff the value is a literal.
+       *
+       * String values are case insensitive.
+       *
+       * If the value is not a literal, this field is ignored because
+       * we can't check the return value of a function to see if it
+       * matches one of the options prior to runtime.
+       */
+      literalOptions?: string[];
     }>;
     minParams?: number;
     returnType: string;
@@ -87,3 +102,5 @@ export type SignatureType =
   | FunctionDefinition['signatures'][number]
   | CommandOptionsDefinition['signature'];
 export type SignatureArgType = SignatureType['params'][number];
+
+export type FunctionArgSignature = FunctionDefinition['signatures'][number]['params'][number];

packages/kbn-esql-validation-autocomplete/src/shared/helpers.ts

@@ -34,6 +34,7 @@ import {
 import type {
   CommandDefinition,
   CommandOptionsDefinition,
+  FunctionArgSignature,
   FunctionDefinition,
   SignatureArgType,
 } from '../definitions/types';
@@ -179,6 +180,8 @@ export function getFunctionDefinition(name: string) {
   return buildFunctionLookup().get(name.toLowerCase());
 }
 
+const unwrapStringLiteralQuotes = (value: string) => value.slice(1, -1);
+
 function buildCommandLookup() {
   if (!commandLookups) {
     commandLookups = commandDefinitions.reduce((memo, def) => {
@@ -337,8 +340,28 @@ export function inKnownTimeInterval(item: ESQLTimeInterval): boolean {
   return timeLiterals.some(({ name }) => name === item.unit.toLowerCase());
 }
 
+/**
+ * Checks if this argument is one of the possible options
+ * if they are defined on the arg definition.
+ *
+ * TODO - Consider merging with isEqualType to create a unified arg validation function
+ */
+export function isValidLiteralOption(arg: ESQLLiteral, argDef: FunctionArgSignature) {
+  return (
+    arg.literalType === 'string' &&
+    argDef.literalOptions &&
+    !argDef.literalOptions
+      .map((option) => option.toLowerCase())
+      .includes(unwrapStringLiteralQuotes(arg.value).toLowerCase())
+  );
+}
+
+/**
+ * Checks if an AST argument is of the correct type
+ * given the definition.
+ */
 export function isEqualType(
-  item: ESQLSingleAstItem,
+  arg: ESQLSingleAstItem,
   argDef: SignatureArgType,
   references: ReferenceMaps,
   parentCommand?: string,
@@ -348,24 +371,24 @@ export function isEqualType(
   if (argType === 'any') {
     return true;
   }
-  if (item.type === 'literal') {
-    return compareLiteralType(argType, item);
+  if (arg.type === 'literal') {
+    return compareLiteralType(argType, arg);
   }
-  if (item.type === 'function') {
-    if (isSupportedFunction(item.name, parentCommand).supported) {
-      const fnDef = buildFunctionLookup().get(item.name)!;
+  if (arg.type === 'function') {
+    if (isSupportedFunction(arg.name, parentCommand).supported) {
+      const fnDef = buildFunctionLookup().get(arg.name)!;
       return fnDef.signatures.some((signature) => argType === signature.returnType);
     }
   }
-  if (item.type === 'timeInterval') {
-    return argType === 'time_literal' && inKnownTimeInterval(item);
+  if (arg.type === 'timeInterval') {
+    return argType === 'time_literal' && inKnownTimeInterval(arg);
   }
-  if (item.type === 'column') {
+  if (arg.type === 'column') {
     if (argType === 'column') {
       // anything goes, so avoid any effort here
       return true;
     }
-    const hit = getColumnHit(nameHit ?? item.name, references);
+    const hit = getColumnHit(nameHit ?? arg.name, references);
     const validHit = hit;
     if (!validHit) {
       return false;