[ES|QL] Support PromQL instant query (#271369)

## Summary

Closes #270417


https://github.com/user-attachments/assets/6f164e44-9747-4b5a-a93d-a7950ebf13b0

- Added the `time `param both autocomplete e validation

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

Author: bartoval

src/platform/packages/shared/kbn-esql-language/src/commands/registry/promql/autocomplete.test.ts

@@ -158,6 +158,18 @@ describe('after PROMQL keyword', () => {
     );
   });
 
+  test('does not suggest time when range params are used', async () => {
+    await expectPromqlSuggestions('PROMQL step=5m ', {
+      textsNotContain: ['time = '],
+    });
+  });
+
+  test('does not suggest range params when time is used', async () => {
+    await expectPromqlSuggestions('PROMQL time="2026-01-13T11:30:00.000Z" ', {
+      textsNotContain: ['time = ', 'step = ', 'start = ', 'end = ', 'buckets = '],
+    });
+  });
+
   test('handles quoted param values correctly', async () => {
     await expectPromqlSuggestions(
       'PROMQL index="metrics" step="5m" ',
@@ -897,6 +909,14 @@ describe('param value suggestions', () => {
     );
   });
 
+  test('suggests date literals for time=', async () => {
+    await expectPromqlSuggestions(
+      'PROMQL time=',
+      { textsContain: TIME_SYSTEM_PARAMS, labelsNotContain: promqlFunctionLabels },
+      mockCallbacks
+    );
+  });
+
   test('suggests date literals when query follows end=', async () => {
     const query =
       'PROMQL index = kibana_sample_data_logstsdb step = 1h start = "2026-01-08T16:00:00.000Z" end =  bytes_counter';

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

@@ -28,6 +28,7 @@ import {
   getUsedPromqlParamNames,
   isAtValidColumnSuggestionPosition,
   isParamValueComplete,
+  isPromqlParamAvailable,
 } from './utils';
 import { findPipeOutsideQuotes } from '../../definitions/utils/shared';
 import { suggestForPromqlQuery } from '../../definitions/utils/autocomplete';
@@ -65,11 +66,8 @@ export async function autocomplete(
   switch (kind) {
     case 'after_command': {
       const usedParams = getUsedPromqlParamNames(commandText);
-      const availableParamSuggestions = getPromqlParamKeySuggestions().filter(
-        ({ label }) =>
-          !usedParams.has(label) &&
-          !(label === PromqlParamName.Step && usedParams.has(PromqlParamName.Buckets)) &&
-          !(label === PromqlParamName.Buckets && usedParams.has(PromqlParamName.Step))
+      const availableParamSuggestions = getPromqlParamKeySuggestions().filter(({ label }) =>
+        isPromqlParamAvailable(label, usedParams)
       );
 
       const canSuggestQuery = isAtValidColumnSuggestionPosition(

src/platform/packages/shared/kbn-esql-language/src/commands/registry/promql/columns_after.test.ts

@@ -85,6 +85,26 @@ describe('PROMQL columnsAfter', () => {
     expect(result.map(({ name }) => name)).toEqual(['step', 'col0', 'job']);
   });
 
+  it('does not return step column when time param is used', async () => {
+    const result = await columnsAfter(
+      synth.cmd`PROMQL index=metrics time="2026-01-13T11:30:00.000Z" col0=(sum by (job) (http_requests_total{env="prod"}))`,
+      [],
+      'PROMQL index=metrics time="2026-01-13T11:30:00.000Z" col0=(sum by (job) (http_requests_total{env="prod"})) | KEEP job',
+      {
+        fromFrom: () => Promise.resolve([]),
+        fromJoin: () => Promise.resolve([]),
+        fromEnrich: () => Promise.resolve([]),
+        fromPromql: () =>
+          Promise.resolve([
+            { name: 'job', type: 'keyword', userDefined: false },
+            { name: 'http_requests_total', type: 'double', userDefined: false },
+          ]),
+      }
+    );
+
+    expect(result.map(({ name }) => name)).toEqual(['col0', 'job']);
+  });
+
   it('does not treat pipe inside label string as command delimiter', async () => {
     const sourceFields: ESQLFieldWithMetadata[] = [
       { name: 'bytes', type: 'double', userDefined: false },

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

@@ -29,10 +29,10 @@ export const promqlCommand = {
     preview: true,
     description: i18n.translate('kbn-esql-language.esql.definitions.promqlDoc', {
       defaultMessage:
-        'Execute PromQL queries against time series data. Use step= or buckets= for time resolution. The index= parameter defaults to * if not specified.',
+        'Execute PromQL queries against time series data. Use time= for instant queries, or step= or buckets= for range query time resolution. The index= parameter defaults to * if not specified.',
     }),
     declaration:
-      'PROMQL [step=<duration>|buckets=<integer>] [start=<time>] [end=<time>] [index=<pattern>] [column=](<query>)',
+      'PROMQL [time=<time>|[step=<duration>|buckets=<integer>] [start=<time>] [end=<time>]] [index=<pattern>] [column=](<query>)',
     examples: [
       'PROMQL index=metrics step=1m start=?_tstart end=?_tend (sum by (instance) (bytes))',
       'PROMQL index=metrics buckets=6 start=?_tstart end=?_tend (avg(cpu_usage))',

src/platform/packages/shared/kbn-esql-language/src/commands/registry/promql/summary.test.ts

@@ -36,6 +36,11 @@ describe('PROMQL summary', () => {
       expectedNewColumns: ['step', 'col0'],
     });
   });
+  it('does not return the step column when time param is used', () => {
+    assertSummary('PROMQL index=metrics time="2026-01-13T11:30:00.000Z" col0=(sum(bytes))', {
+      expectedNewColumns: ['col0'],
+    });
+  });
   it.todo('returns query text as column name when no label is provided');
   it.todo('collects columns derivated from grouping inside the query');
 });

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

@@ -20,6 +20,7 @@ export enum PromqlParamValueType {
 
 export enum PromqlParamName {
   Index = 'index',
+  Time = 'time',
   Step = 'step',
   Start = 'start',
   End = 'end',
@@ -83,6 +84,11 @@ export const PROMQL_PARAMS: PromqlParamDefinition[] = [
     description: 'Index pattern to query',
     valueType: PromqlParamValueType.TimeseriesSources,
   },
+  {
+    name: PromqlParamName.Time,
+    description: 'Instant query evaluation time',
+    valueType: PromqlParamValueType.DateLiterals,
+  },
   {
     name: PromqlParamName.Step,
     description: 'Query resolution step (e.g. 1m, 5m, 1h)',
@@ -112,6 +118,29 @@ export const PROMQL_PARAMS: PromqlParamDefinition[] = [
 
 export const PROMQL_PARAM_NAMES: string[] = PROMQL_PARAMS.map(({ name }) => name);
 
+export const PROMQL_RANGE_PARAM_NAMES = [
+  PromqlParamName.Step,
+  PromqlParamName.Buckets,
+  PromqlParamName.Start,
+  PromqlParamName.End,
+] as const;
+
+export const PROMQL_PARAM_CONFLICTS: Readonly<Record<string, readonly string[]>> = {
+  [PromqlParamName.Step]: [PromqlParamName.Buckets, PromqlParamName.Time],
+  [PromqlParamName.Buckets]: [PromqlParamName.Step, PromqlParamName.Time],
+  [PromqlParamName.Start]: [PromqlParamName.Time],
+  [PromqlParamName.End]: [PromqlParamName.Time],
+  [PromqlParamName.Time]: PROMQL_RANGE_PARAM_NAMES,
+};
+
+export function isPromqlParamAvailable(name: string, usedParams: Set<string>): boolean {
+  if (usedParams.has(name)) {
+    return false;
+  }
+
+  return !PROMQL_PARAM_CONFLICTS[name]?.some((param) => usedParams.has(param));
+}
+
 const PARAM_ASSIGNMENT_PATTERNS = PROMQL_PARAM_NAMES.map((param) => ({
   param,
   pattern: new RegExp(`${param}\\s*=`, 'i'),

src/platform/packages/shared/kbn-esql-language/src/commands/registry/promql/validate.test.ts

@@ -39,6 +39,15 @@ describe('PROMQL Validation', () => {
         ['[PROMQL] Parameters "step" and "buckets" are mutually exclusive']
       );
     });
+
+    test('time cannot be used with range query params', () => {
+      promqlExpectErrors(
+        'PROMQL index=timeseries_index time="2026-01-13T11:30:00.000Z" step=5m (rate(counterIntegerField[5m]))',
+        [
+          '[PROMQL] Specify either [time] for instant query or any of [step], [buckets], [start], [end]',
+        ]
+      );
+    });
   });
 
   describe('param values', () => {
@@ -82,6 +91,19 @@ describe('PROMQL Validation', () => {
         ['[PROMQL] Invalid scrape_interval value']
       );
     });
+
+    test('valid time value', () => {
+      promqlExpectErrors(
+        'PROMQL time="2026-01-13T11:30:00.000Z" (rate(counterIntegerField[5m]))',
+        []
+      );
+    });
+
+    test('invalid time format', () => {
+      promqlExpectErrors('PROMQL time=invalid (rate(counterIntegerField[5m]))', [
+        '[PROMQL] Invalid time value. Use ISO 8601 with Z (e.g. 2024-01-15T10:00:00Z) or ?_tstart/?_tend',
+      ]);
+    });
   });
 
   describe('query presence', () => {

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

@@ -39,6 +39,7 @@ import {
   isPromqlParamName,
   looksLikePromqlParamAssignment,
   PromqlParamName,
+  PROMQL_RANGE_PARAM_NAMES,
 } from './utils';
 
 // ISO 8601 with Z, optional milliseconds (e.g. 2024-01-15T10:00:00Z or ...00.000Z).
@@ -80,6 +81,21 @@ export const validate = (
 
   const hasStep = usedParams.has(PromqlParamName.Step);
   const hasBuckets = usedParams.has(PromqlParamName.Buckets);
+  const hasTime = usedParams.has(PromqlParamName.Time);
+  const hasRangeParam = PROMQL_RANGE_PARAM_NAMES.some((param) => usedParams.has(param));
+
+  if (hasTime && hasRangeParam) {
+    messages.push({
+      ...getMessageFromId({
+        messageId: 'promqlInvalidParam',
+        values: {
+          reason:
+            'Specify either [time] for instant query or any of [step], [buckets], [start], [end]',
+        },
+        locations: command.location,
+      }),
+    });
+  }
 
   if (hasStep && hasBuckets) {
     messages.push({
@@ -94,7 +110,7 @@ export const validate = (
   const hasStart = usedParams.has(PromqlParamName.Start);
   const hasEnd = usedParams.has(PromqlParamName.End);
 
-  if (hasStart !== hasEnd) {
+  if (!hasTime && hasStart !== hasEnd) {
     const param = hasStart ? PromqlParamName.End : PromqlParamName.Start;
     messages.push({
       ...getMessageFromId({
@@ -123,7 +139,11 @@ export const validate = (
       continue;
     }
 
-    if (param === PromqlParamName.Start || param === PromqlParamName.End) {
+    if (
+      param === PromqlParamName.Start ||
+      param === PromqlParamName.End ||
+      param === PromqlParamName.Time
+    ) {
       const normalized = stripQuotes(value);
       const isPlaceholder = normalized === '?_tstart' || normalized === '?_tend';