feat: Add RawSqlChartConfig types for SQL-based Table (#1846)

## Summary



This PR is the first step towards raw SQL-driven charts. 
- It introduces updated ChartConfig types, which are now unions of `BuilderChartConfig` (which is unchanged from the current `ChartConfig` types` and `RawSqlChartConfig` types which represent sql-driven charts. 
- It adds _very basic_ support for SQL-driven tables in the Chart Explorer and Dashboard pages. This is currently behind a feature toggle and enabled only in preview environments and for local development.

The changes in most of the files in this PR are either type updates or the addition of type guards to handle the new ChartConfig union type. 

The DBEditTimeChartForm has been updated significantly to (a) add the Raw SQL option to the table chart editor and (b) handle conversion from internal form state (which can now include properties from either branch of the ChartConfig union) to valid SavedChartConfigs (which may only include properties from one branch).

Significant changes are in:
- packages/app/src/components/ChartEditor/types.ts
- packages/app/src/components/ChartEditor/RawSqlChartEditor.tsx
- packages/app/src/components/ChartEditor/utils.ts
- packages/app/src/components/DBEditTimeChartForm.tsx
- packages/app/src/components/DBTableChart.tsx
- packages/app/src/components/SQLEditor.tsx
- packages/app/src/hooks/useOffsetPaginatedQuery.tsx

Future PRs will add templating to the Raw SQL driven charts for date range and granularity injection; support for other chart types driven by SQL; improved placeholder, validation, and error states; and improved support in the external API and import/export.

### Screenshots or video

https://github.com/user-attachments/assets/008579cc-ef3c-496e-9899-88bbb21eaa5e

### How to test locally or on Vercel

The SQL-driven table can be tested in the preview environment or locally. 

### References



- Linear Issue: HDX-3580
- Related PRs:

Author: pulpdrew

.changeset/fast-swans-brake.md

@@ -0,0 +1,7 @@
+---
+"@hyperdx/common-utils": patch
+"@hyperdx/api": patch
+"@hyperdx/app": patch
+---
+
+feat: Add RawSqlChartConfig types for SQL-based Table

packages/api/src/controllers/dashboard.ts

@@ -1,4 +1,6 @@
+import { isBuilderSavedChartConfig } from '@hyperdx/common-utils/dist/guards';
 import {
+  BuilderSavedChartConfig,
   DashboardWithoutIdSchema,
   Tile,
 } from '@hyperdx/common-utils/dist/types';
@@ -17,15 +19,17 @@ import Dashboard from '@/models/dashboard';
 
 function pickAlertsByTile(tiles: Tile[]) {
   return tiles.reduce((acc, tile) => {
-    if (tile.config.alert) {
+    if (isBuilderSavedChartConfig(tile.config) && tile.config.alert) {
       acc[tile.id] = tile.config.alert;
     }
     return acc;
   }, {});
 }
 
 type TileForAlertSync = Pick<Tile, 'id'> & {
-  config?: Pick<Tile['config'], 'alert'> | { alert?: IAlert | AlertDocument };
+  config?:
+    | Pick<BuilderSavedChartConfig, 'alert'>
+    | { alert?: IAlert | AlertDocument };
 };
 
 function extractTileAlertData(tiles: TileForAlertSync[]): {
@@ -48,8 +52,15 @@ async function syncDashboardAlerts(
 ): Promise<void> {
   const { tileIds: oldTileIds, tileIdsWithAlerts: oldTileIdsWithAlerts } =
     extractTileAlertData(oldTiles);
+
+  const newTilesForAlertSync: TileForAlertSync[] = newTiles.map(t => ({
+    id: t.id,
+    config: isBuilderSavedChartConfig(t.config)
+      ? { alert: t.config.alert }
+      : {},
+  }));
   const { tileIds: newTileIds, tileIdsWithAlerts: newTileIdsWithAlerts } =
-    extractTileAlertData(newTiles);
+    extractTileAlertData(newTilesForAlertSync);
 
   // 1. Create/update alerts for tiles that have alerts
   const alertsByTile = pickAlertsByTile(newTiles);

packages/api/src/fixtures.ts

@@ -1,5 +1,6 @@
 import { createNativeClient } from '@hyperdx/common-utils/dist/clickhouse/node';
 import {
+  BuilderSavedChartConfig,
   DisplayType,
   SavedChartConfig,
   Tile,
@@ -421,7 +422,8 @@ export const randomMongoId = () =>
 
 export const makeTile = (opts?: {
   id?: string;
-  alert?: SavedChartConfig['alert'];
+  alert?: BuilderSavedChartConfig['alert'];
+  sourceId?: string;
 }): Tile => ({
   id: opts?.id ?? randomMongoId(),
   x: 1,
@@ -433,10 +435,11 @@ export const makeTile = (opts?: {
 
 export const makeChartConfig = (opts?: {
   id?: string;
-  alert?: SavedChartConfig['alert'];
+  alert?: BuilderSavedChartConfig['alert'];
+  sourceId?: string;
 }): SavedChartConfig => ({
   name: 'Test Chart',
-  source: 'test-source',
+  source: opts?.sourceId ?? 'test-source',
   displayType: DisplayType.Line,
   select: [
     {

packages/api/src/routers/external-api/v2/utils/dashboards.ts

@@ -1,5 +1,7 @@
+import { isRawSqlSavedChartConfig } from '@hyperdx/common-utils/dist/guards';
 import {
   AggregateFunctionSchema,
+  BuilderSavedChartConfig,
   DisplayType,
   SavedChartConfig,
 } from '@hyperdx/common-utils/dist/types';
@@ -62,7 +64,7 @@ const DEFAULT_SELECT_ITEM: ExternalDashboardSelectItem = {
 };
 
 const convertToExternalSelectItem = (
-  item: Exclude<SavedChartConfig['select'][number], string>,
+  item: Exclude<BuilderSavedChartConfig['select'][number], string>,
 ): ExternalDashboardSelectItem => {
   const parsedAggFn = AggregateFunctionSchema.safeParse(item.aggFn);
   const aggFn = parsedAggFn.success ? parsedAggFn.data : 'none';
@@ -84,6 +86,9 @@ const convertToExternalSelectItem = (
 const convertToExternalTileChartConfig = (
   config: SavedChartConfig,
 ): ExternalDashboardTileConfig | undefined => {
+  // HDX-3582: Implement this for Raw SQL charts
+  if (isRawSqlSavedChartConfig(config)) return undefined;
+
   const sourceId = config.source?.toString() ?? '';
 
   const stringValueOrDefault = <D>(
@@ -175,7 +180,10 @@ const convertToExternalTileChartConfig = (
 
 function convertTileToExternalChart(
   tile: DashboardDocument['tiles'][number],
-): ExternalDashboardTileWithId {
+): ExternalDashboardTileWithId | undefined {
+  // HDX-3582: Implement this for Raw SQL charts
+  if (isRawSqlSavedChartConfig(tile.config)) return undefined;
+
   // Returned in case of a failure converting the saved chart config
   const defaultTileConfig: ExternalDashboardTileConfig = {
     displayType: 'line',
@@ -196,7 +204,9 @@ export function convertToExternalDashboard(
   return {
     id: dashboard._id.toString(),
     name: dashboard.name,
-    tiles: dashboard.tiles.map(convertTileToExternalChart),
+    tiles: dashboard.tiles
+      .map(convertTileToExternalChart)
+      .filter(t => t !== undefined),
     tags: dashboard.tags || [],
     filters: dashboard.filters?.map(translateFilterToExternalFilter) || [],
     savedQuery: dashboard.savedQuery ?? null,
@@ -211,7 +221,7 @@ export function convertToExternalDashboard(
 
 const convertToInternalSelectItem = (
   item: ExternalDashboardSelectItem,
-): Exclude<SavedChartConfig['select'][number], string> => {
+): Exclude<BuilderSavedChartConfig['select'][number], string> => {
   return {
     ...pick(item, ['alias', 'metricType', 'metricName', 'aggFn', 'level']),
     aggCondition: item.where,

packages/api/src/tasks/checkAlerts/index.ts

@@ -17,7 +17,11 @@ import { renderChartConfig } from '@hyperdx/common-utils/dist/core/renderChartCo
 import { aliasMapToWithClauses } from '@hyperdx/common-utils/dist/core/utils';
 import { timeBucketByGranularity } from '@hyperdx/common-utils/dist/core/utils';
 import {
-  ChartConfigWithOptDateRange,
+  isBuilderSavedChartConfig,
+  isRawSqlSavedChartConfig,
+} from '@hyperdx/common-utils/dist/guards';
+import {
+  BuilderChartConfigWithOptDateRange,
   DisplayType,
 } from '@hyperdx/common-utils/dist/types';
 import * as fns from 'date-fns';
@@ -67,6 +71,7 @@ export const alertHasGroupBy = (details: AlertDetails): boolean => {
   }
   if (
     details.taskType === AlertTaskType.TILE &&
+    isBuilderSavedChartConfig(details.tile.config) &&
     details.tile.config.groupBy &&
     details.tile.config.groupBy.length > 0
   ) {
@@ -84,10 +89,10 @@ export async function computeAliasWithClauses(
   savedSearch: Pick<ISavedSearch, 'select' | 'where' | 'whereLanguage'>,
   source: ISource,
   metadata: Metadata,
-): Promise<ChartConfigWithOptDateRange['with']> {
+): Promise<BuilderChartConfigWithOptDateRange['with']> {
   const resolvedSelect =
     savedSearch.select || source.defaultTableSelectExpression || '';
-  const config: ChartConfigWithOptDateRange = {
+  const config: BuilderChartConfigWithOptDateRange = {
     connection: '',
     displayType: DisplayType.Search,
     from: source.from,
@@ -317,7 +322,7 @@ const getChartConfigFromAlert = (
   connection: string,
   dateRange: [Date, Date],
   windowSizeInMins: number,
-): ChartConfigWithOptDateRange | undefined => {
+): BuilderChartConfigWithOptDateRange | undefined => {
   const { alert, source } = details;
   if (details.taskType === AlertTaskType.SAVED_SEARCH) {
     const savedSearch = details.savedSearch;
@@ -344,6 +349,10 @@ const getChartConfigFromAlert = (
     };
   } else if (details.taskType === AlertTaskType.TILE) {
     const tile = details.tile;
+
+    // Alerts are not supported for raw sql based charts
+    if (isRawSqlSavedChartConfig(tile.config)) return undefined;
+
     // Doesn't work for metric alerts yet
     if (
       tile.config.displayType === DisplayType.Line ||

packages/api/src/tasks/checkAlerts/providers/__tests__/default.test.ts

@@ -148,8 +148,10 @@ describe('DefaultAlertProvider', () => {
       });
 
       // Create tile with source
-      const tile = makeTile({ id: 'test-tile-123' });
-      tile.config.source = source._id.toString();
+      const tile = makeTile({
+        id: 'test-tile-123',
+        sourceId: source._id.toString(),
+      });
 
       // Create dashboard
       const dashboard = await Dashboard.create({
@@ -301,8 +303,10 @@ describe('DefaultAlertProvider', () => {
       );
 
       // Create tile and alert
-      const tile = makeTile({ id: 'test-tile-123' });
-      tile.config.source = source._id.toString();
+      const tile = makeTile({
+        id: 'test-tile-123',
+        sourceId: source._id.toString(),
+      });
 
       const dashboard = await Dashboard.create({
         team: team._id,
@@ -503,8 +507,10 @@ describe('DefaultAlertProvider', () => {
     it('should skip alerts with missing source', async () => {
       const team = await createTeam({ name: 'Test Team' });
 
-      const tile = makeTile({ id: 'test-tile' });
-      tile.config.source = new mongoose.Types.ObjectId().toString(); // Non-existent source
+      const tile = makeTile({
+        id: 'test-tile',
+        sourceId: new mongoose.Types.ObjectId().toString(), // Non-existent source
+      });
 
       const dashboard = await Dashboard.create({
         team: team._id,
@@ -684,8 +690,10 @@ describe('DefaultAlertProvider', () => {
       });
 
       // Create tile with source
-      const tile = makeTile({ id: 'test-tile-123' });
-      tile.config.source = source._id.toString();
+      const tile = makeTile({
+        id: 'test-tile-123',
+        sourceId: source._id.toString(),
+      });
 
       // Create dashboard
       const dashboard = await Dashboard.create({

packages/api/src/tasks/checkAlerts/providers/default.ts

@@ -1,4 +1,5 @@
 import { ClickhouseClient } from '@hyperdx/common-utils/dist/clickhouse/node';
+import { isRawSqlSavedChartConfig } from '@hyperdx/common-utils/dist/guards';
 import { Tile } from '@hyperdx/common-utils/dist/types';
 import mongoose from 'mongoose';
 import ms from 'ms';
@@ -106,6 +107,16 @@ async function getTileDetails(
     return [];
   }
 
+  if (isRawSqlSavedChartConfig(tile.config)) {
+    logger.warn({
+      tileId,
+      dashboardId: dashboard._id,
+      alertId: alert.id,
+      message: 'skipping alert with raw sql chart config, not supported',
+    });
+    return [];
+  }
+
   const source = await Source.findOne({
     _id: tile.config.source,
     team: alert.team,