feat: add typed sql parameter helpers

apps/dev-playground/client/eslint.config.js

@@ -6,7 +6,7 @@ import globals from "globals";
 import tseslint from "typescript-eslint";
 
 export default defineConfig([
-  globalIgnores(["dist"]),
+  globalIgnores(["dist", "src/routeTree.gen.ts"]),
   {
     files: ["**/*.{ts,tsx}"],
     extends: [

apps/dev-playground/client/src/appKitTypes.d.ts

@@ -61,5 +61,15 @@ declare module "@databricks/app-kit-ui/react" {
         app_name: string;
         total_cost_usd: number;
     }[];
+    sql_helpers_test: {
+        string_value: string;
+        number_value: number;
+        boolean_value: boolean;
+        date_value: string;
+        timestamp_value: string;
+        binary_value: string;
+        binary_hex: string;
+        binary_length: number;
+    };
   }
 }

apps/dev-playground/client/src/components/analytics/usage-trends-chart.tsx

@@ -1,3 +1,4 @@
+import { sql } from "@databricks/app-kit-ui/js";
 import { BarChart } from "@databricks/app-kit-ui/react";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import {
@@ -21,7 +22,7 @@ export function UsageTrendsChart({
 }: UsageTrendsChartProps) {
   const spendDataParams = {
     ...queryParams,
-    groupBy,
+    groupBy: sql.string(groupBy),
   };
 
   return (

apps/dev-playground/client/src/lib/utils/filter-utils.ts

@@ -1,3 +1,4 @@
+import { sql } from "@databricks/app-kit-ui/js";
 import type { Aggregation, DashboardFilters } from "@/lib/types";
 
 const ALLOWED_PERIODS = ["day", "week", "month"] as const;
@@ -56,14 +57,16 @@ export function buildWorkflowParams(
 ) {
   const { startDate, endDate } = getDateRange(filters);
 
+  const aggregationLevel = sanitizeAggregationLevel(aggregation.period);
+
   return {
     filters: {
-      startDate: startDate.toISOString().split("T")[0],
-      endDate: endDate.toISOString().split("T")[0],
-      aggregationLevel: sanitizeAggregationLevel(aggregation.period),
-      appId: filters.apps !== "all" ? filters.apps : "all",
-      creator: filters.creator !== "all" ? filters.creator : "all",
-      groupBy: "default",
+      startDate: sql.date(startDate),
+      endDate: sql.date(endDate),
+      aggregationLevel: sql.string(aggregationLevel),
+      appId: sql.string(filters.apps !== "all" ? filters.apps : "all"),
+      creator: sql.string(filters.creator !== "all" ? filters.creator : "all"),
+      groupBy: sql.string("default"),
     },
   };
 }

apps/dev-playground/client/src/routeTree.gen.ts

@@ -8,125 +8,150 @@
 // You should NOT make any changes in this file as it will be overwritten.
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
-import { Route as rootRouteImport } from "./routes/__root";
-import { Route as TelemetryRouteRouteImport } from "./routes/telemetry.route";
-import { Route as ReconnectRouteRouteImport } from "./routes/reconnect.route";
-import { Route as DataVisualizationRouteRouteImport } from "./routes/data-visualization.route";
-import { Route as AnalyticsRouteRouteImport } from "./routes/analytics.route";
-import { Route as IndexRouteImport } from "./routes/index";
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as TelemetryRouteRouteImport } from './routes/telemetry.route'
+import { Route as SqlHelpersRouteRouteImport } from './routes/sql-helpers.route'
+import { Route as ReconnectRouteRouteImport } from './routes/reconnect.route'
+import { Route as DataVisualizationRouteRouteImport } from './routes/data-visualization.route'
+import { Route as AnalyticsRouteRouteImport } from './routes/analytics.route'
+import { Route as IndexRouteImport } from './routes/index'
 
 const TelemetryRouteRoute = TelemetryRouteRouteImport.update({
-  id: "/telemetry",
-  path: "/telemetry",
+  id: '/telemetry',
+  path: '/telemetry',
   getParentRoute: () => rootRouteImport,
-} as any);
+} as any)
+const SqlHelpersRouteRoute = SqlHelpersRouteRouteImport.update({
+  id: '/sql-helpers',
+  path: '/sql-helpers',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ReconnectRouteRoute = ReconnectRouteRouteImport.update({
-  id: "/reconnect",
-  path: "/reconnect",
+  id: '/reconnect',
+  path: '/reconnect',
   getParentRoute: () => rootRouteImport,
-} as any);
+} as any)
 const DataVisualizationRouteRoute = DataVisualizationRouteRouteImport.update({
-  id: "/data-visualization",
-  path: "/data-visualization",
+  id: '/data-visualization',
+  path: '/data-visualization',
   getParentRoute: () => rootRouteImport,
-} as any);
+} as any)
 const AnalyticsRouteRoute = AnalyticsRouteRouteImport.update({
-  id: "/analytics",
-  path: "/analytics",
+  id: '/analytics',
+  path: '/analytics',
   getParentRoute: () => rootRouteImport,
-} as any);
+} as any)
 const IndexRoute = IndexRouteImport.update({
-  id: "/",
-  path: "/",
+  id: '/',
+  path: '/',
   getParentRoute: () => rootRouteImport,
-} as any);
+} as any)
 
 export interface FileRoutesByFullPath {
-  "/": typeof IndexRoute;
-  "/analytics": typeof AnalyticsRouteRoute;
-  "/data-visualization": typeof DataVisualizationRouteRoute;
-  "/reconnect": typeof ReconnectRouteRoute;
-  "/telemetry": typeof TelemetryRouteRoute;
+  '/': typeof IndexRoute
+  '/analytics': typeof AnalyticsRouteRoute
+  '/data-visualization': typeof DataVisualizationRouteRoute
+  '/reconnect': typeof ReconnectRouteRoute
+  '/sql-helpers': typeof SqlHelpersRouteRoute
+  '/telemetry': typeof TelemetryRouteRoute
 }
 export interface FileRoutesByTo {
-  "/": typeof IndexRoute;
-  "/analytics": typeof AnalyticsRouteRoute;
-  "/data-visualization": typeof DataVisualizationRouteRoute;
-  "/reconnect": typeof ReconnectRouteRoute;
-  "/telemetry": typeof TelemetryRouteRoute;
+  '/': typeof IndexRoute
+  '/analytics': typeof AnalyticsRouteRoute
+  '/data-visualization': typeof DataVisualizationRouteRoute
+  '/reconnect': typeof ReconnectRouteRoute
+  '/sql-helpers': typeof SqlHelpersRouteRoute
+  '/telemetry': typeof TelemetryRouteRoute
 }
 export interface FileRoutesById {
-  __root__: typeof rootRouteImport;
-  "/": typeof IndexRoute;
-  "/analytics": typeof AnalyticsRouteRoute;
-  "/data-visualization": typeof DataVisualizationRouteRoute;
-  "/reconnect": typeof ReconnectRouteRoute;
-  "/telemetry": typeof TelemetryRouteRoute;
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/analytics': typeof AnalyticsRouteRoute
+  '/data-visualization': typeof DataVisualizationRouteRoute
+  '/reconnect': typeof ReconnectRouteRoute
+  '/sql-helpers': typeof SqlHelpersRouteRoute
+  '/telemetry': typeof TelemetryRouteRoute
 }
 export interface FileRouteTypes {
-  fileRoutesByFullPath: FileRoutesByFullPath;
+  fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
-    | "/"
-    | "/analytics"
-    | "/data-visualization"
-    | "/reconnect"
-    | "/telemetry";
-  fileRoutesByTo: FileRoutesByTo;
-  to: "/" | "/analytics" | "/data-visualization" | "/reconnect" | "/telemetry";
+    | '/'
+    | '/analytics'
+    | '/data-visualization'
+    | '/reconnect'
+    | '/sql-helpers'
+    | '/telemetry'
+  fileRoutesByTo: FileRoutesByTo
+  to:
+    | '/'
+    | '/analytics'
+    | '/data-visualization'
+    | '/reconnect'
+    | '/sql-helpers'
+    | '/telemetry'
   id:
-    | "__root__"
-    | "/"
-    | "/analytics"
-    | "/data-visualization"
-    | "/reconnect"
-    | "/telemetry";
-  fileRoutesById: FileRoutesById;
+    | '__root__'
+    | '/'
+    | '/analytics'
+    | '/data-visualization'
+    | '/reconnect'
+    | '/sql-helpers'
+    | '/telemetry'
+  fileRoutesById: FileRoutesById
 }
 export interface RootRouteChildren {
-  IndexRoute: typeof IndexRoute;
-  AnalyticsRouteRoute: typeof AnalyticsRouteRoute;
-  DataVisualizationRouteRoute: typeof DataVisualizationRouteRoute;
-  ReconnectRouteRoute: typeof ReconnectRouteRoute;
-  TelemetryRouteRoute: typeof TelemetryRouteRoute;
+  IndexRoute: typeof IndexRoute
+  AnalyticsRouteRoute: typeof AnalyticsRouteRoute
+  DataVisualizationRouteRoute: typeof DataVisualizationRouteRoute
+  ReconnectRouteRoute: typeof ReconnectRouteRoute
+  SqlHelpersRouteRoute: typeof SqlHelpersRouteRoute
+  TelemetryRouteRoute: typeof TelemetryRouteRoute
 }
 
-declare module "@tanstack/react-router" {
+declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
-    "/telemetry": {
-      id: "/telemetry";
-      path: "/telemetry";
-      fullPath: "/telemetry";
-      preLoaderRoute: typeof TelemetryRouteRouteImport;
-      parentRoute: typeof rootRouteImport;
-    };
-    "/reconnect": {
-      id: "/reconnect";
-      path: "/reconnect";
-      fullPath: "/reconnect";
-      preLoaderRoute: typeof ReconnectRouteRouteImport;
-      parentRoute: typeof rootRouteImport;
-    };
-    "/data-visualization": {
-      id: "/data-visualization";
-      path: "/data-visualization";
-      fullPath: "/data-visualization";
-      preLoaderRoute: typeof DataVisualizationRouteRouteImport;
-      parentRoute: typeof rootRouteImport;
-    };
-    "/analytics": {
-      id: "/analytics";
-      path: "/analytics";
-      fullPath: "/analytics";
-      preLoaderRoute: typeof AnalyticsRouteRouteImport;
-      parentRoute: typeof rootRouteImport;
-    };
-    "/": {
-      id: "/";
-      path: "/";
-      fullPath: "/";
-      preLoaderRoute: typeof IndexRouteImport;
-      parentRoute: typeof rootRouteImport;
-    };
+    '/telemetry': {
+      id: '/telemetry'
+      path: '/telemetry'
+      fullPath: '/telemetry'
+      preLoaderRoute: typeof TelemetryRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/sql-helpers': {
+      id: '/sql-helpers'
+      path: '/sql-helpers'
+      fullPath: '/sql-helpers'
+      preLoaderRoute: typeof SqlHelpersRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/reconnect': {
+      id: '/reconnect'
+      path: '/reconnect'
+      fullPath: '/reconnect'
+      preLoaderRoute: typeof ReconnectRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/data-visualization': {
+      id: '/data-visualization'
+      path: '/data-visualization'
+      fullPath: '/data-visualization'
+      preLoaderRoute: typeof DataVisualizationRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/analytics': {
+      id: '/analytics'
+      path: '/analytics'
+      fullPath: '/analytics'
+      preLoaderRoute: typeof AnalyticsRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
   }
 }
 
@@ -135,8 +160,9 @@ const rootRouteChildren: RootRouteChildren = {
   AnalyticsRouteRoute: AnalyticsRouteRoute,
   DataVisualizationRouteRoute: DataVisualizationRouteRoute,
   ReconnectRouteRoute: ReconnectRouteRoute,
+  SqlHelpersRouteRoute: SqlHelpersRouteRoute,
   TelemetryRouteRoute: TelemetryRouteRoute,
-};
+}
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)
-  ._addFileTypes<FileRouteTypes>();
+  ._addFileTypes<FileRouteTypes>()

apps/dev-playground/client/src/routes/__root.tsx

@@ -56,6 +56,14 @@ function RootComponent() {
                     Telemetry
                   </Button>
                 </Link>
+                <Link to="/sql-helpers" className="no-underline">
+                  <Button
+                    variant="ghost"
+                    className="text-gray-700 hover:text-gray-900"
+                  >
+                    SQL Helpers
+                  </Button>
+                </Link>
               </div>
             </nav>
           </div>

apps/dev-playground/client/src/routes/data-visualization.route.tsx

@@ -1,3 +1,4 @@
+import { sql } from "@databricks/app-kit-ui/js";
 import {
   AreaChart,
   BarChart,
@@ -58,22 +59,20 @@ function CodeSnippet({ code }: { code: string }) {
 
 function DataVisualizationRoute() {
   // Default params for the demo - last 30 days
-  const endDate = new Date().toISOString().split("T")[0];
-  const startDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
-    .toISOString()
-    .split("T")[0];
+  const endDate = new Date();
+  const startDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
 
   const commonParams = {
-    startDate,
-    endDate,
-    aggregationLevel: "day",
+    startDate: sql.date(startDate),
+    endDate: sql.date(endDate),
+    aggregationLevel: sql.string("day"),
   };
 
   const spendDataParams = {
     ...commonParams,
-    appId: "all",
-    creator: "all",
-    groupBy: "default",
+    appId: sql.string("all"),
+    creator: sql.string("all"),
+    groupBy: sql.string("default"),
   };
 
   return (

apps/dev-playground/client/src/routes/index.tsx

@@ -103,6 +103,25 @@ function IndexRoute() {
               </Button>
             </div>
           </Card>
+
+          <Card className="p-6 hover:shadow-lg transition-shadow cursor-pointer">
+            <div className="flex flex-col h-full">
+              <h3 className="text-2xl font-semibold text-gray-900 mb-3">
+                SQL Helpers
+              </h3>
+              <p className="text-gray-600 mb-6 flex-grow">
+                Type-safe parameter helpers for Databricks SQL queries. Test
+                each helper interactively and see the generated parameter
+                objects.
+              </p>
+              <Button
+                onClick={() => navigate({ to: "/sql-helpers" })}
+                className="w-full"
+              >
+                Try SQL Helpers
+              </Button>
+            </div>
+          </Card>
         </div>
 
         <div className="text-center pt-12 border-t border-gray-200">