time bucket thresholds can now be defined per query schema

Author: ericallam

apps/webapp/app/v3/querySchemas.ts

@@ -1,4 +1,4 @@
-import { column, type TableSchema } from "@internal/tsql";
+import { column, type BucketThreshold, type TableSchema } from "@internal/tsql";
 import { z } from "zod";
 import { autoFormatSQL } from "~/components/code/TSQLEditor";
 import { runFriendlyStatus, runStatusTitleFromStatus } from "~/components/runs/v3/TaskRunStatus";
@@ -598,6 +598,18 @@ export const metricsSchema: TableSchema = {
       expression: "attributes.trigger.worker_version",
     },
   },
+  timeBucketThresholds: [
+    // Metrics are pre-aggregated into 10-second buckets, so 10s is the most granular interval.
+    // All thresholds are shifted coarser compared to the runs table defaults.
+    { maxRangeSeconds: 3 * 60 * 60, interval: { value: 10, unit: "SECOND" } },
+    { maxRangeSeconds: 12 * 60 * 60, interval: { value: 1, unit: "MINUTE" } },
+    { maxRangeSeconds: 2 * 24 * 60 * 60, interval: { value: 5, unit: "MINUTE" } },
+    { maxRangeSeconds: 7 * 24 * 60 * 60, interval: { value: 15, unit: "MINUTE" } },
+    { maxRangeSeconds: 30 * 24 * 60 * 60, interval: { value: 1, unit: "HOUR" } },
+    { maxRangeSeconds: 90 * 24 * 60 * 60, interval: { value: 6, unit: "HOUR" } },
+    { maxRangeSeconds: 180 * 24 * 60 * 60, interval: { value: 1, unit: "DAY" } },
+    { maxRangeSeconds: 365 * 24 * 60 * 60, interval: { value: 1, unit: "WEEK" } },
+  ] satisfies BucketThreshold[],
 };
 
 /**

internal-packages/tsql/src/index.ts

@@ -133,7 +133,9 @@ export {
 
 // Re-export time bucket utilities
 export {
+  BUCKET_THRESHOLDS,
   calculateTimeBucketInterval,
+  type BucketThreshold,
   type TimeBucketInterval,
 } from "./query/time_buckets.js";
 

internal-packages/tsql/src/query/printer.test.ts

@@ -2,7 +2,13 @@ import { describe, it, expect, beforeEach } from "vitest";
 import { parseTSQLSelect, parseTSQLExpr, compileTSQL } from "../index.js";
 import { ClickHousePrinter, printToClickHouse, type PrintResult } from "./printer.js";
 import { createPrinterContext, PrinterContext } from "./printer_context.js";
-import { createSchemaRegistry, column, type TableSchema, type SchemaRegistry } from "./schema.js";
+import {
+  createSchemaRegistry,
+  column,
+  type TableSchema,
+  type SchemaRegistry,
+} from "./schema.js";
+import type { BucketThreshold } from "./time_buckets.js";
 import { QueryError, SyntaxError } from "./errors.js";
 
 /**
@@ -3570,4 +3576,73 @@ describe("timeBucket()", () => {
       expect(Object.values(params)).toContain("org_test123");
     });
   });
+
+  describe("per-table timeBucketThresholds", () => {
+    const customThresholds: BucketThreshold[] = [
+      // 10-second minimum granularity (e.g., for pre-aggregated metrics)
+      { maxRangeSeconds: 10 * 60, interval: { value: 10, unit: "SECOND" } },
+      { maxRangeSeconds: 30 * 60, interval: { value: 30, unit: "SECOND" } },
+      { maxRangeSeconds: 2 * 60 * 60, interval: { value: 1, unit: "MINUTE" } },
+    ];
+
+    const schemaWithCustomThresholds: TableSchema = {
+      ...timeBucketSchema,
+      name: "metrics",
+      timeBucketThresholds: customThresholds,
+    };
+
+    it("should use custom thresholds when defined on the table schema", () => {
+      // 3-minute range: global default would give 5 SECOND, custom gives 10 SECOND
+      const threeMinuteRange = {
+        from: new Date("2024-01-01T00:00:00Z"),
+        to: new Date("2024-01-01T00:03:00Z"),
+      };
+
+      const schema = createSchemaRegistry([schemaWithCustomThresholds]);
+      const ctx = createPrinterContext({
+        schema,
+        enforcedWhereClause: {
+          organization_id: { op: "eq", value: "org_test123" },
+          project_id: { op: "eq", value: "proj_test456" },
+          environment_id: { op: "eq", value: "env_test789" },
+        },
+        timeRange: threeMinuteRange,
+      });
+
+      const ast = parseTSQLSelect(
+        "SELECT timeBucket(), count() FROM metrics GROUP BY timeBucket"
+      );
+      const { sql } = printToClickHouse(ast, ctx);
+
+      // Custom thresholds: under 10 min → 10 SECOND (not the global 5 SECOND)
+      expect(sql).toContain("toStartOfInterval(created_at, INTERVAL 10 SECOND)");
+    });
+
+    it("should fall back to global defaults when no custom thresholds are defined", () => {
+      // 3-minute range with standard schema (no custom thresholds)
+      const threeMinuteRange = {
+        from: new Date("2024-01-01T00:00:00Z"),
+        to: new Date("2024-01-01T00:03:00Z"),
+      };
+
+      const schema = createSchemaRegistry([timeBucketSchema]);
+      const ctx = createPrinterContext({
+        schema,
+        enforcedWhereClause: {
+          organization_id: { op: "eq", value: "org_test123" },
+          project_id: { op: "eq", value: "proj_test456" },
+          environment_id: { op: "eq", value: "env_test789" },
+        },
+        timeRange: threeMinuteRange,
+      });
+
+      const ast = parseTSQLSelect(
+        "SELECT timeBucket(), count() FROM runs GROUP BY timeBucket"
+      );
+      const { sql } = printToClickHouse(ast, ctx);
+
+      // Global default: under 5 min → 5 SECOND
+      expect(sql).toContain("toStartOfInterval(created_at, INTERVAL 5 SECOND)");
+    });
+  });
 });

internal-packages/tsql/src/query/printer.ts

@@ -2978,8 +2978,12 @@ export class ClickHousePrinter {
       );
     }
 
-    // Calculate the appropriate interval
-    const interval = calculateTimeBucketInterval(timeRange.from, timeRange.to);
+    // Calculate the appropriate interval (use table-specific thresholds if defined)
+    const interval = calculateTimeBucketInterval(
+      timeRange.from,
+      timeRange.to,
+      tableSchema.timeBucketThresholds
+    );
 
     // Emit toStartOfInterval(column, INTERVAL N UNIT)
     return `toStartOfInterval(${escapeClickHouseIdentifier(clickhouseColumnName)}, INTERVAL ${interval.value} ${interval.unit})`;

internal-packages/tsql/src/query/schema.ts

@@ -2,6 +2,7 @@
 // Defines allowed tables, columns, and tenant isolation configuration
 
 import { QueryError } from "./errors";
+import type { BucketThreshold } from "./time_buckets";
 
 /**
  * ClickHouse data types supported by TSQL
@@ -354,6 +355,13 @@ export interface TableSchema {
    * ```
    */
   timeConstraint?: string;
+  /**
+   * Custom time bucket thresholds for this table.
+   * When set, timeBucket() uses these instead of the global defaults.
+   * Useful when the table's time granularity differs from the standard (e.g., metrics
+   * pre-aggregated into 10-second buckets shouldn't go below 10-second intervals).
+   */
+  timeBucketThresholds?: BucketThreshold[];
 }
 
 /**

internal-packages/tsql/src/query/time_buckets.ts

@@ -17,13 +17,23 @@ export interface TimeBucketInterval {
 }
 
 /**
- * Time bucket thresholds: each entry defines a maximum time range duration (in seconds)
+ * A threshold mapping a maximum time range duration to a bucket interval.
+ */
+export interface BucketThreshold {
+  /** Maximum range duration in seconds for this threshold to apply */
+  maxRangeSeconds: number;
+  /** The bucket interval to use when the range is under maxRangeSeconds */
+  interval: TimeBucketInterval;
+}
+
+/**
+ * Default time bucket thresholds: each entry defines a maximum time range duration (in seconds)
  * and the corresponding bucket interval to use.
  *
  * The intervals are chosen to produce roughly 50-100 data points for the given range.
  * Entries are ordered from smallest to largest range.
  */
-const BUCKET_THRESHOLDS: Array<{ maxRangeSeconds: number; interval: TimeBucketInterval }> = [
+export const BUCKET_THRESHOLDS: BucketThreshold[] = [
   // Under 5 minutes → 5 second buckets (max 60 buckets)
   { maxRangeSeconds: 5 * 60, interval: { value: 5, unit: "SECOND" } },
   // Under 30 minutes → 30 second buckets (max 60 buckets)
@@ -73,10 +83,14 @@ const DEFAULT_LARGE_INTERVAL: TimeBucketInterval = { value: 1, unit: "MONTH" };
  * ); // { value: 6, unit: "HOUR" }
  * ```
  */
-export function calculateTimeBucketInterval(from: Date, to: Date): TimeBucketInterval {
+export function calculateTimeBucketInterval(
+  from: Date,
+  to: Date,
+  thresholds?: BucketThreshold[]
+): TimeBucketInterval {
   const rangeSeconds = Math.abs(to.getTime() - from.getTime()) / 1000;
 
-  for (const threshold of BUCKET_THRESHOLDS) {
+  for (const threshold of thresholds ?? BUCKET_THRESHOLDS) {
     if (rangeSeconds < threshold.maxRangeSeconds) {
       return threshold.interval;
     }