feat: Support autocomplete for PromQL label filters (#3072)

## Summary

This PR adds support for querying available labels from a PromQL source (either by querying a timeseries table or by proxying to a remote prometheus endpoint), and uses the new functionality to provide label autocomplete suggestions when configuring a PromQL Labels dashboard filter:

<img width="691" height="677" alt="Screenshot 2026-09-03 at 7 10 05 AM" src="https://github.com/user-attachments/assets/278db93d-6059-4486-bd10-9bac4f0b6eda" />

### How to test locally

1. Setup a promql source based on the metrics_ts table
2. Create a dashboard and add a promql labels filter, note the autocomplete is populated


### References



- Linear Issue: Closes HDX-5256
- Related PRs:

Author: pulpdrew

.changeset/early-hotels-lay.md

@@ -0,0 +1,6 @@
+---
+"@hyperdx/api": patch
+"@hyperdx/app": patch
+---
+
+feat: Support autocomplete for PromQL label filters

packages/api/src/controllers/__tests__/timeseriesEngine.int.test.ts

@@ -1,12 +1,16 @@
 import { ClickhouseClient } from '@/clickhouse';
 import * as config from '@/config';
-import { queryLabelValues } from '@/controllers/timeseriesEngine';
+import {
+  queryLabelNames,
+  queryLabelValues,
+} from '@/controllers/timeseriesEngine';
 import {
   closeTestFixtureClickHouseClient,
   DEFAULT_DATABASE,
   dropTimeSeriesTable,
   executeSqlCommand,
   seedTimeSeriesTagsTable,
+  TimeSeriesFixtureSeries,
 } from '@/fixtures';
 
 const CONNECTION_ID = 'timeseries-engine-int-test';
@@ -19,11 +23,12 @@ const RECENT_START_SEC = 1700000000;
 const sec = (s: number) => s * 1000;
 
 // Three series: one only in the distant past, two only in the recent window
-// sharing a metric name (so DISTINCT has something to collapse).
-const SERIES = [
+// sharing a metric name (so DISTINCT has something to collapse). Only the old
+// series carries `region`, so a window can exclude a label name too.
+const SERIES: TimeSeriesFixtureSeries[] = [
   {
     metricName: 'old_metric',
-    tags: { job: 'batch' },
+    tags: { job: 'batch', region: 'eu' },
     startSec: OLD_START_SEC,
     endSec: OLD_START_SEC + HOUR_SEC,
   },
@@ -241,4 +246,62 @@ describe('timeseriesEngine controller', () => {
       }
     });
   });
+
+  describe('queryLabelNames', () => {
+    const labelNames = (
+      args: Partial<Parameters<typeof queryLabelNames>[0]> = {},
+    ) =>
+      queryLabelNames({
+        client,
+        connectionId: CONNECTION_ID,
+        databaseName: DEFAULT_DATABASE,
+        tableName: BOUNDED_TABLE,
+        ...args,
+      });
+
+    // `__name__` is not a key of `tags`, so it only appears if folded back in.
+    it('returns every label name including __name__, deduplicated and sorted', async () => {
+      expect(await labelNames()).toEqual(['__name__', 'job', 'region']);
+    });
+
+    it('keeps only labels carried by series overlapping the window', async () => {
+      expect(
+        await labelNames({
+          startMs: sec(RECENT_START_SEC),
+          endMs: sec(RECENT_START_SEC + HOUR_SEC),
+        }),
+      ).toEqual(['__name__', 'job']);
+    });
+
+    it('returns nothing for a window no series covers', async () => {
+      expect(
+        await labelNames({
+          startMs: sec(OLD_START_SEC + 2 * HOUR_SEC),
+          endMs: sec(OLD_START_SEC + 3 * HOUR_SEC),
+        }),
+      ).toEqual([]);
+    });
+
+    it('caps the number of names returned, keeping the ordering', async () => {
+      expect(await labelNames({ limit: 2 })).toEqual(['__name__', 'job']);
+    });
+
+    it('treats a zero limit as unlimited', async () => {
+      expect(await labelNames({ limit: 0 })).toEqual([
+        '__name__',
+        'job',
+        'region',
+      ]);
+    });
+
+    it('ignores the bounds on a table without min_time/max_time', async () => {
+      expect(
+        await labelNames({
+          tableName: UNBOUNDED_TABLE,
+          startMs: sec(RECENT_START_SEC),
+          endMs: sec(RECENT_START_SEC + HOUR_SEC),
+        }),
+      ).toEqual(['__name__', 'job', 'region']);
+    });
+  });
 });

packages/api/src/controllers/timeseriesEngine.ts

@@ -14,6 +14,16 @@ import logger from '@/utils/logger';
 export const PROMETHEUS_MAX_EXECUTION_SEC = 30;
 export const PROMETHEUS_MAX_RESULT_ROWS = 100000;
 
+export type TimeSeriesTagsQueryArgs = {
+  client: ClickhouseClient;
+  connectionId: string;
+  databaseName: string;
+  tableName: string;
+  startMs?: number;
+  endMs?: number;
+  limit?: number;
+};
+
 /**
  * Indicates whether the tags inner table associated with the given TimeSeries table
  * includes the optional `min_time` and `max_time` columns.
@@ -49,64 +59,61 @@ async function timeSeriesTagsTableHasTimeBounds({
 }
 
 /**
- * Queries distinct values for the given label name from the given TimeSeries table,
- * optionally filtering by a time range (if the table has the optional time range columns).
+ * Returns SQL predicates restricting tags rows to series that overlap [startMs, endMs].
+ * Empty when no bound is given, or when the table stores no time bounds.
  */
-export async function queryLabelValues({
+async function getTimeFilterCondition({
   client,
-  databaseName,
   connectionId,
+  databaseName,
   tableName,
-  labelName,
   startMs,
   endMs,
-  limit,
-}: {
-  client: ClickhouseClient;
-  connectionId: string;
-  databaseName: string;
-  tableName: string;
-  labelName: string;
-  startMs?: number;
-  endMs?: number;
-  limit?: number;
-}): Promise<string[]> {
-  const isMetricName = labelName === '__name__';
-  const value = isMetricName
-    ? chSql`${{ Identifier: 'metric_name' }} `
-    : chSql`${{ Identifier: 'tags' }}[${{ String: labelName }}]`;
-
-  const conditions: ChSql[] = [];
-  if (!isMetricName)
-    conditions.push(
-      chSql`mapContains(${{ Identifier: 'tags' }}, ${{ String: labelName }})`,
-    );
-
-  const metadata = new Metadata(client, new MetadataCache());
-  const hasStartTime = startMs != null;
-  const hasEndTime = endMs != null;
+}: Omit<TimeSeriesTagsQueryArgs, 'limit'>): Promise<ChSql[]> {
+  if (startMs == null && endMs == null) return [];
 
   // min and max time columns are optional in the tags inner table,
   // so we check if they exist before adding time conditions
-  const tableHasTimeBounds =
-    (hasStartTime || hasEndTime) && // Short-circuit if no time conditions are needed
-    (await timeSeriesTagsTableHasTimeBounds({
-      metadata,
-      connectionId,
-      database: databaseName,
-      table: tableName,
-    }));
+  const metadata = new Metadata(client, new MetadataCache());
+  const tableHasTimeBounds = await timeSeriesTagsTableHasTimeBounds({
+    metadata,
+    connectionId,
+    database: databaseName,
+    table: tableName,
+  });
+  if (!tableHasTimeBounds) return [];
 
-  if (tableHasTimeBounds && endMs != null)
+  const conditions: ChSql[] = [];
+  if (endMs != null)
     conditions.push(
       chSql`(min_time IS NULL OR min_time <= fromUnixTimestamp64Milli(${{ Int64: endMs }}))`,
     );
-
-  if (tableHasTimeBounds && startMs != null)
+  if (startMs != null)
     conditions.push(
       chSql`(max_time IS NULL OR max_time >= fromUnixTimestamp64Milli(${{ Int64: startMs }}))`,
     );
+  return conditions;
+}
 
+/**
+ * Runs `SELECT DISTINCT <value> AS val FROM timeSeriesTags(...)` with the given
+ * conditions, sorted, and returns the distinct values.
+ */
+async function queryDistinctTagsValues({
+  client,
+  databaseName,
+  tableName,
+  value,
+  conditions,
+  limit,
+}: {
+  client: ClickhouseClient;
+  databaseName: string;
+  tableName: string;
+  value: ChSql;
+  conditions: ChSql[];
+  limit?: number;
+}): Promise<string[]> {
   const where = conditions.length
     ? chSql`WHERE ${concatChSql(' AND ', ...conditions)}`
     : chSql``;
@@ -135,3 +142,44 @@ export async function queryLabelValues({
   const json = await resp.json<{ val: string }>();
   return json.data.map(r => r.val);
 }
+
+/**
+ * Queries distinct values for the given label name from the given TimeSeries table,
+ * optionally filtering by a time range (if the table has the optional time range columns).
+ */
+export async function queryLabelValues({
+  labelName,
+  limit,
+  ...args
+}: TimeSeriesTagsQueryArgs & { labelName: string }): Promise<string[]> {
+  const isMetricName = labelName === '__name__';
+  const value = isMetricName
+    ? chSql`${{ Identifier: 'metric_name' }} `
+    : chSql`${{ Identifier: 'tags' }}[${{ String: labelName }}]`;
+
+  const conditions: ChSql[] = [];
+  if (!isMetricName)
+    conditions.push(
+      chSql`mapContains(${{ Identifier: 'tags' }}, ${{ String: labelName }})`,
+    );
+  conditions.push(...(await getTimeFilterCondition(args)));
+
+  return queryDistinctTagsValues({ ...args, value, conditions, limit });
+}
+
+/**
+ * Queries the distinct label names carried by any series in the given TimeSeries
+ * table, optionally filtering by a time range (if the table has the optional time
+ * range columns).
+ */
+export async function queryLabelNames({
+  limit,
+  ...args
+}: TimeSeriesTagsQueryArgs): Promise<string[]> {
+  // `all_tags` is EPHEMERAL by default, so the label names come from `tags`,
+  // which the engine strips `__name__` out of. It is folded back in explicitly.
+  const value = chSql`arrayJoin(arrayConcat([${{ String: '__name__' }}], mapKeys(${{ Identifier: 'tags' }})))`;
+  const conditions = await getTimeFilterCondition(args);
+
+  return queryDistinctTagsValues({ ...args, value, conditions, limit });
+}