[ES|QL] tsdb compatible hint - autocomplete + validation (elastic#270418)

resolves elastic#269963

## Summary

Respects the `tsdb_compatible: false` hint added to ES|QL function
metadata
([elasticsearch#149401](elastic/elasticsearch#149401))
by filtering incompatible functions from autocomplete suggestions and
raising a validation error when they are used in a time series (`TS`)
pipeline.

**Function definition generation** — The function definition script
needed to propagate the new flag from the elasticsearch defintions.

**Autocomplete** — `filterFunctionDefinitions` (the single chokepoint
all function-suggestion paths route through) now drops functions with
`tsdbCompatible: false` when the query source is `TS`. The TS context is
derived once from the parsed AST via the existing
`isTimeseriesSourceCommand` helper and carried on `ICommandContext`, so
no per-command changes are needed.

**Validation** — `FunctionValidator.validate()` reports a new
`tsdbIncompatibleFunction` error ("Function X is not supported in time
series (TS) pipelines").

The only function carrying `tsdbCompatible: false` today is `SPARKLINE`,
but the plumbing is in place for any future additions from upstream.

### Checklist

Check the PR satisfies following conditions. 

Reviewers should verify this PR satisfies this list as well.

- [x] [Unit or functional
tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)
were updated or added to match the most common scenarios
- [x] The PR description includes the appropriate Release Notes section,
and the correct `release_note:*` label is applied per the
[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)
- [x] Review the [backport
guidelines](https://docs.google.com/document/d/1VyN5k91e5OVumlc0Gb9RPa3h1ewuPE705nRtioPiTvY/edit?usp=sharing)
and apply applicable `backport:*` labels.

---------

Co-authored-by: Stratou <efstratia.kalafateli@elastic.co>

Author: momovdg

src/platform/packages/shared/kbn-esql-language/scripts/generate_function_definitions.ts

@@ -84,6 +84,7 @@ function getFunctionDefinition(ESFunctionDefinition: Record<string, any>): Funct
     alias: aliasTable[ESFunctionDefinition.name],
     ignoreAsSuggestion: ESFunctionDefinition.snapshot_only,
     preview: ESFunctionDefinition.preview,
+    tsdbCompatible: ESFunctionDefinition.tsdb_compatible,
     signatures: _.uniqBy(
       ESFunctionDefinition.signatures.map((signature: any) => ({
         ...signature,
@@ -332,7 +333,9 @@ const ${getDefinitionName(name)}: FunctionDefinition = {
   name: EsqlFunctionNames.${name.toUpperCase()},
     description: i18n.translate('kbn-esql-language.esql.definitions.${name}', { defaultMessage: ${JSON.stringify(
     removeAsciiDocInternalCrossReferences(removeInlineAsciiDocLinks(description), functionNames)
-  )} }),${functionDefinition.ignoreAsSuggestion ? 'ignoreAsSuggestion: true,' : ''}
+  )} }),${functionDefinition.ignoreAsSuggestion ? 'ignoreAsSuggestion: true,' : ''}${
+    functionDefinition.tsdbCompatible === false ? '\n  tsdbCompatible: false,' : ''
+  }
   preview: ${functionDefinition.preview || 'false'},
   alias: ${alias ? `['${alias.join("', '")}']` : 'undefined'},
   signatures: ${JSON.stringify(signaturesWithLicenseLowerCase, null, 2)},

src/platform/packages/shared/kbn-esql-language/src/commands/definitions/generated/aggregation_functions.ts

@@ -4241,6 +4241,7 @@ const sparklineDefinition: FunctionDefinition = {
     defaultMessage:
       'The values representing the y-axis values of a sparkline graph for a given aggregation over a period of time.',
   }),
+  tsdbCompatible: false,
   preview: true,
   alias: undefined,
   signatures: [

src/platform/packages/shared/kbn-esql-language/src/commands/definitions/types.ts

@@ -185,6 +185,7 @@ export interface FunctionDefinition {
   type: FunctionDefinitionTypes;
   preview?: boolean;
   ignoreAsSuggestion?: boolean;
+  tsdbCompatible?: boolean;
   name: string;
   alias?: string[];
   description: string;
@@ -202,6 +203,7 @@ export interface FunctionFilterPredicates {
   returnTypes?: string[];
   ignored?: string[];
   allowed?: string[];
+  isTimeseriesSource?: boolean;
 }
 
 // PromQL Function Definition Types
@@ -490,6 +492,10 @@ export interface ValidationErrors {
     message: string;
     type: { type: string };
   };
+  tsdbIncompatibleFunction: {
+    message: string;
+    type: { fnName: string };
+  };
 }
 
 export type ErrorTypes = keyof ValidationErrors;

src/platform/packages/shared/kbn-esql-language/src/commands/definitions/utils/autocomplete/helpers.ts

@@ -141,6 +141,7 @@ export function getFunctionsSuggestions({
     location,
     returnTypes: types,
     ignored,
+    isTimeseriesSource: context?.isTimeseriesSource,
   };
 
   const hasMinimumLicenseRequired = callbacks?.hasMinimumLicenseRequired;

src/platform/packages/shared/kbn-esql-language/src/commands/definitions/utils/errors.ts

@@ -497,6 +497,13 @@ Expected one of:
         }),
         type: 'error',
       };
+    case 'tsdbIncompatibleFunction':
+      return {
+        message: i18n.translate('kbn-esql-language.esql.validation.tsdbIncompatibleFunction', {
+          defaultMessage: 'Function {fnName} is not supported in time series (TS) pipelines',
+          values: { fnName: out.fnName.toUpperCase() },
+        }),
+      };
   }
   return { message: '' };
 }
@@ -702,6 +709,9 @@ export const errors = {
       locationName,
     }),
 
+  tsdbIncompatibleFunction: (fn: ESQLFunction): ESQLMessage =>
+    errors.byId('tsdbIncompatibleFunction', fn.location, { fnName: fn.name }),
+
   wrongNumberArgs: (fn: ESQLFunction, definition: FunctionDefinition): ESQLMessage => {
     const validArgCounts = new Set<number>();
     let minParams: number | undefined;

src/platform/packages/shared/kbn-esql-language/src/commands/definitions/utils/functions.ts

@@ -105,14 +105,26 @@ export const filterFunctionDefinitions = (
   if (!predicates) {
     return functions;
   }
-  const { location, returnTypes, ignored = [], allowed = [] } = predicates;
+  const { location, returnTypes, ignored = [], allowed = [], isTimeseriesSource } = predicates;
 
   return functions.filter(
-    ({ name, locationsAvailable, ignoreAsSuggestion, signatures, license, observabilityTier }) => {
+    ({
+      name,
+      locationsAvailable,
+      ignoreAsSuggestion,
+      tsdbCompatible,
+      signatures,
+      license,
+      observabilityTier,
+    }) => {
       if (ignoreAsSuggestion) {
         return false;
       }
 
+      if (isTimeseriesSource && tsdbCompatible === false) {
+        return false;
+      }
+
       if (!!hasMinimumLicenseRequired && license) {
         if (!hasMinimumLicenseRequired(license.toLocaleLowerCase() as LicenseType)) {
           return false;

src/platform/packages/shared/kbn-esql-language/src/commands/definitions/utils/validation/function.ts

@@ -112,6 +112,14 @@ class FunctionValidator {
       return;
     }
 
+    // Return early so the source-incompatibility error takes priority over the generic
+    // "not allowed here" check below — the location may technically match, but the function
+    // is invalid regardless because the pipeline source is TS.
+    if (isTimeseriesSourceCommand(this.ast) && this.definition.tsdbCompatible === false) {
+      this.report(errors.tsdbIncompatibleFunction(this.fn));
+      return;
+    }
+
     if (!this.allowedHere) {
       this.report(errors.functionNotAllowedHere(this.fn, this.location.displayName));
     }

src/platform/packages/shared/kbn-esql-language/src/commands/registry/types.ts

@@ -226,6 +226,7 @@ export interface ICommandContext {
   isCursorInSubquery?: boolean;
   isFieldsBrowserEnabled?: boolean;
   unmappedFieldsStrategy?: UnmappedFieldsStrategy;
+  isTimeseriesSource?: boolean;
 }
 /**
  * This is a list of locations within an ES|QL query.

src/platform/packages/shared/kbn-esql-language/src/language/autocomplete/__tests__/autocomplete.tsdb_compatible.test.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+import { FunctionDefinitionTypes } from '../../../commands/definitions/types';
+import { Location } from '../../../commands/registry/types';
+import { setTestFunctions } from '../../../commands/definitions/utils/test_functions';
+import { setup } from './helpers';
+
+const TS_INCOMPATIBLE_FN = {
+  type: FunctionDefinitionTypes.AGG,
+  name: 'TS_INCOMPATIBLE_AGG',
+  description: 'An aggregation that is not supported in TS pipelines',
+  signatures: [{ params: [], returnType: 'double' as const }],
+  locationsAvailable: [Location.STATS],
+  tsdbCompatible: false,
+};
+
+const TS_COMPATIBLE_FN = {
+  type: FunctionDefinitionTypes.AGG,
+  name: 'TS_COMPATIBLE_AGG',
+  description: 'An aggregation that is supported everywhere',
+  signatures: [{ params: [], returnType: 'double' as const }],
+  locationsAvailable: [Location.STATS],
+};
+
+describe('tsdbCompatible filtering', () => {
+  beforeEach(() => setTestFunctions([TS_INCOMPATIBLE_FN, TS_COMPATIBLE_FN]));
+  afterEach(() => setTestFunctions([]));
+
+  it('excludes tsdbCompatible:false functions from suggestions in a TS pipeline', async () => {
+    const { suggest } = await setup();
+    const suggestions = (await suggest('TS index | STATS /')).map((s) => s.label);
+
+    expect(suggestions).not.toContain('TS_INCOMPATIBLE_AGG');
+    expect(suggestions).toContain('TS_COMPATIBLE_AGG');
+  });
+
+  it('includes tsdbCompatible:false functions in suggestions in a FROM pipeline', async () => {
+    const { suggest } = await setup();
+    const suggestions = (await suggest('FROM index | STATS /')).map((s) => s.label);
+
+    expect(suggestions).toContain('TS_INCOMPATIBLE_AGG');
+    expect(suggestions).toContain('TS_COMPATIBLE_AGG');
+  });
+});

src/platform/packages/shared/kbn-esql-language/src/language/autocomplete/autocomplete.ts

@@ -326,6 +326,7 @@ async function getSuggestionsWithinCommandExpression(
     isCursorInSubquery: astContext.isCursorInSubquery,
     isFieldsBrowserEnabled: canSuggestResourceBrowser && !isInsideSubquery,
     unmappedFieldsStrategy,
+    isTimeseriesSource: isTimeseriesSourceCommand(commands.filter((cmd) => cmd.type === 'command')),
   };
 
   // Wrap getColumnsByType so the fields browser option is injected from context;