databricks-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Databricks Apps Development

Databricks Apps 开发

FIRST: Use the parent

databricks

skill for CLI basics, authentication, profile selection, and data exploration commands.

Build apps that deploy to Databricks Apps platform.

首先：使用父级

databricks

技能来处理CLI基础操作、身份验证、配置文件选择和数据探索命令。

构建可部署到Databricks Apps平台的应用。

Required Reading by Phase

各阶段必读内容

Phase	READ BEFORE proceeding
Scaffolding	Parent `databricks` skill (auth, warehouse discovery)
Writing SQL queries	SQL Queries Guide
Writing UI components	Frontend Guide
Using `useAnalyticsQuery`	AppKit SDK
Adding API endpoints	tRPC Guide

阶段	开始前必读
项目搭建	父级 `databricks` 技能（身份验证、数据仓库发现）
编写SQL查询	SQL查询指南
编写UI组件	前端指南
使用 `useAnalyticsQuery`	AppKit SDK
添加API端点	tRPC指南

Generic Guidelines

通用指南

These apply regardless of framework:

Deployment:

databricks apps deploy --profile <PROFILE>

(⚠️ USER CONSENT REQUIRED)

Validation:
```
databricks apps validate
```
before deploying
App name: Must be ≤26 characters, lowercase letters/numbers/hyphens only (no underscores). dev- prefix adds 4 chars, max 30 total.
Smoke tests: ALWAYS update
```
tests/smoke.spec.ts
```
selectors BEFORE running validation. Default template checks for "Minimal Databricks App" heading and "hello world" text — these WILL fail in your custom app. See testing guide.
Authentication: covered by parent
```
databricks
```
skill

以下规则适用于所有框架：

部署：

databricks apps deploy --profile <PROFILE>

（⚠️ 需要用户同意）

验证：部署前执行
```
databricks apps validate
```
应用名称：长度必须≤26个字符，仅允许小写字母、数字和连字符（不能使用下划线）。添加dev-前缀会占用4个字符，总长度最大为30。
冒烟测试：运行验证前务必更新
```
tests/smoke.spec.ts
```
中的选择器。默认模板会检查“Minimal Databricks App”标题和“hello world”文本——在自定义应用中这些检查会失败。请参阅测试指南。
身份验证：由父级
```
databricks
```
技能覆盖

Project Structure (after

databricks apps init --features analytics

)

项目结构（执行

databricks apps init --features analytics

后）

```
client/src/App.tsx
```
— main React component (start here)
```
config/queries/*.sql
```
— SQL query files (queryKey = filename without .sql)
```
server/server.ts
```
— backend entry (tRPC routers)
```
tests/smoke.spec.ts
```
— smoke test (⚠️ MUST UPDATE selectors for your app)

client/src/appKitTypes.d.ts

— auto-generated types (

npm run typegen

)

```
client/src/App.tsx
```
— 主React组件（从此处开始开发）
```
config/queries/*.sql
```
— SQL查询文件（queryKey为不带.sql的文件名）
```
server/server.ts
```
— 后端入口（tRPC路由）
```
tests/smoke.spec.ts
```
— 冒烟测试（⚠️ 必须为你的应用更新选择器）
```
client/src/appKitTypes.d.ts
```
— 自动生成的类型文件（执行
```
npm run typegen
```
生成）

Development Workflow (FOLLOW THIS ORDER)

开发流程（请按此顺序执行）

Create SQL files in
```
config/queries/
```
Run
```
npm run typegen
```
— verify all queries show ✓
Read
```
client/src/appKitTypes.d.ts
```
to see generated types
THEN write
```
App.tsx
```
using the generated types
Update
```
tests/smoke.spec.ts
```
selectors
Run
```
databricks apps validate
```

DO NOT write UI code before running typegen — types won't exist and you'll waste time on compilation errors.

在
```
config/queries/
```
目录下创建SQL文件
执行
```
npm run typegen
```
— 验证所有查询均显示✓
查看
```
client/src/appKitTypes.d.ts
```
文件以查看生成的类型
随后使用生成的类型编写
```
App.tsx
```
更新
```
tests/smoke.spec.ts
```
中的选择器
执行
```
databricks apps validate
```

请勿在执行typegen前编写UI代码——此时类型尚未生成，会导致编译错误，浪费时间。

When to Use What

场景使用指南

Read data → display in chart/table: Use visualization components with
```
queryKey
```
prop
Read data → custom display (KPIs, cards): Use
```
useAnalyticsQuery
```
hook
Read data → need computation before display: Still use
```
useAnalyticsQuery
```
, transform client-side
Call ML model endpoint: Use tRPC
Write/update data (INSERT/UPDATE/DELETE): Use tRPC
⚠️ NEVER use tRPC to run SELECT queries — always use SQL files in
```
config/queries/
```

读取数据→在图表/表格中展示：使用带有
```
queryKey
```
属性的可视化组件
读取数据→自定义展示（关键指标、卡片）：使用
```
useAnalyticsQuery
```
钩子
读取数据→展示前需计算：仍使用
```
useAnalyticsQuery
```
，在客户端进行数据转换
调用机器学习模型端点：使用tRPC
写入/更新数据（INSERT/UPDATE/DELETE）：使用tRPC
⚠️ 切勿使用tRPC执行SELECT查询 — 请始终使用
```
config/queries/
```
目录下的SQL文件

Frameworks

支持的框架

AppKit (Recommended)

AppKit（推荐使用）

TypeScript/React framework with type-safe SQL queries and built-in components.

Official Documentation — the source of truth for all API details:

bash

npx @databricks/appkit docs              # ← ALWAYS start here to see available pages
npx @databricks/appkit docs <path>       # then use paths from the index

DO NOT guess doc paths. Run without args first, pick from the index. Docs are the authority on component props, hook signatures, and server APIs — skill files only cover anti-patterns and gotchas.

Scaffold (requires

--warehouse-id

, see parent skill; DO NOT use

npx

bash

databricks apps init --description "<DESC>" --features analytics --warehouse-id <ID> --name <NAME> --run none --profile <PROFILE>

READ AppKit Overview for project structure, workflow, and pre-implementation checklist.

基于TypeScript/React的框架，提供类型安全的SQL查询和内置组件。

官方文档 — 所有API细节的权威来源：

bash

npx @databricks/appkit docs              # ← 请始终从此处开始查看可用页面
npx @databricks/appkit docs <path>       # 然后使用索引中的路径

请勿猜测文档路径。请先不带参数运行命令，从索引中选择路径。文档是组件属性、钩子签名和服务器API的权威参考——本技能仅涵盖反模式和常见陷阱。

项目搭建（需要

--warehouse-id

参数，请参阅父级技能；请勿使用

npx

）：

bash

databricks apps init --description "<DESC>" --features analytics --warehouse-id <ID> --name <NAME> --run none --profile <PROFILE>

**请阅读AppKit 概述**以了解项目结构、工作流程和实施前检查清单。

Other Frameworks

其他框架

Databricks Apps supports any framework that can run as a web server (Flask, FastAPI, Streamlit, Gradio, etc.). Use standard framework documentation - this skill focuses on AppKit.

Databricks Apps支持所有可作为Web服务器运行的框架（Flask、FastAPI、Streamlit、Gradio等）。请使用各框架的标准文档——本技能重点介绍AppKit。

databricks-apps

Original

Translation

Databricks Apps Development

Databricks Apps 开发

Required Reading by Phase

各阶段必读内容

Generic Guidelines

通用指南

Project Structure (after
`databricks apps init --features analytics`
)

项目结构（执行
`databricks apps init --features analytics`
后）

Development Workflow (FOLLOW THIS ORDER)

开发流程（请按此顺序执行）

When to Use What

场景使用指南

Frameworks

支持的框架

AppKit (Recommended)

AppKit（推荐使用）

Other Frameworks

其他框架

databricks-apps

Original

Translation

Databricks Apps Development

Databricks Apps 开发

Required Reading by Phase

各阶段必读内容

Generic Guidelines

通用指南

Project Structure (after databricks apps init --features analytics)

项目结构（执行databricks apps init --features analytics后）

Development Workflow (FOLLOW THIS ORDER)

开发流程（请按此顺序执行）

When to Use What

场景使用指南

Frameworks

支持的框架

AppKit (Recommended)

AppKit（推荐使用）

Other Frameworks

其他框架

Project Structure (after
`databricks apps init --features analytics`
)

项目结构（执行
`databricks apps init --features analytics`
后）