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">