databricks-apps について
Databricks Apps向けのカスタムアプリ開発スキルです。コーディングエージェントを対象に、データアクセスやストレージの選択から実装、検証までを案内します。
主な機能
- 01AppKitと他フレームワークの案内
- 02AnalyticsとLakebaseの選択手順
- 03SQL、UI、エンドポイント実装ガイド
- 04検証とスモークテストの説明
活用シーン
- 01Databricks Appの足場作成
- 02AnalyticsとLakebaseの選択
- 03データ表示またはチャットアプリの構築
- 04デプロイ前のアプリ検証
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ databricks/ databricks-agent-skills --skill databricks-appsインストール後、Claude Code で/databricks-appsを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
agents/openai.yamlassets/databricks.svgreferences/other-frameworks.mdplatform-guide.mdtesting.mdreferences/appkit/agents.mdappkit-sdk.mdcustom-endpoints.mdfiles.mdfrontend.mdgenie.mdimage-generation.mdjobs.mdlakebase.mdmetric-views.mdmodel-serving.mdoverview.mdproto-contracts.mdproto-first.mdsql-queries.md詳細
Databricks Apps の開発
まず、CLI の基本、認証、プロファイルの選択には親の databricks-core スキルを使用してください。
パッケージマネージャー — 以下のインストールやコマンドを実行する前に、必ずこれを特定してください。
Databricks Apps が公式にサポートしているのは npm と pnpm のみです。
- 次の優先順位でプロジェクトのパッケージマネージャーを特定します。プロジェクトの指示 →
package.jsonのpackageManagerフィールド → ロックファイル(pnpm-lock.yaml→ pnpm、package-lock.json→ npm)。 - 手掛かりが矛盾する場合、またはサポート対象外のパッケージマネージャー(yarn、bun など)が検出された場合は、作業を中断し、使用するパッケージマネージャーをユーザーに確認してから進めてください。
- パッケージマネージャーが特定できない場合に限り、pnpm を使用します。
このスキルとガイド全体で、特定したパッケージマネージャーに置き換えてください。
<pm>→ インストールとパッケージスクリプトで使用するパッケージマネージャー(<pm> install、<pm> run typegen)。
<pm> はドキュメント上のプレースホルダーであり、シェル変数ではありません。入力するのではなく、実際のパッケージマネージャーに置き換えてください。
これは本当に Databricks App ですか? データを表示する方法がアプリだけだと決めつけないでください。アプリ固有の要件がなく、「グラフが数個あるダッシュボード」のようなシンプルなものであれば、マネージド AI/BI(Lakeview)ダッシュボードの方が簡単です。その場合は、このスキルではなく databricks-aibi-dashboards スキルを使用してください。AI/BI では実現できない機能(独自のインタラクションやコンポーネント、書き戻し、埋め込み型または認証で制御されたワークフロー、アプリ内の Genie/チャット画面など)が必要な場合、またはユーザーが明示的にアプリを求めている場合に限り、カスタム Databricks App を選択してください。本当に判断が難しい場合は、アプリを前提にせず、マネージド AI/BI ダッシュボードとカスタムアプリの両方を提示し、ユーザーに選んでもらってください。アプリが適切な選択だと確認できた後は、このスキルでアプリベースのダッシュボードを優先しても問題ありません。適切な構築方法については databricks-app-design が扱います。
データ UI の設計(データを表示するすべてのアプリで必須):ユーザーがカスタムコードのアプリ(マネージド AI/BI ダッシュボードではないもの。上記参照)を希望していると確認したうえで、そのアプリが何らかのデータを表示する場合は、KPI/概要ページ、レポート、グラフ、テーブル、クエリ結果、会話型/チャット型/Genie の自然言語アシスタントのいずれであっても、レイアウト、グラフ、KPI、意味に沿った色使い、必要な状態、AI の結果に対する信頼性を判断し、それらを AppKit コンポーネントに対応付けるために、このスキルと併せて databricks-app-design スキルを必ず使用してください。これにはチャット/Genie アプリも含まれ、静的なデータ表示だけが対象ではありません。迷った場合は使用してください。
Databricks Apps プラットフォームにデプロイできるアプリを構築してください。
フェーズごとの必読ガイド
| フェーズ | 作業を進める前に読む |
|---|---|
| スキャフォールディング | ⚠️ STOP — スキャフォールディングの前に、State Storage Guidance を確認し、以下の Data Access Decision Gate を完了してください。 親の databricks-core スキル(認証、ウェアハウスの検出);その後、--features と --set を指定して databricks apps manifest + databricks apps init を実行します(以下の AppKit セクションを参照) |
| SQL クエリの作成 | SQL Queries Guide |
| UI コンポーネントの作成 | Frontend Guide |
useAnalyticsQuery の使用 | AppKit SDK |
| ガバナンス対象の UC Metric View のクエリ | Metric Views Guide |
| API エンドポイントの追加 | Custom Endpoints Guide |
| Lakebase(OLTP データベース)の使用 | Lakebase Guide |
| Genie チャット/Genie を活用したアプリの追加 | Genie Guide — 以下の Genie エージェントのワークフローに従ってください |
| Model Serving(ML 推論)の使用 | Model Serving Guide |
| 画像の生成または編集(テキストから画像、画像から画像) | Image Generation Guide |
| AI エージェントのホスティング(ツールを使用するチャットボット、ベータ版) | Agents Guide — @databricks/appkit/beta からインポートします |
| 型付きデータコントラクト(proto-first 設計) | Proto-First Guide と Plugin Contracts |
| UC Volumes 内のファイル管理 | Files Guide |
| アプリから Lakeflow Jobs をトリガー/監視 | Jobs Guide |
| プラットフォームのルール(権限、デプロイ、制限) | Platform Guide — AppKit を含むすべてのアプリで必ずお読みください |
| AppKit 以外のアプリ(Streamlit、FastAPI、Flask、Gradio、Next.js など) | Other Frameworks |
汎用ガイドライン
- アプリ名:Platform App のリソース名には、小文字、数字、ハイフンを最大 30 文字まで使用できます(アンダースコアは使用できません)。
databricks apps initで作成した AppKit プロジェクトでは、開発ワークフローによってdev-プレフィックスが追加されるため、ベース名は 26 文字以内にしてください。DABs ではこのプレフィックスは追加されません。 - 検証:デプロイ前に
databricks apps validate --profile <PROFILE>を実行します。 - スモークテスト(AppKit のみ):検証を実行する前に、必ず
tests/smoke.spec.tsのセレクターを更新してください。デフォルトのテンプレートは「Minimal Databricks App」という見出しと「hello world」というテキストをチェックします。カスタムアプリではこれらのチェックに必ず失敗します。テストガイドを参照してください。 - スモークテストのセレクター:Playwright のロケーター API(
getByRole、getByText、getByPlaceholder、getByLabel)のみを使用してください。Playwright にgetByLabelTextは存在しません(React Testing Library のメソッドです)。実行時にTypeErrorが発生します。テストガイドまたはnpx playwright codegenを参照してください。 - スモークテストのデータ:結果セットは、分析イベントのペイロード上限である 1 MB 未満にしてください。数千行を返すクエリは
INVALID_REQUEST: Event exceeds max size of 1048576 bytesとnet::ERR_ABORTEDを引き起こし、アサート対象の UI 要素がすべて表示されなくなります。LIMITまたは集計クエリ(例:COUNT(*) GROUP BY status)を使用し、未加工の行データをそのまま出力しないでください。 - AppKit のバージョン:
package.jsonの@databricks/appkitまたは@databricks/appkit-uiのバージョンを上書きしないでください。databricks apps initによって適切なバージョンが設定されます。ユーザーから明示的に依頼された場合を除き、どちらのパッケージも異なるバージョンをインストールしないでください。異なるバージョンが必要な場合は、databricks apps init --version <version>を使用して再度スキャフォールドしてください。 - 認証:親の
databricks-coreスキルで扱います。 - AppKit API の範囲:AppKit API(
createApp、プラグインの形状、useAnalyticsQuery、useMetricViewなど)を呼び出すコードを書く前に、npx @databricks/appkit docs <section>を実行し、実際のシグネチャを使用してください。トレーニングデータには古い形状が含まれており、シグネチャを 1 つでも誤って記述すると、検証中にtsc --noEmitが失敗します。ドキュメントはインストール済みの AppKit に含まれており、信頼できる情報源です。 - TypeScript の型アサーション:
as unknown as <T>の二重アサーションは使用しないでください。appkit lintはno-double-type-assertionを適用するため、違反が 1 つでもあると検証ステップ全体が失敗します。代わりに、Zod(z.infer<typeof schema>)で型を絞り込むか、実行時の型ガードを使用するか、型付きのマッパー関数を作成してください。クエリ結果の形状を変更する必要がある場合は、型アサーションではなく queryKey の型を使って行スキーマを型付けしてください。
プロジェクト構成(databricks apps init --features analytics の実行後)
client/src/App.tsx— メインの React コンポーネント(ここから始めます)config/queries/*.sql— SQL クエリファイル(queryKey = .sql を除いたファイル名)config/metric-views/definitions.json— ガバナンス対象の UC Metric View バインディング(任意。Metric Viewsを参照)server/server.ts— バックエンドのエントリーポイント(onPluginsReady+ Express ルート)tests/smoke.spec.ts— スモークテスト(⚠️ アプリに合わせてセレクターを必ず更新してください)client/src/appKitTypes.d.ts— 自動生成された型(<pm> run typegen)
プロジェクト構成(databricks apps init --features lakebase の実行後)
server/server.ts— Lakebase プールと Express ルートを含むバックエンドclient/src/App.tsx— React フロントエンドapp.yaml—databaseリソース宣言を含むマニフェストpackage.json—@databricks/lakebaseの依存関係を含みます- 注:
config/queries/はありません — Lakebase アプリでは SQL ファイルではなく、Express ルート内のappkit.lakebase.query()を使用します
データの調査
SQL を書く前に、データを調査するため、親の databricks-core スキルを使用します。キーワードで information_schema を検索してから、必要なテーブルの discover-schema をまとめて実行してください。この手順を省略しないでください。
状態の保存に関するガイダンス(判断ゲートの前に検討してください):
ユーザーのアプリの説明に、フォーム、CRUD 操作、ユーザーからの投稿、注文、ToDo、その他のユーザー生成コンテンツなど、データの保存や永続化が含まれる場合、そのアプリには Lakebase データベースが必要になる可能性があります。
- 足場を作成する前に、アプリに永続ストレージ(Lakebase)が必要かどうかをユーザーに確認してください。Lakebase を黙って追加してはいけません。
- 必要であることが確認できたら、Genie のフローと同様に、既存の Lakebase プロジェクトを再利用するか、新しく作成するかをユーザーに確認してください。決して黙って作成してはいけません。
databricks-lakebaseスキルを使用して、ブランチ名とデータベースのリソース名を取得します。- 再利用する場合:
databricks postgres list-projectsで一覧を取得してから、list-branches/list-databasesを実行し、プロジェクト、ブランチ、データベースをユーザーに選んでもらいます。アプリが所有するスキーマも確認してください(新規または専用のスキーマにすると、サービスプリンシパルの所有権に関する競合を避けられます)。 - 作成する場合: 新しいプロジェクトを作成します(
productionブランチとdatabricks_postgresデータベースが自動的にプロビジョニングされます)。
- 再利用する場合:
--features lakebaseを指定して足場を作成し、--set lakebase.postgres.branch=<BRANCH_NAME> --set lakebase.postgres.database=<DATABASE_NAME>を渡します。- アプリが Unity Catalog のテーブルも読み取る場合は、以下のデータアクセス判断ゲートに進み、
--features analyticsを追加するか、Lakebase の同期テーブルを使用するかを判断します。
ユーザーが永続的な書き戻しストレージを明示的に求めない限り、分析、ダッシュボード、可視化アプリに Lakebase を追加しないでください。読み取り専用のデータ表示、フィルター、設定にはデータベースは必要ありません。
開発ワークフロー(この順序を厳守)
データアクセス選択ゲート(スキャフォールディング前に必須):
アプリが Unity Catalog/レイクハウステーブルから読み取る場合は、必ず以下の比較をユーザーに提示し、どちらを選ぶか確認してください。省略したり、ユーザーに代わって選択したりしないでください。
| (A)Lakebase 同期テーブル | (B)Analytics | |
|---|---|---|
| 速度 | サブ秒の応答 | 数秒かかります |
| 最適な用途 | 全文検索、入力候補、オートコンプリート、リアルタイム検索、運用アプリ | ダッシュボード、グラフ、集計、KPI、フィルター付きクエリ、閲覧 |
| 仕組み | Delta のデータを Lakebase Postgres に同期 | 読み取り時に SQL ウェアハウスでクエリを実行 |
表を提示した後、簡単な推奨事項を加えてください。読み取り専用アプリの大半(ダッシュボード、グラフ、フィルター付きクエリ、閲覧、集計)には、デフォルトで Analytics(B)を推奨します。Lakebase 同期テーブル(A)は、全文検索、入力候補/オートコンプリート、ID によるリアルタイム検索、運用データの提供でサブ秒のレイテンシーが必要な場合に限って推奨してください。注:「検索」や「フィルター」という表現がプロンプトにある場合、通常は全文検索(Lakebase)ではなく SQL の WHERE 句(Analytics)を指します。最終的な決定は必ずユーザーに委ねてください。
ユーザーが選択した後:
- (A)Lakebase 同期テーブル →
--features lakebaseを指定してスキャフォールディングします。ワークフロー全体については Lakebase ガイド を参照してください。 - (B)Analytics →
--features analyticsを指定してスキャフォールディングします。Analytics 内で、データがガバナンス対象の UC Metric View(事前定義されたセマンティックなメジャー/ディメンション)である場合は、メトリックビュー用の方法でクエリします。Metric Views を参照してください。それ以外の場合は、config/queries/に SQL を記述します。 - 両方 → アプリで両方のパターンが必要な場合は、
--features analytics,lakebaseを指定してスキャフォールディングします。 - アプリが Unity Catalog のデータを読み取らない場合(純粋な CRUD、Genie、Model Serving)は、このゲートを省略し、適切な
--featuresフラグを指定してスキャフォールディングします。
Analytics アプリ(--features analytics):
config/queries/に SQL ファイルを作成します<pm> run typegenを実行し、すべてのクエリに ✓ が表示されることを確認しますclient/src/appKitTypes.d.tsを読み、生成された型を確認します- その後で、生成された型を使って
App.tsxを記述します tests/smoke.spec.tsのセレクターを更新しますdatabricks apps validate --profile <PROFILE>を実行します
typegen を実行する前に UI コードを書かないでください。 型が存在しないため、コンパイルエラーへの対応に時間を費やすことになります。
Lakebase アプリ(--features lakebase):SQL ファイルも typegen も不要です。onPluginsReady パターンについては Lakebase ガイド を参照してください。起動時にスキーマを初期化し、server/server.ts に Express ルートを登録してから、React フロントエンドを構築します。
用途に応じた選択
上記の判断ゲートを完了したら、次の振り分け表を使用してください。
- 分析データを読み取る → グラフ/テーブルに表示する:
queryKeyprop を使用する可視化コンポーネントを使用します - 分析データを読み取る → カスタム表示する(KPI、カード):
useAnalyticsQueryhook を使用します - 分析データを読み取る → 表示前に計算が必要:引き続き
useAnalyticsQueryを使用し、クライアント側で変換します - ガバナンス管理された UC Metric View(セマンティックレイヤー)を読み取る:
useMetricViewhook とconfig/metric-views/definitions.jsonを使用します。Metric Views を参照してください - レイクハウスのデータを低レイテンシで読み取る(検索、検索機能、カタログ):Lakebase の同期テーブルを使用します。Lakebase Guide を参照してください
- 永続データを読み書きする(ユーザー、注文、CRUD 状態):
onPluginsReadyの Express ルート経由で Lakebase を使用します。Lakebase Guide を参照してください - テーブルに対する自然言語クエリーインターフェース(Genie):
genie()plugin を使用します。Genie Guide を参照してください - ML モデルエンドポイントを呼び出す:
serving()plugin を使用します。Model Serving Guide を参照してください - 基盤モデル/UC モデルサービス(
system.ai.*)を呼び出す:uc_securable(MODEL_SERVICE)リソースを宣言し、/ai-gateway/mlflow/v1でサービス名を呼び出します。Unity Catalog model services とdatabricks-unity-gatewayスキルを参照してください(サービングエンドポイント名を受け取るserving()は使用しません) - プロンプトから画像を生成または編集する:画像対応の Foundation Model に対するストリーミング Express ルート(またはチャット UI 用の
agentsツール)とネイティブのfetchを使用します。Image Generation Guide を参照してください - ツール(SQL、ファイル、Genie、MCP)を 呼び出し、サブエージェントに委任し、または人間の承認を含む複数ターンのチャットをストリーミングする AI エージェント:
agents()plugin を使用します(@databricks/appkit/betaからインポート、ベータ版)。Agents Guide を参照してください - アプリから Lakeflow Job をトリガーまたは監視する:
jobs()plugin を使用します。Jobs Guide を参照してください - ⚠️ ウェアハウスに対して SELECT クエリーを実行するカスタムエンドポイントを追加しないでください — 必ず
config/queries/内の SQL ファイルを使用してください - ⚠️ Lakebase データに
useAnalyticsQueryを使用しないでください — この hook は SQL ウェアハウスのみをクエリーします
フレームワーク
AppKit(推奨)
型安全な SQL クエリーと組み込みコンポーネントを備えた TypeScript/React フレームワークです。
公式ドキュメント — すべての API 詳細の信頼できる情報源です。インストール済みの @databricks/appkit パッケージに含まれるプロジェクトローカルの appkit CLI を使用してください。
npx @databricks/appkit docs # ← ALWAYS start here to see available pages
npx @databricks/appkit docs <query> # view a section by name or doc path
npx @databricks/appkit docs --full # full index with all API entries
npx @databricks/appkit docs "appkit-ui API reference" # example: section by name
npx @databricks/appkit docs ./docs/plugins/analytics.md # example: specific doc file
ドキュメントのパスを推測しないでください。 まず引数なしで実行し、インデックスから選択してください。<query> 引数には、セクション名(インデックスに記載)とファイルパスの両方を指定できます。コンポーネントの props、hook のシグネチャ、サーバー API についてはドキュメントが正式な情報源です。スキルファイルではアンチパターンと注意点のみを扱います。
アプリマニフェストとスキャフォールディング
スキャフォールディングのエージェントワークフロー:まずマニフェストを取得し、その後 init コマンドを組み立てます。
- マニフェストを取得します(プラグインとそのリソースを記述した JSON スキーマ):
出力には次の内容が定義されています。databricks apps manifest --profile <PROFILE> # See plugins available in a specific AppKit version: databricks apps manifest --version <VERSION> --profile <PROFILE> # Custom template: databricks apps manifest --template <GIT_URL> --profile <PROFILE>- プラグイン:それぞれにキー(
--features用のプラグイン ID)があり、requiredByTemplateとresourcesも含まれます。 - requiredByTemplate:true の場合、そのプラグインはこのテンプレートで必須です。
--featuresに追加しないでください(自動的に含まれます)。ただし、必要なリソースはすべて--setで指定する必要があります。false または未指定の場合、そのプラグインは任意です。ユーザーのプロンプトでその機能(例:分析/SQL)が求められている場合に限り--featuresに追加し、その後、必要なリソースを--setで指定します。 - リソース:各プラグインには
resources.requiredとresources.optional(配列)があります。各項目にはresourceKeyとfields(フィールド名 → 説明/環境変数のオブジェクト)があります。含めるすべてのプラグインについて、必須リソースの各フィールドを--set <plugin>.<resourceKey>.<field>=<value>で指定してください。
- プラグイン:それぞれにキー(
- スキャフォールド(Databricks CLI のみを使用):
特定の AppKit バージョンを対象にするには、任意でdatabricks apps init --name <NAME> --features <plugin1>,<plugin2> \ --set <plugin1>.<resourceKey>.<field>=<value> \ --set <plugin2>.<resourceKey>.<field>=<value> \ --description "<DESC>" --run none --profile <PROFILE> # --run none: skip auto-run after scaffolding (review code first) # With custom template: databricks apps init --template <GIT_URL> --name <NAME> --features ... --set ... --profile <PROFILE>--version <VERSION>を使用します。- 必須:
--name、--profile。名前は26文字以下で、小文字の英字、数字、ハイフンのみを使用します。--featuresは、ユーザーが希望する任意のプラグイン(requiredByTemplate: falseまたは未指定のプラグイン)にのみ使用してください。必須プラグインを--featuresに指定してはいけません。 - リソース:(1)
requiredByTemplate: trueのすべてのプラグイン、および (2)--featuresに追加した任意のプラグインについて、必須リソース(各resources.required内の項目)ごとに--setを指定します。resources.optionalの項目は、ユーザーが希望する場合にのみ--setを追加します。 - 特定:親の
databricks-coreスキルを使用して ID を特定します(例:ウェアハウスの場合はdatabricks warehouses list --profile <PROFILE>またはdatabricks experimental aitools tools get-default-warehouse --profile <PROFILE>)。
- 必須:
プラグイン名、リソースキー、プロパティ名を推測してはいけません。必ず databricks apps manifest の出力から確認してください。例:マニフェストに、必須リソースの resourceKey: "sql-warehouse" と fields: { "id": ... } を持つプラグイン analytics が表示された場合は、--set analytics.sql-warehouse.id=<ID> を含めます。
**実行 ID(認証モード)**には databricks CLI >= v1.20.0 が必要です(認証モード機能が初めて追加されたリリースであり、v1.19.0 以前にはありません)。これに対応していない CLI にはこれらのフラグが存在せず、すべてのリソースがサービスプリンシパルにバインドされるため、以下のフラグを使用してはいけません。デフォルトでは、すべてのリソースは引き続きサービスプリンシパル(SP)にバインドされます。これらのフラグを省略すると、以前とまったく同じ出力になります。
--auth-mode obo|spは、アプリ全体のデフォルトを設定します。デフォルトはspです。--auth-mode oboは、ユーザーに代わって実行できるリソースにのみ適用されます。実行できないリソース(例:secret、Lakebase)は SP のままとなり、CLI はそれらを列挙したメモを表示します。--auth-mode bothはアプリレベルでは無効です。--set <plugin>.<resourceKey>.authMode=obo|sp|bothは、1つのリソースの ID を設定し、アプリ全体のデフォルトを上書きします。bothが有効なのは、ここでリソースごとに指定する場合のみです。- OBO で実行できないリソースに
authModeを明示的に設定すると、エラーになります(CLI は該当リソースと修正方法を示します)。 - 対話型の認証プロンプト(Service principal / On behalf of user / Mixed)が表示されるのは、完全な対話型フローの場合のみです。
--featuresまたは--setを渡すとプロンプトは表示されず、デフォルトの SP が使用されます。
各モードで出力される内容と、databricks apps validate による OBO のチェックについては、Platform Guide を参照してください。デフォルトは SP とし、アプリで閲覧ユーザー自身の権限を適用する必要がある場合(行レベルまたはユーザーごとのデータアクセス)にのみ OBO を選択してください。分析用ウェアハウスを OBO、ジョブを SP とするなど、混合構成は一般的です。
Scaffolding Rules Protocol — databricks apps manifest は、テンプレートレベル(トップレベルの scaffolding.rules)および個別のプラグイン(plugins[].scaffolding.rules)に scaffolding.rules を出力することがあります。各ブロックには、短い指示文字列の配列 must / should / never が含まれます。以下のように扱います:
- 収集 — 最終的な
--featuresリストに含まれる各プラグインと、requiredByTemplate: trueの各プラグインについて、plugins[].scaffolding.rulesを読み取ります。それらにトップレベルのテンプレートscaffolding.rulesを加えて、出所(テンプレートまたは<plugin>)をタグ付けした作業セットを1つ作成します。 - 優先順位 — マニフェストのルールは、このスキルに組み込まれた指示より優先されます。マニフェストに記述のない項目については、このスキルの内容を最低限の基準とします。
- フェーズの順序 — テキストが
Before initで始まるルールは、databricks apps initの実行前に必ず実行します。After initで始まるルールは、初期化の完了後に必ず実行します(例:マイグレーション、型生成、接続チェック)。フェーズの接頭辞がないルールは、スキャフォールド/開発の全工程に適用されます。 - 競合の検出 — プラグインの
mustルールが、同じ対象についてテンプレートのneverルールと矛盾する場合(またはその逆の場合)は、作業を停止し、先にどちらに従うかをユーザーに確認します。どちらかを黙って選んではいけません。同じ操作に対するmustとneverは競合として扱います。shouldは推奨事項であり、作業を妨げるものではありません。 - 報告 —
databricks apps initの実行前に、統合した作業セットをフェーズ(Before init/After init/Always)ごと、重大度(must/should/never)ごとに分類してユーザーに提示し、有効なガードレールを明示します。
プロジェクト構造、ワークフロー、実装前チェックリストについては、AppKit Overview を読んでください。
Genie エージェントのワークフロー — ユーザーが Genie を利用するアプリを希望する場合、最初に Genie Space ID を尋ねてはいけません。代わりに、次の手順に従います。
- アプリでクエリする Unity Catalog のテーブルを尋ねます(完全修飾名:
catalog.schema.table)。 - 既存の Genie space を再利用するか、新しく作成するかを尋ねます。
- 新規作成する場合:ウェアハウスを特定してから、
databricks genie create-spaceで space を作成します(構文とシリアライズされた space の形式については、Genie Guide を参照してください)。 - 再利用する場合:
databricks genie list-spaces --profile <PROFILE>で既存の space を特定し、ユーザーに選んでもらいます。 - space ID をアプリにスキャフォールドするか、アプリに設定します —
databricks apps manifestから--setのキーを導き出します。
設定、SSE エンドポイント、フロントエンドとの連携については、Genie Guide を読んでください。
よくあるスキャフォールディングの間違い
# ❌ WRONG: name is NOT a positional argument
databricks apps init --features analytics my-app-name
# → "unknown command" error
# ✅ CORRECT: use --name flag
databricks apps init --name my-app-name --features analytics --set "..." --profile <PROFILE>
ディレクトリ名
databricks apps init は、アプリ名に合わせたケバブケースのディレクトリを作成します。
アプリ名は小文字とハイフンのみを使用し、26文字以下である必要があります。
その他のフレームワーク(Streamlit、FastAPI、Flask、Gradio、Dash、Next.js など)
Databricks Apps は、HTTP サーバーとして動作するあらゆるフレームワークをサポートしています。LLM はすでにこれらのフレームワークを把握しています。課題となるのは、Databricks プラットフォームとの連携です。
AppKit 以外のアプリを構築する前に、**Other Frameworks Guide を読んでください。**ポート/ホストの設定、app.yaml と databricks.yml の設定、依存関係の管理、ネットワーク、フレームワーク固有の注意点について説明しています。
デプロイ後の検証
デプロイ後、アプリが実行中であることを確認します。
databricks apps get <app-name> --profile <PROFILE> -o json # Check app_status.state: RUNNING; the `url` field is the app's URL
databricks apps logs <app-name> --follow --profile <PROFILE> # Stream live logs (Ctrl+C to stop)
注:
databricks apps logsには OAuth 認証が必要で、PAT では動作しません。PAT 認証を使用する場合は、ステータス確認にdatabricks apps getを使用してください。