Back to Details

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

各阶段必读内容

PhaseREAD BEFORE proceeding
ScaffoldingParent 
databricks
skill (auth, warehouse discovery)
Writing SQL queriesSQL Queries Guide
Writing UI componentsFrontend Guide
Using 
useAnalyticsQuery
AppKit SDK
Adding API endpointstRPC 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)

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

  1. Create SQL files in 
    config/queries/
  2. Run 
    npm run typegen
    — verify all queries show ✓
  3. Read 
    client/src/appKitTypes.d.ts
    to see generated types
  4. THEN write 
    App.tsx
    using the generated types
  5. Update 
    tests/smoke.spec.ts
    selectors
  6. Run 
    databricks apps validate
DO NOT write UI code before running typegen — types won't exist and you'll waste time on compilation errors.
  1. 在
    config/queries/
    目录下创建SQL文件
  2. 执行
    npm run typegen
    — 验证所有查询均显示✓
  3. 查看
    client/src/appKitTypes.d.ts
    文件以查看生成的类型
  4. 随后 使用生成的类型编写
    App.tsx
  5. 更新
    tests/smoke.spec.ts
    中的选择器
  6. 执行
    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。