mcpField
D
databricks-apps

databricks-apps

github.com/databricks開発3731.1k 回インストール今日更新
リポジトリ

databricks-apps について

Databricks Apps向けのカスタムアプリ開発スキルです。コーディングエージェントを対象に、データアクセスやストレージの選択から実装、検証までを案内します。

主な機能

  1. 01AppKitと他フレームワークの案内
  2. 02AnalyticsとLakebaseの選択手順
  3. 03SQL、UI、エンドポイント実装ガイド
  4. 04検証とスモークテストの説明

活用シーン

  1. 01Databricks Appの足場作成
  2. 02AnalyticsとLakebaseの選択
  3. 03データ表示またはチャットアプリの構築
  4. 04デプロイ前のアプリ検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/databricks/databricks-agent-skills --skill databricks-apps

インストール後、Claude Code で/databricks-appsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

agents/
openai.yaml
assets/
databricks.svg
references/
other-frameworks.md
platform-guide.md
testing.md
references/appkit/
agents.md
appkit-sdk.md
custom-endpoints.md
files.md
frontend.md
genie.md
image-generation.md
jobs.md
lakebase.md
metric-views.md
model-serving.md
overview.md
proto-contracts.md
proto-first.md
sql-queries.md

詳細

Databricks Apps の開発

まず、CLI の基本、認証、プロファイルの選択には親の databricks-core スキルを使用してください。

パッケージマネージャー — 以下のインストールやコマンドを実行する前に、必ずこれを特定してください。

Databricks Apps が公式にサポートしているのは npm と pnpm のみです。

  1. 次の優先順位でプロジェクトのパッケージマネージャーを特定します。プロジェクトの指示 → package.json の packageManager フィールド → ロックファイル(pnpm-lock.yaml → pnpm、package-lock.json → npm)。
  2. 手掛かりが矛盾する場合、またはサポート対象外のパッケージマネージャー(yarn、bun など)が検出された場合は、作業を中断し、使用するパッケージマネージャーをユーザーに確認してから進めてください。
  3. パッケージマネージャーが特定できない場合に限り、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 データベースが必要になる可能性があります。

  1. 足場を作成する前に、アプリに永続ストレージ(Lakebase)が必要かどうかをユーザーに確認してください。Lakebase を黙って追加してはいけません。
  2. 必要であることが確認できたら、Genie のフローと同様に、既存の Lakebase プロジェクトを再利用するか、新しく作成するかをユーザーに確認してください。決して黙って作成してはいけません。databricks-lakebase スキルを使用して、ブランチ名とデータベースのリソース名を取得します。
    • 再利用する場合: databricks postgres list-projects で一覧を取得してから、list-branches / list-databases を実行し、プロジェクト、ブランチ、データベースをユーザーに選んでもらいます。アプリが所有するスキーマも確認してください(新規または専用のスキーマにすると、サービスプリンシパルの所有権に関する競合を避けられます)。
    • 作成する場合: 新しいプロジェクトを作成します(production ブランチと databricks_postgres データベースが自動的にプロビジョニングされます)。
  3. --features lakebase を指定して足場を作成し、--set lakebase.postgres.branch=<BRANCH_NAME> --set lakebase.postgres.database=<DATABASE_NAME> を渡します。
  4. アプリが 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):

  1. config/queries/ に SQL ファイルを作成します
  2. <pm> run typegen を実行し、すべてのクエリに ✓ が表示されることを確認します
  3. client/src/appKitTypes.d.ts を読み、生成された型を確認します
  4. その後で、生成された型を使って App.tsx を記述します
  5. tests/smoke.spec.ts のセレクターを更新します
  6. databricks apps validate --profile <PROFILE> を実行します

typegen を実行する前に UI コードを書かないでください。 型が存在しないため、コンパイルエラーへの対応に時間を費やすことになります。

Lakebase アプリ(--features lakebase):SQL ファイルも typegen も不要です。onPluginsReady パターンについては Lakebase ガイド を参照してください。起動時にスキーマを初期化し、server/server.ts に Express ルートを登録してから、React フロントエンドを構築します。

用途に応じた選択

上記の判断ゲートを完了したら、次の振り分け表を使用してください。

  • 分析データを読み取る → グラフ/テーブルに表示する:queryKey prop を使用する可視化コンポーネントを使用します
  • 分析データを読み取る → カスタム表示する(KPI、カード):useAnalyticsQuery hook を使用します
  • 分析データを読み取る → 表示前に計算が必要:引き続き useAnalyticsQuery を使用し、クライアント側で変換します
  • ガバナンス管理された UC Metric View(セマンティックレイヤー)を読み取る:useMetricView hook と 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 コマンドを組み立てます。

  1. マニフェストを取得します(プラグインとそのリソースを記述した 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> で指定してください。
  2. スキャフォールド(Databricks CLI のみを使用):
    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>
    
    特定の AppKit バージョンを対象にするには、任意で --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 が含まれます。以下のように扱います:

  1. 収集 — 最終的な --features リストに含まれる各プラグインと、requiredByTemplate: true の各プラグインについて、plugins[].scaffolding.rules を読み取ります。それらにトップレベルのテンプレート scaffolding.rules を加えて、出所(テンプレートまたは<plugin>)をタグ付けした作業セットを1つ作成します。
  2. 優先順位 — マニフェストのルールは、このスキルに組み込まれた指示より優先されます。マニフェストに記述のない項目については、このスキルの内容を最低限の基準とします。
  3. フェーズの順序 — テキストが Before init で始まるルールは、databricks apps init の実行前に必ず実行します。After init で始まるルールは、初期化の完了後に必ず実行します(例:マイグレーション、型生成、接続チェック)。フェーズの接頭辞がないルールは、スキャフォールド/開発の全工程に適用されます。
  4. 競合の検出 — プラグインの must ルールが、同じ対象についてテンプレートの never ルールと矛盾する場合(またはその逆の場合)は、作業を停止し、先にどちらに従うかをユーザーに確認します。どちらかを黙って選んではいけません。同じ操作に対する must と never は競合として扱います。should は推奨事項であり、作業を妨げるものではありません。
  5. 報告 — databricks apps init の実行前に、統合した作業セットをフェーズ(Before init/After init/Always)ごと、重大度(must/should/never)ごとに分類してユーザーに提示し、有効なガードレールを明示します。

プロジェクト構造、ワークフロー、実装前チェックリストについては、AppKit Overview を読んでください。

Genie エージェントのワークフロー — ユーザーが Genie を利用するアプリを希望する場合、最初に Genie Space ID を尋ねてはいけません。代わりに、次の手順に従います。

  1. アプリでクエリする Unity Catalog のテーブルを尋ねます(完全修飾名:catalog.schema.table)。
  2. 既存の Genie space を再利用するか、新しく作成するかを尋ねます。
  3. 新規作成する場合:ウェアハウスを特定してから、databricks genie create-space で space を作成します(構文とシリアライズされた space の形式については、Genie Guide を参照してください)。
  4. 再利用する場合:databricks genie list-spaces --profile <PROFILE> で既存の space を特定し、ユーザーに選んでもらいます。
  5. 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 を使用してください。

コメント