feat: add INLINE + ARROW_STREAM format support for analytics plugin

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" | "auto";
+export type DataFormat = "json" | "arrow" | "arrow_stream" | "auto";
 
 /** Chart orientation */
 export type Orientation = "vertical" | "horizontal";

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

@@ -205,7 +205,7 @@ describe("useChartData", () => {
       );
     });
 
-    test("auto-selects JSON by default when no heuristics match", () => {
+    test("auto-selects ARROW_STREAM 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: "JSON" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
 
-    test("defaults to auto format (JSON) when format is not specified", () => {
+    test("defaults to auto format (ARROW_STREAM) when format is not specified", () => {
       mockUseAnalyticsQuery.mockReturnValue({
         data: [],
         loading: false,
@@ -243,7 +243,7 @@ describe("useChartData", () => {
       expect(mockUseAnalyticsQuery).toHaveBeenCalledWith(
         "test",
         undefined,
-        expect.objectContaining({ format: "JSON" }),
+        expect.objectContaining({ format: "ARROW_STREAM" }),
       );
     });
   });

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";
+export type AnalyticsFormat = "JSON" | "ARROW" | "ARROW_STREAM";
 
 /**
  * Typed Arrow Table - preserves row type information for type inference.
@@ -32,8 +32,10 @@ export interface TypedArrowTable<
 // ============================================================================
 
 /** Options for configuring an analytics SSE query */
-export interface UseAnalyticsQueryOptions<F extends AnalyticsFormat = "JSON"> {
-  /** Response format - "JSON" returns typed arrays, "ARROW" returns TypedArrowTable */
+export interface UseAnalyticsQueryOptions<
+  F extends AnalyticsFormat = "ARROW_STREAM",
+> {
+  /** Response format - "ARROW_STREAM" (default) uses inline Arrow, "JSON" returns typed arrays, "ARROW" uses external links */
   format?: F;
 
   /** Maximum size of serialized parameters in bytes */

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

@@ -54,13 +54,13 @@ function getArrowStreamUrl(id: string) {
 export function useAnalyticsQuery<
   T = unknown,
   K extends QueryKey = QueryKey,
-  F extends AnalyticsFormat = "JSON",
+  F extends AnalyticsFormat = "ARROW_STREAM",
 >(
   queryKey: K,
   parameters?: InferParams<K> | null,
   options: UseAnalyticsQueryOptions<F> = {} as UseAnalyticsQueryOptions<F>,
 ): UseAnalyticsQueryResult<InferResultByFormat<T, K, F>> {
-  const format = options?.format ?? "JSON";
+  const format = options?.format ?? "ARROW_STREAM";
   const maxParametersSize = options?.maxParametersSize ?? 100 * 1024;
   const autoStart = options?.autoStart ?? true;
 

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

@@ -50,10 +50,11 @@ export interface UseChartDataResult {
 function resolveFormat(
   format: DataFormat,
   parameters?: Record<string, unknown>,
-): "JSON" | "ARROW" {
+): "JSON" | "ARROW" | "ARROW_STREAM" {
   // Explicit format selection
   if (format === "json") return "JSON";
   if (format === "arrow") return "ARROW";
+  if (format === "arrow_stream") return "ARROW_STREAM";
 
   // Auto-selection heuristics
   if (format === "auto") {
@@ -72,10 +73,10 @@ function resolveFormat(
       return "ARROW";
     }
 
-    return "JSON";
+    return "ARROW_STREAM";
   }
 
-  return "JSON";
+  return "ARROW_STREAM";
 }
 
 // ============================================================================

packages/appkit/src/connectors/sql-warehouse/defaults.ts

@@ -12,7 +12,7 @@ interface ExecuteStatementDefaults {
 export const executeStatementDefaults: ExecuteStatementDefaults = {
   wait_timeout: "30s",
   disposition: "INLINE",
-  format: "JSON_ARRAY",
+  format: "ARROW_STREAM",
   on_wait_timeout: "CONTINUE",
   timeout: 60000,
 };

packages/appkit/src/plugins/analytics/analytics.ts

@@ -19,6 +19,7 @@ import { queryDefaults } from "./defaults";
 import manifest from "./manifest.json";
 import { QueryProcessor } from "./query";
 import type {
+  AnalyticsFormat,
   AnalyticsQueryResponse,
   IAnalyticsConfig,
   IAnalyticsQueryRequest,
@@ -119,7 +120,8 @@ export class AnalyticsPlugin extends Plugin {
     res: express.Response,
   ): Promise<void> {
     const { query_key } = req.params;
-    const { parameters, format = "JSON" } = req.body as IAnalyticsQueryRequest;
+    const { parameters, format = "ARROW_STREAM" } =
+      req.body as IAnalyticsQueryRequest;
 
     // Request-scoped logging with WideEvent tracking
     logger.debug(req, "Executing query: %s (format=%s)", query_key, format);
@@ -155,19 +157,6 @@ export class AnalyticsPlugin extends Plugin {
     const userKey = getCurrentUserId();
     const executorKey = isAsUser ? userKey : "global";
 
-    const queryParameters =
-      format === "ARROW"
-        ? {
-            formatParameters: {
-              disposition: "EXTERNAL_LINKS",
-              format: "ARROW_STREAM",
-            },
-            type: "arrow",
-          }
-        : {
-            type: "result",
-          };
-
     const hashedQuery = this.queryProcessor.hashQuery(query);
 
     const defaultConfig: PluginExecuteConfig = {
@@ -197,20 +186,115 @@ export class AnalyticsPlugin extends Plugin {
           parameters,
         );
 
-        const result = await executor.query(
+        return this._executeWithFormatFallback(
+          executor,
           query,
           processedParams,
-          queryParameters.formatParameters,
+          format,
           signal,
         );
-
-        return { type: queryParameters.type, ...result };
       },
       streamExecutionSettings,
       executorKey,
     );
   }
 
+  /** Format configurations in fallback order. */
+  private static readonly FORMAT_CONFIGS = {
+    ARROW_STREAM: {
+      formatParameters: { disposition: "INLINE", format: "ARROW_STREAM" },
+      type: "result" as const,
+    },
+    JSON: {
+      formatParameters: undefined,
+      type: "result" as const,
+    },
+    ARROW: {
+      formatParameters: {
+        disposition: "EXTERNAL_LINKS",
+        format: "ARROW_STREAM",
+      },
+      type: "arrow" as const,
+    },
+  };
+
+  /**
+   * Execute a query with automatic format fallback.
+   *
+   * For the default ARROW_STREAM format, tries formats in order until one
+   * succeeds: ARROW_STREAM → JSON → ARROW. This handles warehouses that
+   * only support a subset of format/disposition combinations.
+   *
+   * Explicit format requests (JSON, ARROW) are not retried.
+   */
+  private async _executeWithFormatFallback(
+    executor: AnalyticsPlugin,
+    query: string,
+    processedParams:
+      | Record<string, SQLTypeMarker | null | undefined>
+      | undefined,
+    requestedFormat: AnalyticsFormat,
+    signal?: AbortSignal,
+  ): Promise<{ type: string; [key: string]: any }> {
+    // Explicit format — no fallback.
+    if (requestedFormat === "JSON" || requestedFormat === "ARROW") {
+      const config = AnalyticsPlugin.FORMAT_CONFIGS[requestedFormat];
+      const result = await executor.query(
+        query,
+        processedParams,
+        config.formatParameters,
+        signal,
+      );
+      return { type: config.type, ...result };
+    }
+
+    // Default (ARROW_STREAM) — try each format in order.
+    const fallbackOrder: AnalyticsFormat[] = ["ARROW_STREAM", "JSON", "ARROW"];
+
+    for (let i = 0; i < fallbackOrder.length; i++) {
+      const fmt = fallbackOrder[i];
+      const config = AnalyticsPlugin.FORMAT_CONFIGS[fmt];
+      try {
+        const result = await executor.query(
+          query,
+          processedParams,
+          config.formatParameters,
+          signal,
+        );
+        if (i > 0) {
+          logger.info(
+            "Query succeeded with fallback format %s (preferred %s was rejected)",
+            fmt,
+            fallbackOrder[0],
+          );
+        }
+        return { type: config.type, ...result };
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const isFormatError =
+          msg.includes("ARROW_STREAM") ||
+          msg.includes("JSON_ARRAY") ||
+          msg.includes("EXTERNAL_LINKS") ||
+          msg.includes("INVALID_PARAMETER_VALUE") ||
+          msg.includes("NOT_IMPLEMENTED");
+
+        if (!isFormatError || i === fallbackOrder.length - 1) {
+          throw err;
+        }
+
+        logger.warn(
+          "Format %s rejected by warehouse, falling back to %s: %s",
+          fmt,
+          fallbackOrder[i + 1],
+          msg,
+        );
+      }
+    }
+
+    // Unreachable — last format in fallbackOrder throws on failure.
+    throw new Error("All format fallbacks exhausted");
+  }
+
   /**
    * Execute a SQL query using the current execution context.
    *