refactor: use API enum names (JSON_ARRAY, ARROW_STREAM) and simplify format model

Address Mario's review: collapse three formats (JSON, ARROW, ARROW_STREAM) into
two that match the Databricks API enums. ARROW_STREAM supports both INLINE and
EXTERNAL_LINKS dispositions with automatic fallback. Default remains JSON_ARRAY
per reviewer request.

Co-authored-by: Isaac

Author: jamesbroadhead

packages/appkit-ui/src/react/charts/__tests__/types.test.ts

@@ -93,7 +93,7 @@ describe("isQueryProps", () => {
     const props = {
       queryKey: "test_query",
       parameters: { limit: 100 },
-      format: "json" as const,
+      format: "json_array" as const,
     };
 
     expect(isQueryProps(props as any)).toBe(true);

packages/appkit-ui/src/react/charts/types.ts

@@ -5,7 +5,7 @@ import type { Table } from "apache-arrow";
 // ============================================================================
 
 /** Supported data formats for analytics queries */
-export type DataFormat = "json" | "arrow" | "arrow_stream" | "auto";
+export type DataFormat = "json_array" | "arrow_stream" | "auto";
 
 /** Chart orientation */
 export type Orientation = "vertical" | "horizontal";
@@ -77,8 +77,8 @@ export interface QueryProps extends ChartBaseProps {
   parameters?: Record<string, unknown>;
   /**
    * Data format to use
-   * - "json": Use JSON format (smaller payloads, simpler)
-   * - "arrow": Use Arrow format (faster for large datasets)
+   * - "json_array": Use JSON format (smaller payloads, simpler)
+   * - "arrow_stream": Use Arrow format (faster for large datasets)
    * - "auto": Automatically select based on expected data size
    * @default "auto"
    */

packages/appkit-ui/src/react/hooks/__tests__/use-chart-data.test.ts

@@ -72,7 +72,7 @@ describe("useChartData", () => {
   });
 
   describe("format selection", () => {
-    test("uses JSON format when explicitly specified", () => {
+    test("uses JSON_ARRAY format when explicitly specified", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: [],
         loading: false,
@@ -82,18 +82,18 @@ describe("useChartData", () => {
       renderHook(() =>
         useChartData({
           queryKey: "test",
-          format: "json",
+          format: "json_array",
         }),
       );
 
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         undefined,
-        expect.objectContaining({ format: "JSON" }),
+        expect.objectContaining({ format: "JSON_ARRAY" }),
       );
     });
 
-    test("uses ARROW format when explicitly specified", () => {
+    test("uses ARROW_STREAM format when explicitly specified", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: [],
         loading: false,
@@ -103,18 +103,18 @@ describe("useChartData", () => {
       renderHook(() =>
         useChartData({
           queryKey: "test",
-          format: "arrow",
+          format: "arrow_stream",
         }),
       );
 
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         undefined,
-        expect.objectContaining({ format: "ARROW" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
-    test("auto-selects ARROW for large limit", () => {
+    test("auto-selects ARROW_STREAM for large limit", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: [],
         loading: false,
@@ -132,11 +132,11 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         { limit: 1000 },
-        expect.objectContaining({ format: "ARROW" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
-    test("auto-selects ARROW for date range queries", () => {
+    test("auto-selects ARROW_STREAM for date range queries", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: [],
         loading: false,
@@ -157,7 +157,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         expect.objectContaining({ startDate: "2025-01-01" }),
-        expect.objectContaining({ format: "ARROW" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
@@ -179,7 +179,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         expect.anything(),
-        expect.objectContaining({ format: "JSON" }),
+        expect.objectContaining({ format: "JSON_ARRAY" }),
       );
     });
 
@@ -201,11 +201,11 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         expect.anything(),
-        expect.objectContaining({ format: "ARROW" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
-    test("auto-selects ARROW_STREAM by default when no heuristics match", () => {
+    test("auto-selects JSON_ARRAY by default when no heuristics match", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: [],
         loading: false,
@@ -223,11 +223,11 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         { limit: 100 },
-        expect.objectContaining({ format: "ARROW_STREAM" }),
+        expect.objectContaining({ format: "JSON_ARRAY" }),
       );
     });
 
-    test("defaults to auto format (ARROW_STREAM) when format is not specified", () => {
+    test("defaults to auto format (JSON_ARRAY) when format is not specified", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: [],
         loading: false,
@@ -243,7 +243,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         undefined,
-        expect.objectContaining({ format: "ARROW_STREAM" }),
+        expect.objectContaining({ format: "JSON_ARRAY" }),
       );
     });
   });
@@ -353,29 +353,29 @@ describe("useChartData", () => {
       expect(result.current.isArrow).toBe(false);
     });
 
-    test("isArrow reflects requested ARROW format when data is null", () => {
+    test("isArrow reflects requested ARROW_STREAM format when data is null", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: null,
         loading: true,
         error: null,
       });
 
       const { result } = renderHook(() =>
-        useChartData({ queryKey: "test", format: "arrow" }),
+        useChartData({ queryKey: "test", format: "arrow_stream" }),
       );
 
       expect(result.current.isArrow).toBe(true);
     });
 
-    test("isArrow reflects requested JSON format when data is null", () => {
+    test("isArrow reflects requested JSON_ARRAY format when data is null", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: null,
         loading: true,
         error: null,
       });
 
       const { result } = renderHook(() =>
-        useChartData({ queryKey: "test", format: "json" }),
+        useChartData({ queryKey: "test", format: "json_array" }),
       );
 
       expect(result.current.isArrow).toBe(false);

packages/appkit-ui/src/react/hooks/types.ts

@@ -5,7 +5,7 @@ import type { Table } from "apache-arrow";
 // ============================================================================
 
 /** Supported response formats for analytics queries */
-export type AnalyticsFormat = "JSON" | "ARROW" | "ARROW_STREAM";
+export type AnalyticsFormat = "JSON_ARRAY" | "ARROW_STREAM";
 
 /**
  * Typed Arrow Table - preserves row type information for type inference.
@@ -33,9 +33,9 @@ export interface TypedArrowTable<
 
 /** Options for configuring an analytics SSE query */
 export interface UseAnalyticsQueryOptions<
-  F extends AnalyticsFormat = "ARROW_STREAM",
+  F extends AnalyticsFormat = "JSON_ARRAY",
 > {
-  /** Response format - "ARROW_STREAM" (default) uses inline Arrow, "JSON" returns typed arrays, "ARROW" uses external links */
+  /** Response format - "JSON_ARRAY" (default) returns typed arrays, "ARROW_STREAM" uses Arrow (inline or external links) */
   format?: F;
 
   /** Maximum size of serialized parameters in bytes */
@@ -122,7 +122,9 @@ export type InferResultByFormat<
   T,
   K,
   F extends AnalyticsFormat,
-> = F extends "ARROW" ? TypedArrowTable<InferRowType<K>> : InferResult<T, K>;
+> = F extends "ARROW_STREAM"
+  ? TypedArrowTable<InferRowType<K>>
+  : InferResult<T, K>;
 
 /**
  * Infers parameters type from QueryRegistry[K]["parameters"]

packages/appkit-ui/src/react/hooks/use-analytics-query.ts

@@ -27,8 +27,8 @@ function getArrowStreamUrl(id: string) {
  * Integration hook between client and analytics plugin.
  *
  * The return type is automatically inferred based on the format:
- * - `format: "JSON"` (default): Returns typed array from QueryRegistry
- * - `format: "ARROW"`: Returns TypedArrowTable with row type preserved
+ * - `format: "JSON_ARRAY"` (default): Returns typed array from QueryRegistry
+ * - `format: "ARROW_STREAM"`: Returns TypedArrowTable with row type preserved
  *
  * Note: User context execution is determined by query file naming:
  * - `queryKey.obo.sql`: Executes as user (OBO = on-behalf-of / user delegation)
@@ -39,28 +39,28 @@ function getArrowStreamUrl(id: string) {
  * @param options - Analytics query settings including format
  * @returns Query result state with format-appropriate data type
  *
- * @example JSON format (default)
+ * @example JSON_ARRAY format (default)
  * ```typescript
  * const { data } = useAnalyticsQuery("spend_data", params);
  * // data: Array<{ group_key: string; cost_usd: number; ... }> | null
  * ```
  *
- * @example Arrow format
+ * @example ARROW_STREAM format
  * ```typescript
- * const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW" });
+ * const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW_STREAM" });
  * // data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null
  * ```
  */
 export function useAnalyticsQuery<
   T = unknown,
   K extends QueryKey = QueryKey,
-  F extends AnalyticsFormat = "ARROW_STREAM",
+  F extends AnalyticsFormat = "JSON_ARRAY",
 >(
   queryKey: K,
   parameters?: InferParams<K> | null,
   options: UseAnalyticsQueryOptions<F> = {} as UseAnalyticsQueryOptions<F>,
 ): UseAnalyticsQueryResult<InferResultByFormat<T, K, F>> {
-  const format = options?.format ?? "ARROW_STREAM";
+  const format = options?.format ?? "JSON_ARRAY";
   const maxParametersSize = options?.maxParametersSize ?? 100 * 1024;
   const autoStart = options?.autoStart ?? true;
 

packages/appkit-ui/src/react/hooks/use-chart-data.ts

@@ -17,8 +17,8 @@ export interface UseChartDataOptions {
   parameters?: Record<string, unknown>;
   /**
    * Data format preference
-   * - "json": Force JSON format
-   * - "arrow": Force Arrow format
+   * - "json_array": Force JSON format
+   * - "arrow_stream": Force Arrow format
    * - "auto": Auto-select based on heuristics
    * @default "auto"
    */
@@ -50,33 +50,32 @@ export interface UseChartDataResult {
 function resolveFormat(
   format: DataFormat,
   parameters?: Record<string, unknown>,
-): "JSON" | "ARROW" | "ARROW_STREAM" {
+): "JSON_ARRAY" | "ARROW_STREAM" {
   // Explicit format selection
-  if (format === "json") return "JSON";
-  if (format === "arrow") return "ARROW";
+  if (format === "json_array") return "JSON_ARRAY";
   if (format === "arrow_stream") return "ARROW_STREAM";
 
   // Auto-selection heuristics
   if (format === "auto") {
     // Check for explicit hint in parameters
-    if (parameters?._preferArrow === true) return "ARROW";
-    if (parameters?._preferJson === true) return "JSON";
+    if (parameters?._preferArrow === true) return "ARROW_STREAM";
+    if (parameters?._preferJson === true) return "JSON_ARRAY";
 
     // Check limit parameter as data size hint
     const limit = parameters?.limit;
     if (typeof limit === "number" && limit > ARROW_THRESHOLD) {
-      return "ARROW";
+      return "ARROW_STREAM";
     }
 
     // Check for date range queries (often large)
     if (parameters?.startDate && parameters?.endDate) {
-      return "ARROW";
+      return "ARROW_STREAM";
     }
 
-    return "ARROW_STREAM";
+    return "JSON_ARRAY";
   }
 
-  return "ARROW_STREAM";
+  return "JSON_ARRAY";
 }
 
 // ============================================================================
@@ -98,7 +97,7 @@ function resolveFormat(
  * // Force Arrow format
  * const { data } = useChartData({
  *   queryKey: "big_query",
- *   format: "arrow"
+ *   format: "arrow_stream"
  * });
  * ```
  */
@@ -111,7 +110,7 @@ export function useChartData(options: UseChartDataOptions): UseChartDataResult {
     [format, parameters],
   );
 
-  const isArrowFormat = resolvedFormat === "ARROW";
+  const isArrowFormat = resolvedFormat === "ARROW_STREAM";
 
   // Fetch data using the analytics query hook
   const {