@databricks/appkit-ui 0.12.1 → 0.12.2

package/docs/plugins/analytics.md

@@ -21,11 +21,18 @@ await createApp({
 
 ```
 
-## Where queries live[​](#where-queries-live "Direct link to Where queries live")
+## Query files[​](#query-files "Direct link to Query files")
 
 * Put `.sql` files in `config/queries/`
 * Query key is the filename without `.sql` (e.g. `spend_summary.sql` → `"spend_summary"`)
 
+### Execution context[​](#execution-context "Direct link to Execution context")
+
+* `queryKey.sql` executes as **service principal** (shared cache)
+* `queryKey.obo.sql` executes as **user** (OBO = on-behalf-of, per-user cache)
+
+The execution context is determined by the SQL file name, not by the hook call.
+
 ## SQL parameters[​](#sql-parameters "Direct link to SQL parameters")
 
 Use `:paramName` placeholders and optionally annotate parameter types using SQL comments:
@@ -64,3 +71,99 @@ The analytics plugin exposes these endpoints (mounted under `/api/analytics`):
 
 * `format: "JSON"` (default) returns JSON rows
 * `format: "ARROW"` returns an Arrow "statement\_id" payload over SSE, then the client fetches binary Arrow from `/api/analytics/arrow-result/:jobId`
+
+## Frontend usage[​](#frontend-usage "Direct link to Frontend usage")
+
+### useAnalyticsQuery[​](#useanalyticsquery "Direct link to useAnalyticsQuery")
+
+React hook that subscribes to an analytics query over SSE and returns its latest result.
+
+```ts
+import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
+
+const { data, loading, error } = useAnalyticsQuery(queryKey, parameters, options);
+
+```
+
+**Return type:**
+
+```ts
+{
+  data: T | null;      // query result (typed array for JSON, TypedArrowTable for ARROW)
+  loading: boolean;    // true while the query is executing
+  error: string | null; // error message, or null on success
+}
+
+```
+
+**Options:**
+
+| Option              | Type                | Default  | Description                             |
+| ------------------- | ------------------- | -------- | --------------------------------------- |
+| `format`            | `"JSON" \| "ARROW"` | `"JSON"` | Response format                         |
+| `maxParametersSize` | `number`            | `102400` | Max serialized parameters size in bytes |
+| `autoStart`         | `boolean`           | `true`   | Start query on mount                    |
+
+**Example with loading/error/empty handling:**
+
+```tsx
+import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
+import { sql } from "@databricks/appkit-ui/js";
+import { Skeleton } from "@databricks/appkit-ui";
+
+function SpendTable() {
+  const params = useMemo(() => ({
+    startDate: sql.date("2025-01-01"),
+    endDate: sql.date("2025-12-31"),
+  }), []);
+
+  const { data, loading, error } = useAnalyticsQuery("spend_summary", params);
+
+  if (loading) return <Skeleton className="h-32 w-full" />;
+  if (error) return <div className="text-destructive">{error}</div>;
+  if (!data?.length) return <div className="text-muted-foreground">No results</div>;
+
+  return (
+    <ul>
+      {data.map((row) => (
+        <li key={row.id}>{row.name}: ${row.cost_usd}</li>
+      ))}
+    </ul>
+  );
+}
+
+```
+
+### Type-safe queries[​](#type-safe-queries "Direct link to Type-safe queries")
+
+Augment the `QueryRegistry` interface to get full type inference on parameters and results:
+
+```ts
+// config/appKitTypes.d.ts
+declare module "@databricks/appkit-ui/react" {
+  interface QueryRegistry {
+    spend_summary: {
+      name: "spend_summary";
+      parameters: { startDate: string; endDate: string };
+      result: Array<{ id: string; name: string; cost_usd: number }>;
+    };
+  }
+}
+
+```
+
+See [Type generation](./docs/development/type-generation.md) for automatic generation from SQL files.
+
+### Memoization[​](#memoization "Direct link to Memoization")
+
+**Always wrap parameters in `useMemo`** to avoid refetch loops. The hook re-executes whenever the parameters reference changes:
+
+```ts
+// Good
+const params = useMemo(() => ({ status: sql.string("active") }), []);
+const { data } = useAnalyticsQuery("users", params);
+
+// Bad - creates a new object every render, causing infinite refetches
+const { data } = useAnalyticsQuery("users", { status: sql.string("active") });
+
+```

package/docs/plugins/server.md

@@ -31,7 +31,7 @@ The Server plugin uses the deferred initialization phase to access routes from o
 The smallest valid AppKit server:
 
 ```ts
-// server/index.ts
+// server/server.ts
 import { createApp, server } from "@databricks/appkit";
 
 await createApp({

package/docs.md

@@ -21,7 +21,38 @@ AppKit simplifies building data applications on Databricks by providing:
 * [Node.js](https://nodejs.org) v22+ environment with `npm`
 * Databricks CLI (v0.287.0 or higher): install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
 
-## Quick start[​](#quick-start "Direct link to Quick start")
+## Quick start options[​](#quick-start-options "Direct link to Quick start options")
+
+There are two ways to get started with AppKit:
+
+* **AI-assisted** (recommended): Use an AI coding assistant with Agent Skills to explore data, run CLI commands, and scaffold your app interactively.
+* **Manual**: Use the Databricks CLI directly to create, bootstrap, and deploy your app.
+
+Choose the path that best fits your workflow; both approaches produce the same kind of AppKit-based Databricks application.
+
+## AI-first quick start[​](#ai-first-quick-start "Direct link to AI-first quick start")
+
+Databricks AppKit is designed to work with AI coding assistants through Agent Skills.
+
+Install Agent Skills and configure it for use with your preferred AI assistant:
+
+```bash
+databricks experimental aitools skills install
+
+```
+
+Once configured for your development environment, you can use your AI assistant to create and deploy new Databricks applications, as well as to iteratively evolve your app's codebase.
+
+Just prompt your AI assistant to create a new Databricks app, such as:
+
+```text
+Create a new Databricks app that displays a dashboard of the nyc taxi trips dataset.
+
+```
+
+To learn more about the Agent Skills, see the [AI-assisted development](./docs/development/ai-assisted-development.md) documentation.
+
+## Manual quick start[​](#manual-quick-start "Direct link to Manual quick start")
 
 Learn how to create and deploy a sample Databricks application that uses AppKit with the Databricks CLI.
 

package/llms.txt

@@ -26,14 +26,14 @@ npx @databricks/appkit docs <query>
 - [Architecture](./docs/architecture.md): AppKit follows a plugin-based architecture designed for building production-ready Databricks applications. This document provides a high-level overview of the system components and their interactions.
 - [Configuration](./docs/configuration.md): This guide covers environment variables and configuration options for AppKit applications.
 - [Core principles](./docs/core-principles.md): Learn about the fundamental concepts and principles behind AppKit.
-- [Development](./docs/development.md): AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with MCP, and remote tunneling to deployed backends.
+- [Development](./docs/development.md): AppKit provides multiple development workflows to suit different needs: local development with hot reload, AI-assisted development with Agent Skills, and remote tunneling to deployed backends.
 - [Plugins](./docs/plugins.md): Plugins are modular extensions that add capabilities to your AppKit application. They follow a defined lifecycle and have access to shared services like caching, telemetry, and streaming.
 
 ## Development
 
-- [AI-Assisted development](./docs/development/ai-assisted-development.md): AppKit-specific agent skills for AI coding assistants are coming soon. This documentation will be updated with instructions when available.
+- [AI-Assisted development](./docs/development/ai-assisted-development.md): AppKit integrates with AI coding assistants through the Agent Skills.
 - [LLM Guide](./docs/development/llm-guide.md): This document provides prescriptive guidance for AI coding assistants generating code with Databricks AppKit. It is intentionally opinionated to ensure consistent, production-ready code generation.
-- [Local development](./docs/development/local-development.md): Once your app is bootstrapped according to the Quick start guide, you can start the development server with hot reload for both UI and backend code.
+- [Local development](./docs/development/local-development.md): Once your app is bootstrapped according to the Manual quick start guide, you can start the development server with hot reload for both UI and backend code.
 - [Project setup](./docs/development/project-setup.md): This guide covers the recommended project structure and scaffolding for AppKit applications.
 - [Remote Bridge](./docs/development/remote-bridge.md): Remote bridge allows you to develop against a deployed backend while keeping your UI and queries local. This is useful for testing against production data or debugging deployed backend code without redeploying your app.
 - [Type generation](./docs/development/type-generation.md): AppKit can automatically generate TypeScript types for your SQL queries, providing end-to-end type safety from database to UI.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/databricks/appkit.git"