はじめに
この記事では、Claude Code for VS Code(VS Code拡張機能)を使ってDatabricks Appsを開発する方法を、環境構築からデプロイまで一気通貫で解説します。
前回の記事ではターミナルベースのCLI版を中心に解説しましたが、今回はVS Code拡張版をメインにリニューアルしました。変更のポイントは以下のとおりです。
| 項目 | 前回(CLI版) | 今回(VS Code拡張版) |
|---|---|---|
| メインツール | ターミナルでclaudeコマンド |
VS Codeのチャットパネル |
| 対象OS | macOS/Linux | Windows(macOS/Linuxも可) |
| コード変更の確認 | ターミナル上の差分表示でy/n | VS Codeのインライン差分ビューでAccept/Reject |
| gitの使用 |
git cloneでリポジトリ取得 |
git不要、フォルダ作成から開始 |
| デプロイ | bundle deploy |
databricks sync + databricks apps deploy
|
この記事で学べること:
- 環境セットアップ(Windows + VS Code拡張 + Databricks連携)
- Claude Code for VS Codeの基本操作とベストプラクティス
- CLAUDE.mdによるプロジェクト固有知識の管理
- app.yaml作成時の注意点
- ハンズオン: 基本操作の体験からUnity Catalogテーブルブラウザの開発・デプロイまで(60分)
対象読者:
- Databricks開発経験者
- AIコーディングツールに興味のあるエンジニア
- ターミナル操作よりGUIを好む開発者
開発フローの全体像
| ツール | 役割 |
|---|---|
| Claude Code for VS Code | VS Code内のチャットパネルから自然言語でコード生成・修正。app.py、app.yaml、requirements.txtなどを作成 |
| Databricks CLI | ファイル同期(sync)とデプロイ(apps deploy) |
| Databricks Apps | 生成したアプリをホスティング・公開 |
Claude Code for VS Codeは統合ターミナルからDatabricks CLIを直接実行できるため、コード生成からデプロイまでVS Codeの中で完結します。
環境セットアップ
前提条件
| 項目 | 要件 | 確認方法 |
|---|---|---|
| Windows | 10 / 11 | |
| VS Code | 最新版 | code --version |
| Git for Windows | Claude Codeの内部動作にbash環境が必要 | git --version |
| Python | 3.10以上 | python --version |
| Databricksワークスペース | アクセス権限があること |
Step 1: VS Codeのインストール
Visual Studio Code公式サイトからWindows用のインストーラーをダウンロードして実行します。インストール時のオプションはデフォルトのままでOKですが、「PATHへの追加」にチェックが入っていることだけ確認してください。
Step 2: Git for Windowsのインストール
これが最初のハマりポイントです。 Claude Codeは内部的にbashシェルでコマンドを実行する設計になっています。macOS/Linuxにはbashが標準搭載されていますが、Windowsにはないため、Git for Windowsに同梱されているGit Bashが必要です。Gitのバージョン管理機能が必要なわけではなく、bash環境の提供元としてGit for Windowsが前提になっています。
Git for Windowsからダウンロードしてインストールしてください。インストールオプションはデフォルトのままで問題ありません。
Git Bashがない状態でClaude Codeを起動すると以下のエラーが出ます。
Error: Claude Code on Windows requires git-bash (https://git-scm.com/downloads/win).
If installed but not in PATH, set environment variable pointing to your bash.exe,
similar to: CLAUDE_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe
既にインストール済みだがPATHに通っていない場合は、後述のVS Code設定でCLAUDE_CODE_GIT_BASH_PATHを指定することでも対応できます。
Step 3: Claude Code拡張機能のインストール
- VS Codeを開く
-
Ctrl+Shift+Xで拡張機能ビューを開く - 検索ボックスに「Claude Code」と入力
- 発行元が「Anthropic」 の公式拡張機能を選択してインストール
- インストール後にエディタ右上にSparkアイコン(✱)が表示されれば成功
表示されない場合はコマンドパレット(Ctrl+Shift+P)から「Developer: Reload Window」を実行してください。
CLIの別途インストールは不要です。 VS Code拡張機能にCLIが同梱されているため、チャットパネルから使う分にはこれだけでOKです。VS Code外のターミナルからもClaude Codeを使いたい場合のみ、別途CLIをインストールします。
Step 4: Databricks連携の設定
DatabricksのモデルサービングでClaude Codeを利用するための設定です。これにより、Anthropicアカウント不要でClaude Codeを利用できます。
パーソナルアクセストークン(PAT)を発行
- Databricksワークスペースにログイン
- サイドメニューのサービングにアクセス
- コーディングエージェント連携の始めましょう(Get Started) をクリック
- その他の統合(Other Integrations) タブ → Claude Codeを選択
-
デフォルトAnthropicモデル(Default Anthropic Model) で
databricks-claude-sonnet-4-5を選択 - APIキーを生成をクリックし、表示された設定情報をコピーして保管
APIキーは一度しか表示されません。必ずメモしてください。
VS Codeの設定を編集
ここが2つ目のハマりポイントです。 Databricksの画面に表示される設定は~/.claude/settings.jsonに書く形式、つまりCLI前提の書き方です。VS Code拡張機能を使う場合は設定場所が異なります。
| 使い方 | 設定場所 | 形式 |
|---|---|---|
| ターミナルからCLIで使う |
~/.claude/settings.json の env
|
{ "env": { "KEY": "VALUE" } } |
| VS Code拡張で使う | VS Codeの settings.json
|
claudeCode.environmentVariables |
Ctrl+Shift+P → 「Preferences: Open User Settings (JSON)」で設定ファイルを開き、以下を追加します。
{
"claudeCode.preferredLocation": "panel",
"claudeCode.environmentVariables": [
{ "name": "ANTHROPIC_BASE_URL", "value": "https://<ワークスペースURL>/serving-endpoints/anthropic" },
{ "name": "ANTHROPIC_AUTH_TOKEN", "value": "<パーソナルアクセストークン>" },
{ "name": "ANTHROPIC_CUSTOM_HEADERS", "value": "x-databricks-use-coding-agent-mode: true" },
{ "name": "ANTHROPIC_MODEL", "value": "databricks-claude-sonnet-4-5" },
{ "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "databricks-claude-sonnet-4-5" }
]
}
各環境変数の役割は以下のとおりです。
| 環境変数 | 役割 |
|---|---|
ANTHROPIC_BASE_URL |
Databricksのプロキシエンドポイント |
ANTHROPIC_AUTH_TOKEN |
DatabricksのPAT |
ANTHROPIC_CUSTOM_HEADERS |
コーディングエージェントモードの有効化 |
ANTHROPIC_MODEL |
メインで使用するモデル |
ANTHROPIC_DEFAULT_SONNET_MODEL |
Sonnetモデルのデフォルト指定(省略すると404エラー) |
ANTHROPIC_DEFAULT_SONNET_MODELが必要な理由
これが3つ目のハマりポイントです。 ANTHROPIC_DEFAULT_SONNET_MODELを省略すると、以下の404エラーが発生します。
API Error: 404 The given endpoint does not exist, please retry after
checking the specified model and version deployment exists.
ANTHROPIC_MODELにモデルを指定していても、Claude Codeは内部処理の一部でANTHROPIC_DEFAULT_SONNET_MODELを参照するパスがあります。この値が未指定だと、AnthropicのデフォルトモデルIDで呼び出すため、Databricksのエンドポイントには存在しないモデル名になり404になります。
厄介なのはcurlでエンドポイントを直接叩くと正常に応答が返ることです。エンドポイント自体は問題ないので、原因の特定に時間がかかります。Databricks経由で使う場合はANTHROPIC_DEFAULT_SONNET_MODELの指定が必須と覚えてください。
Git for WindowsがPATHに通っていない場合は、以下も追加してください。
{ "name": "CLAUDE_CODE_GIT_BASH_PATH", "value": "C:\\Program Files\\Git\\bin\\bash.exe" }
Windows環境でのセットアップ手順の詳細は「WindowsでClaude Code + Databricks連携を設定する際の落とし穴4つ」も参照してください。
Step 5: Databricks CLIのインストールと認証
PowerShellまたはコマンドプロンプトで以下を実行します。
# インストール
winget install Databricks.DatabricksCLI
# バージョン確認(0.250.0以上が必要)
databricks --version
# 認証(OAuth推奨)
databricks auth login --host https://<ワークスペースURL>
# 動作確認
databricks auth describe
databricks warehouses list
表示されたSQLウェアハウスのIDをメモしておいてください(ハンズオンで使います)。
Databricks CLIのインストール手順の詳細はこちらの記事を参照してください。
起動確認
VS Codeを再起動してから:
- エディタ右上のSparkアイコン(✱)をクリックしてチャットパネルを開く
- チャットパネルでメッセージを送信し、応答が返ることを確認
-
/modelと入力して接続先モデルがdatabricks-claude-sonnet-4-5であることを確認
Claude Code for VS Codeとは
CLI版との比較
Claude Code for VS Codeは、2026年1月にGA(一般提供)になった公式拡張機能です。CLI版と同じエンジンが動作しており、機能面の差はほとんどありません。
| 項目 | CLI版 | VS Code拡張版 |
|---|---|---|
| 動作環境 | ターミナル | VS Codeのチャットパネル |
| 起動方法 |
claudeコマンド |
Sparkアイコン(✱)クリック |
| ファイル変更の確認 | ターミナル上でy/n/e | インライン差分ビューでAccept/Reject |
| コンテキスト |
@ファイル名で手動追加 |
@ファイル名 + 開いているファイルを自動認識 |
| チェックポイント |
/rewindコマンド |
ホバーメニューからビジュアルに巻き戻し |
| プラグイン管理 | CLI |
/pluginsコマンドでGUI管理も可能 |
| セッション共有 | - | CLIと共有(claude --resumeで引き継ぎ可能) |
VS Code拡張版の最大の利点はインライン差分ビューです。CLIではターミナル上にテキストで差分が表示されy/nで判断しますが、VS Code拡張では緑色(追加)・赤色(削除)でハイライトされた差分を視覚的に確認してから承認できます。
基本操作
起動方法
以下のいずれかでチャットパネルを開きます。
- エディタ右上のSparkアイコン(✱) をクリック(ファイルを開いている時)
- 左サイドバーのClaude Codeアイコンをクリック(セッション一覧)
- コマンドパレット(
Ctrl+Shift+P)→「Claude Code: Open in New Tab」 - ステータスバー右下の「✱ Claude Code」をクリック
スラッシュコマンド
CLI版と同じスラッシュコマンドが使えます。
| コマンド | 説明 |
|---|---|
/model |
接続先モデルを確認・切り替え |
/context |
コンテキスト使用量を表示 |
/clear |
コンテキストをクリアして新規セッション開始 |
/compact |
会話履歴を要約して圧縮 |
/plugins |
プラグインの管理(VS Code拡張ではGUI表示) |
チェックポイントと巻き戻し
VS Code拡張版にはチェックポイント機能があります。Claude Codeがファイルを変更するたびに自動的にスナップショットが保存され、任意の時点に巻き戻せます。
メッセージにホバーすると巻き戻しボタンが表示され、以下の3つのオプションから選択できます。
- Fork conversation from here: この地点から会話を分岐(コード変更はそのまま)
- Rewind code to here: コードをこの地点に戻す(会話履歴は維持)
- Fork conversation and rewind code: 会話を分岐しつつコードも戻す
これはgit不要の「取り消し機能」として非常に便利です。思い切った変更を指示して、気に入らなければ巻き戻せばよいので、試行錯誤のハードルが下がります。
CLAUDE.mdの活用
なぜCLAUDE.mdが必要か
CLAUDE.mdは、Claude Codeがセッション開始時に自動的に読み込む特別なファイルです。「プロジェクトの取扱説明書」として機能します。
| 目的 | 説明 |
|---|---|
| 繰り返しの説明を避ける | 毎回「これはDatabricks Appsプロジェクトで...」と説明する必要がなくなる |
| 一貫した出力品質 | コーディング規約やフレームワーク選択が統一される |
| コンテキストの節約 | 会話中に長々と説明する代わりに、事前に定義しておける |
| チーム共有 | 全員が同じ前提知識でClaude Codeを使える |
CLAUDE.mdがないと、Claude Codeは毎回「白紙の状態」からプロジェクトを理解しようとします。Databricks Apps固有のルール(app.yamlの形式、Streamlitのポート設定、databricks-sdkの使い方など)が含まれていれば、最初から正確なコードが生成されます。
Databricks Apps向けの記載例
# プロジェクト概要
Databricks Apps上で動作するUnity Catalogテーブルブラウザ
# 技術スタック
- Python 3.11
- Streamlit
- Databricks SDK(WorkspaceClient)
- Unity Catalog
# Databricks Apps固有のルール
- app.yamlのcommandはリスト形式: ['streamlit', 'run', 'app.py']
- ポート/アドレスは指定しない(環境変数で自動設定される)
- envはname/valueペアのリスト形式
- SQL Warehouse IDはvalueFromで取得: valueFrom: sql-warehouse-id
- 認証はDatabricks SDKの自動認証を使用(WorkspaceClient())
# コーディング規約
- 型ヒントを使用
- Streamlitのキャッシュ(@st.cache_data)を活用
- エラーハンドリングはst.errorで表示
# よくあるエラーと対処法
- ModuleNotFoundError → requirements.txtに追加
- valueFrom解決エラー → UIでリソース設定が必要
メンテナンスのポイント
CLAUDE.mdはプロンプトの一部です。プロンプトエンジニアリングと同様に、反復的に改善します。
| チューニング手法 | 説明 |
|---|---|
| 強調の追加 | 重要な指示には「IMPORTANT」「YOU MUST」を付ける |
| 具体例の追加 | 抽象的な指示より具体的なコード例が効果的 |
| 不要な情報の削除 | 長すぎるCLAUDE.mdはノイズになる(目安: 200行以内) |
効果的なプロンプティング
Explore → Plan → Code ワークフロー
Anthropic公式のベストプラクティスに基づく推奨ワークフローです。
Step 1: Explore(探索)
@app.py を読んで、現在のアプリの構造を理解して。まだコードは書かないで。
Step 2: Plan(計画)
テーブルの行数とサイズ情報を表示する機能を追加したい。
どこをどう変更すればいいか、計画を立てて。コードはまだ書かないで。
Step 3: Code(実装)
計画に従って実装して。
ポイントは「まだコードは書かないで」と明示することです。いきなりコードを書かせると、全体像を把握しないまま局所的な変更をしてしまうことがあります。
具体的なプロンプトの重要性
曖昧な指示は曖昧な結果を生みます。
| 悪い例 | 良い例 |
|---|---|
| テストを追加して | app.pyのテストを追加して。Warehouse接続エラーのケースをカバー。モックは使わないで |
| エラーを直して | このエラーを見て。@app.py の42行目が原因だと思う。CLAUDE.mdのルールに従って修正して |
| UIを改善して | @app.py のサイドバーにテーブル検索機能を追加して。既存のst.selectboxパターンに合わせて |
app.yamlの正しい記述方法
app.yamlはDatabricks Appsの実行設定を定義する重要なファイルです。記述ミスはアプリの起動失敗に直結します。
基本構造
command:
- streamlit
- run
- app.py
env:
- name: DATABRICKS_WAREHOUSE_ID
valueFrom: sql-warehouse-id
よくある間違いと対策
commandの形式エラー
# 間違い: 文字列として記述
command: "streamlit run app.py"
# 正解: リスト形式で記述
command:
- streamlit
- run
- app.py
環境変数の形式エラー
# 間違い: 辞書形式
env:
DATABRICKS_WAREHOUSE_ID: "value"
# 正解: name/valueペアのリスト
env:
- name: DATABRICKS_WAREHOUSE_ID
value: "value"
ポート/アドレス指定
# 間違い: ポート/アドレスを指定
command:
- streamlit
- run
- app.py
- --server.port=8000
# 正解: ポート/アドレス指定なし(自動設定される)
command:
- streamlit
- run
- app.py
Databricks Apps環境ではSTREAMLIT_SERVER_PORTとSTREAMLIT_SERVER_ADDRESSが自動設定されます。app.yamlでのオーバーライドは禁止です。
認証のベストプラクティス
# 避けるべきパターン: ハードコードされた認証情報
token = "dapi_xxxxxxxxxxxxx"
# 推奨パターン: Databricks SDKの自動認証を使用
from databricks.sdk import WorkspaceClient
w = WorkspaceClient() # 環境から自動的に認証情報を取得
ハンズオン: Unity Catalogテーブルブラウザの開発
ここからは実際にClaude Code for VS Codeを使ってDatabricks Appsを開発し、デプロイまで行います。
作るもの: Unity Catalogテーブルブラウザ - カタログ/スキーマ/テーブルを階層的にブラウズし、データをプレビューできるStreamlitアプリです。
全体の流れ
| Phase | 時間目安 | 内容 |
|---|---|---|
| 1 | 5分 | フォルダ作成 → VS Codeで開く → Claude Code起動 |
| 2 | 10分 | 基本操作に慣れる(ファイル生成、差分Accept、@参照、巻き戻し) |
| 3 | 15分 | Claude Codeでアプリの雛形を生成 |
| 4 | 10分 | 対話的に機能を追加 |
| 5 | 15分 | Databricks Appsにデプロイ |
| 6 | 5分 | 動作確認 + 自由に拡張 |
| 合計 | 60分 |
Phase 1: 環境準備(5分)
作業フォルダの作成
PowerShellまたはコマンドプロンプトで以下を実行します。
mkdir %USERPROFILE%\uc-browser
cd %USERPROFILE%\uc-browser
code .
VS Codeが開いたら、事前に用意したCLAUDE.md(前述の「Databricks Apps向けの記載例」の内容)をこのフォルダに作成してください。VS CodeでCtrl+N → 内容を貼り付け → Ctrl+SでCLAUDE.mdとして保存します。
uc-browser\
└── CLAUDE.md
Claude Codeを起動する
VS Code内でClaude Codeを開きます。
- エディタ右上のSparkアイコン(✱)をクリック
- またはコマンドパレット(
Ctrl+Shift+P)→「Claude Code: Open in New Tab」
チャットパネルが表示されたら準備完了です。
CLAUDE.mdの読み込み確認
Claude Codeに以下のように入力してください。
CLAUDE.mdの内容を要約して
Databricks Appsの開発ルール(app.yaml構造、Streamlitの起動方法、databricks-sdkの使い方など)が表示されれば、正しく読み込まれています。
Phase 2: 基本操作に慣れる(10分)
いきなりアプリ開発に入る前に、Claude Code for VS Codeの基本的な操作を体験しておきます。ここで差分ビューの使い方やファイル参照の感覚をつかんでおくと、Phase 3以降がスムーズに進みます。
Step 2-1: ファイルを生成して差分ビューを体験する
Claude Codeに以下を入力してください。
hello.pyというファイルを作成して。"Hello, Databricks Apps!"と表示する簡単なPythonスクリプトにして。
VS Code上に差分ビューが表示されます。これがVS Code拡張の最大の特徴です。
- 左側(変更前): 空
- 右側(変更後): Claude Codeが生成したコード(緑色でハイライト)
- 上部にAcceptとRejectのボタン
内容を確認してAcceptをクリックしてください。VS Codeのエクスプローラーにhello.pyが追加されます。
Step 2-2: @参照でファイルの内容をClaude Codeに渡す
@hello.py この内容を説明して
@に続けてファイル名を入力すると、そのファイルの内容がClaude Codeのコンテキストに追加されます。Claude Codeがファイルの内容を読んで説明してくれるはずです。
Step 2-3: 既存ファイルを修正する体験
@hello.py を修正して、現在の日時も一緒に表示するようにして
今度は既存ファイルの変更の差分ビューが表示されます。赤色(削除される行)と緑色(追加される行)が並んで表示されるので、何がどう変わるかを確認してからAcceptしてください。
Step 2-4: コンテキスト使用量を確認する
/context
現在のセッションでどのくらいのコンテキスト(トークン)を使用しているかが表示されます。長い会話になるとコンテキストが圧迫されるので、定期的に確認する習慣をつけましょう。
Step 2-5: チェックポイントから巻き戻す
ここで巻き戻しを体験します。Step 2-1のメッセージ(hello.pyを最初に生成した時点)にマウスをホバーすると、巻き戻しボタンが表示されます。
「Rewind code to here」 を選択してください。
Step 2-3で追加した日時表示の修正が取り消され、hello.pyが最初の状態に戻ります。これがgitなしで使える「取り消し機能」です。間違った変更をしても安心して巻き戻せます。
Step 2-6: 練習用ファイルを削除する
本番のアプリ開発に入る前に、練習で作ったファイルを片付けます。
hello.pyを削除して
差分ビューでファイル削除を確認し、Acceptしてください。
ここまでで、差分ビューのAccept/Reject、@参照、/context、チェックポイント巻き戻しという基本操作を一通り体験しました。
Phase 3: アプリの雛形を生成する(15分)
Claude Codeにアプリ生成を指示する
以下のプロンプトをClaude Codeに入力してください。
Unity CatalogのカタログとスキーマとテーブルをブラウズできるStreamlitアプリを作ってください。
要件:
- Databricks Appsとしてデプロイする構成(app.yaml, requirements.txt, app.py)
- サイドバーでカタログ → スキーマ → テーブルを選択
- メインエリアに選択したテーブルの情報(カラム一覧)を表示
- databricks-sdkのWorkspaceClientを使う
- SQL Warehouse IDはapp.yamlの環境変数から取得
Claude Codeが応答を生成するのに1〜2分かかることがあります。Databricks経由の場合は特に待ち時間が長くなることがあるので、気長に待ってください。
生成されたファイルを確認する
Phase 2で練習した差分ビューが、今度は本番のコードで表示されます。3つのファイルそれぞれの差分を確認してAcceptしてください。
| ファイル | 役割 | 確認ポイント |
|---|---|---|
app.yaml |
Databricks Appsの設定ファイル | commandがリスト形式か、envにvalueFromがあるか |
requirements.txt |
Pythonの依存パッケージ |
streamlitとdatabricks-sdkが含まれているか |
app.py |
Streamlitアプリ本体 |
WorkspaceClient()を使っているか |
app.yamlを確認する
app.yamlの中身を確認してください。以下のような構造になっているはずです。
command:
- streamlit
- run
- app.py
env:
- name: DATABRICKS_WAREHOUSE_ID
valueFrom: sql-warehouse-id
valueFrom: sql-warehouse-idは、デプロイ時にDatabricks側で実際のWarehouse IDに解決されます(Phase 5で設定します)。
うまくいかない場合: この記事の末尾にある「付録: コピペ用ファイル」の内容でファイルを作成してください。
Phase 4: 機能を追加する(10分)
Phase 3で生成されたアプリは基本的なブラウズ機能のみです。ここからClaude Codeとの対話で機能を拡張していきます。
テーブルのデータプレビュー機能
テーブルを選択したときに、先頭100行のデータプレビューをDataFrameで表示する機能を追加して
Claude Codeがapp.pyの差分を提示します。Phase 2で練習した通り、VS Code上で変更内容を確認し、Acceptしてください。
さらに機能を追加してみる(任意)
時間に余裕がある方は、自由に追加の指示を出してみてください。例えば:
- 「テーブルの行数とサイズを表示して」
- 「カラム名で検索できるフィルタを追加して」
- 「選択したテーブルのCREATE TABLE文を表示して」
- 「テーブルのコメント(説明文)も表示して」
- 「ダークモードに対応して」
Claude Codeとの対話で、思いついた機能を自然言語で指示するだけでアプリが拡張されていく体験をしてください。
Tips: 効果的な指示の出し方
- 一度に複数の要件を詰め込まず、1つずつ指示する
- 期待と違う結果が出たら「やり直して」ではなく「○○の部分を△△に変えて」と具体的に指示する
- エラーが出たらエラーメッセージをそのままClaude Codeに貼ればOK
- 気に入らない変更はPhase 2で体験した通り、チェックポイントから巻き戻せる
Phase 5: Databricks Appsにデプロイする(15分)
デプロイ前にファイルを確認
VS Codeのエクスプローラー(左サイドバー)で以下のファイルが揃っていることを確認してください。
uc-browser\
├── CLAUDE.md
├── app.yaml
├── requirements.txt
└── app.py
アプリを作成する
VS Codeの統合ターミナル(Ctrl+`)を開き、以下を実行します。ターミナルの種類はPowerShellまたはCommand Promptどちらでも構いません。
VS Codeでuc-browserフォルダを開いていれば、統合ターミナルのカレントディレクトリは自動的にそのフォルダになります。別のターミナルを使う場合は先にcd %USERPROFILE%\uc-browserを実行してください。
databricks apps create uc-browser-<your-name>
<your-name>は自分の名前など一意な文字列に置き換えてください(例: uc-browser-taka)。
ソースコードをワークスペースに同期する
databricks sync . /Workspace/Users/<your-email>/apps/uc-browser-<your-name>
<your-email>はDatabricksのログインメールアドレスです。
databricks syncはローカルファイルをワークスペースに同期します。gitは不要です。.gitignoreがあれば除外対象を自動認識しますが、なくても問題ありません。
SQLウェアハウスリソースを追加する(重要)
app.yamlのvalueFrom: sql-warehouse-idを解決するために、UIでリソース設定が必要です。この手順を忘れるとアプリ起動時にエラーになります。
- Databricksワークスペースにログイン
- 左メニューから コンピュート → アプリ に移動
- 作成したアプリ(
uc-browser-<your-name>)をクリック -
編集 をクリック
- アプリのリソース セクションで SQLウェアハウス を追加
- 使用するSQLウェアハウスを選択
デプロイする
databricks apps deploy uc-browser-<your-name> --source-code-path /Workspace/Users/<your-email>/apps/uc-browser-<your-name>
デプロイには数分かかります。状態を確認するには:
databricks apps get uc-browser-<your-name>
statusがRUNNINGになれば成功です。デプロイ待ちの間に、ここまでの操作を振り返ったり、講師に質問したりしてください。
エラーが出ている場合はログを確認します。
databricks apps logs uc-browser-<your-name>
Phase 6: 動作確認(5分)
アプリにアクセスする
databricks apps getの出力に表示されるURLをブラウザで開きます。
Unity Catalogテーブルブラウザが表示され、カタログ → スキーマ → テーブルを選択してデータプレビューが見られれば完成です!
自由に拡張する(時間がある方)
アプリが動いている状態で、さらにClaude Codeで機能追加 → databricks sync → databricks apps deployのサイクルを回してみてください。
例: 「SQLクエリを直接入力して結果を表示する機能を追加して」
付録: コピペ用ファイル
CLAUDE.md
# Databricks Apps + Streamlit プロジェクト
## プロジェクト概要
Unity Catalogの`samples`カタログを可視化するStreamlitダッシュボードアプリケーション。
**対象カタログ**: `samples`(tpch, nyctaxi等)
**samplesカタログを使う理由**:
- 全ユーザーに読み取り権限があるため、デプロイ後もService Principal権限で問題なくアクセス可能
- 特別な権限設定が不要
## 技術スタック
- Python 3.11
- Streamlit
- Databricks SDK (databricks-sdk)
- Databricks SQL Connector (databricks-sql-connector)
**重要: Databricks AppsではSparkSessionは使用不可**
Databricks Appsはコンテナベースの軽量ランタイムで、Sparkドライバー/JVMが含まれていません。
```python
# ❌ 絶対にやってはいけない - JAVA_GATEWAY_EXITEDエラーになる
from pyspark.sql import SparkSession
spark = SparkSession.builder.appName("MyApp").getOrCreate()
# ✅ 代わりにDatabricks SQL Connectorを使用
from databricks import sql
from databricks.sdk.core import Config
```
データアクセスには必ずSQL Warehouse経由の`databricks-sql-connector`を使用してください。
## 開発コマンド
```bash
# ローカル実行(初回は--prepare-environmentで仮想環境を自動作成)
databricks apps run-local --prepare-environment
# 環境変数を追加してローカル実行(valueFromはローカルで解決できないため--envで渡す)
databricks apps run-local --prepare-environment --env DATABRICKS_WAREHOUSE_ID=xxx
# ログ確認
databricks apps logs <app-name>
```
**重要**:
- `--prepare-environment`を付けないと、streamlit等の依存関係がインストールされていない状態で実行され、`executable file not found`エラーになる
- app.yamlで`valueFrom`を使用している環境変数は、ローカル実行時に`--env`フラグで明示的に渡す必要がある
## デプロイ(Databricks Asset Bundles)
YAMLでリソースを定義し、CLIでデプロイする。
### databricks.yml
```yaml
bundle:
name: uc-browser
resources:
apps:
uc-browser:
name: uc-browser-<your-name>
source_code_path: .
resources:
- name: sql-warehouse
sql_warehouse:
id: ${var.warehouse_id}
permission: CAN_USE
variables:
warehouse_id:
description: SQL Warehouse ID
default: <your-warehouse-id>
targets:
dev:
default: true
```
### コマンド
```bash
databricks bundle deploy # デプロイ
databricks bundle run uc-browser # アプリ起動
databricks bundle destroy # 削除
```
**トラブル時**: ファイルがデプロイされない場合は`.gitignore`を確認(除外パターンに含まれている可能性)
## app.yaml のルール
### command は必ずリスト形式(ポート/アドレス指定禁止)
```yaml
# ✅ 正しい
command:
- streamlit
- run
- app.py
# ❌ 間違い: 文字列形式
command: "streamlit run app.py"
# ❌ 間違い: ポート/アドレス指定(Databricks Apps環境では自動設定される)
command:
- streamlit
- run
- app.py
- --server.port=8000 # 指定禁止
- --server.address=0.0.0.0 # 指定禁止
```
**重要**: Databricks Apps環境では以下の環境変数が自動設定され、**オーバーライド禁止**:
- `STREAMLIT_SERVER_PORT`: `DATABRICKS_APP_PORT`に設定
- `STREAMLIT_SERVER_ADDRESS`: `0.0.0.0`に設定
ローカル実行時は`databricks apps run-local`がポート8000で自動起動するため、app.yamlでのポート指定は不要。
### env は name/value ペアのリスト
```yaml
# ✅ 正しい
env:
- name: DATABRICKS_WAREHOUSE_ID
valueFrom: sql-warehouse
- name: LOG_LEVEL
value: INFO
# ❌ 間違い
env:
DATABRICKS_WAREHOUSE_ID: "xxx"
```
### valueFrom vs value の使い分け
| パターン | 用途 |
|----------|------|
| `valueFrom: sql-warehouse` | SQL Warehouse ID |
| `valueFrom: serving-endpoint-name` | Model Serving エンドポイント名 |
| `value: "固定値"` | 固定の設定値 |
**重要**: `valueFrom`を使用するには、Databricks Apps UIでリソースを設定する必要があります。
Compute > Apps > アプリ名 > Settings > Resources で SQL Warehouse等を追加してください。
リソース設定なしでは`valueFrom`が解決されず、アプリが動作しません。
## セキュリティ要件
### SQLクエリは必ずパラメータ化
```python
# ✅ 正しい
cursor.execute(
"SELECT * FROM catalog.schema.table WHERE id = :id",
{"id": user_input}
)
# ❌ 間違い（SQLインジェクションの危険）
cursor.execute(f"SELECT * FROM table WHERE id = {user_input}")
```
### 認証情報をハードコードしない
```python
# ✅ 正しい - SDKの自動認証を使用
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
# ❌ 間違い
token = "dapi_xxxxxxxxxxxxx"
```
### databricks-sql-connectorの認証(重要)
**Databricks Apps環境での正しいパターン**:
```python
from databricks import sql
from databricks.sdk.core import Config
import os
@st.cache_resource
def get_sql_connection():
cfg = Config() # WorkspaceClientではなくConfigを使う
return sql.connect(
server_hostname=cfg.host,
http_path=f"/sql/1.0/warehouses/{os.getenv('DATABRICKS_WAREHOUSE_ID')}",
credentials_provider=lambda: cfg.authenticate, # lambdaでラップ必須
)
```
**よくある間違い**:
```python
# ❌ 間違い1: WorkspaceClient.config.authenticateを直接渡す
w = WorkspaceClient()
conn = sql.connect(
server_hostname=w.config.host,
credentials_provider=w.config.authenticate, # エラー: 'dict' object is not callable
)
# ❌ 間違い2: lambdaなしで渡す
cfg = Config()
conn = sql.connect(
credentials_provider=cfg.authenticate, # エラー: 'NoneType' object is not callable
)
# ✅ 正しい: Configを使い、lambdaでラップする
cfg = Config()
conn = sql.connect(
server_hostname=cfg.host,
http_path=f"/sql/1.0/warehouses/{os.getenv('DATABRICKS_WAREHOUSE_ID')}",
credentials_provider=lambda: cfg.authenticate,
)
```
**ポイント**:
- `WorkspaceClient`ではなく`databricks.sdk.core.Config`を使用
- `credentials_provider`には`lambda: cfg.authenticate`の形式で渡す(lambdaでラップ必須)
- `cfg.authenticate`は呼び出し時にヘッダー辞書を返すメソッド
## Unity Catalogアクセスパターン
### カタログ/スキーマ/テーブル一覧の取得
Unity Catalogのメタデータ取得には`WorkspaceClient`を使用します。
```python
from databricks.sdk import WorkspaceClient
import streamlit as st
@st.cache_resource
def get_workspace_client():
return WorkspaceClient()
def get_catalogs():
w = get_workspace_client()
return [c.name for c in w.catalogs.list()]
def get_schemas(catalog_name):
w = get_workspace_client()
return [s.name for s in w.schemas.list(catalog_name=catalog_name)]
def get_tables(catalog_name, schema_name):
w = get_workspace_client()
return [t.name for t in w.tables.list(catalog_name=catalog_name, schema_name=schema_name)]
```
### テーブルデータの取得
テーブルのデータ取得には`databricks-sql-connector`を使用します。
```python
from databricks import sql
from databricks.sdk.core import Config
import os
import streamlit as st
@st.cache_resource
def get_sql_connection():
cfg = Config()
return sql.connect(
server_hostname=cfg.host,
http_path=f"/sql/1.0/warehouses/{os.getenv('DATABRICKS_WAREHOUSE_ID')}",
credentials_provider=lambda: cfg.authenticate,
)
def get_table_data(catalog, schema, table, limit=100):
conn = get_sql_connection()
with conn.cursor() as cursor:
# パラメータ化クエリは識別子には使えないため、許可リストで検証
query = f"SELECT * FROM `{catalog}`.`{schema}`.`{table}` LIMIT {limit}"
cursor.execute(query)
return cursor.fetchall_arrow().to_pandas()
```
**注意**: テーブル名などの識別子はSQLパラメータ化できないため、ユーザー入力をそのまま使う場合は許可リストで検証するか、選択式UIを使用してください。
## Streamlit のベストプラクティス
### st.set_page_config() は最初に呼び出す
```python
import streamlit as st
# 必ず最初に呼び出す
st.set_page_config(
page_title="UC Browser",
page_icon="📊",
layout="wide"
)
# 他のインポートやコードはこの後
```
### 接続はキャッシュする
```python
from databricks.sdk import WorkspaceClient
from databricks.sdk.core import Config
from databricks import sql
import os
@st.cache_resource
def get_workspace_client():
return WorkspaceClient()
@st.cache_resource
def get_sql_connection():
cfg = Config()
return sql.connect(
server_hostname=cfg.host,
http_path=f"/sql/1.0/warehouses/{os.getenv('DATABRICKS_WAREHOUSE_ID')}",
credentials_provider=lambda: cfg.authenticate,
)
```
## requirements.txt のルール
バージョンを必ず固定する:
```txt
streamlit==1.45.0
databricks-sdk==0.55.0
databricks-sql-connector==4.0.0
pandas==2.2.3
numpy>=1.26.0,<2.0.0
```
## ディレクトリ構造
```
project/
├── databricks.yml # Bundle設定
├── app.yaml # アプリ起動設定
├── app.py # メインアプリ
└── requirements.txt # 依存関係
```
## よくあるエラーと対処法
| エラー | 原因 | 対処法 |
|-------|------|--------|
| `JAVA_GATEWAY_EXITED` | SparkSessionを使用しようとした | Databricks AppsではSparkは使用不可。SQL Connectorを使用 |
| `streamlit: executable file not found` | 依存関係未インストール | `--prepare-environment`を付けて実行 |
| `valueFrom property and can't be resolved locally` | valueFromはローカルで解決不可 | `--env VAR_NAME=value`で環境変数を渡す |
| `'dict' object is not callable` | SQL Connectorの認証設定ミス | `credentials_provider=lambda: cfg.authenticate`の形式で渡す |
| `'NoneType' object is not callable` | SQL Connectorの認証設定ミス | `Config()`を使い、lambdaでラップする |
| `YAML parse error` | app.yamlの構文エラー | command/envの形式を確認 |
| `ModuleNotFoundError` | 依存関係不足 | requirements.txtを確認 |
| `Connection refused` (ローカル) | アプリが起動していない | `databricks apps run-local`を実行 |
| `401 Unauthorized` | 認証エラー | SDK自動認証の設定を確認 |
| `App deployment failed` (ファイル関連) | 10MB超のファイルがある | 大きなファイルを除外、.gitignoreを確認 |
| アプリが起動しない(デプロイ後) | app.yamlでポート/アドレス指定 | `--server.port`と`--server.address`を削除 |
| Bundleでファイルがデプロイされない | `.gitignore`に含まれている | `.gitignore`を確認 |
## Databricks Apps の制限事項
| 制限 | 詳細 |
|------|------|
| **SparkSession使用不可** | コンテナにSparkランタイムなし。SQL Connector必須 |
| **ファイルサイズ** | 1ファイルあたり10MB以下 |
| **認証** | Databricksユーザー認証必須(匿名アクセス不可) |
| **ポート/アドレス指定禁止** | `STREAMLIT_SERVER_PORT`と`STREAMLIT_SERVER_ADDRESS`は自動設定。app.yamlでオーバーライド禁止 |
| **接続タイムアウト** | SQL Warehouseがアイドル停止すると接続が切れる可能性あり |
Phase 3でClaude Codeの生成がうまくいかない場合は、以下の内容でファイルを作成してください。VS CodeでCtrl+N → 内容を貼り付け → Ctrl+Sでファイル名を指定して保存します。
app.yaml
command:
- streamlit
- run
- app.py
- --server.port
- "8000"
- --server.address
- "0.0.0.0"
env:
- name: DATABRICKS_WAREHOUSE_ID
valueFrom: sql-warehouse-id
requirements.txt
streamlit
databricks-sdk
pandas
app.py
import os
import streamlit as st
from databricks.sdk import WorkspaceClient
st.set_page_config(page_title="UC Table Browser", layout="wide")
st.title("Unity Catalog テーブルブラウザ")
w = WorkspaceClient()
warehouse_id = os.environ.get("DATABRICKS_WAREHOUSE_ID", "")
@st.cache_data(ttl=300)
def list_catalogs():
return [c.name for c in w.catalogs.list()]
@st.cache_data(ttl=300)
def list_schemas(catalog):
return [s.name for s in w.schemas.list(catalog_name=catalog)]
@st.cache_data(ttl=300)
def list_tables(catalog, schema):
return [t.name for t in w.tables.list(catalog_name=catalog, schema_name=schema)]
@st.cache_data(ttl=300)
def get_table_info(catalog, schema, table):
full_name = f"{catalog}.{schema}.{table}"
return w.tables.get(full_name=full_name)
def execute_query(query):
from databricks.sdk.service.sql import StatementState
response = w.statement_execution.execute_statement(
warehouse_id=warehouse_id,
statement=query,
wait_timeout="30s",
)
if response.status.state != StatementState.SUCCEEDED:
st.error(f"クエリ失敗: {response.status.error}")
return None
columns = [col.name for col in response.manifest.schema.columns]
rows = []
if response.result and response.result.data_array:
rows = response.result.data_array
import pandas as pd
return pd.DataFrame(rows, columns=columns)
# サイドバー: カタログ → スキーマ → テーブル選択
with st.sidebar:
st.header("ナビゲーション")
catalogs = list_catalogs()
selected_catalog = st.selectbox("カタログ", catalogs)
if selected_catalog:
schemas = list_schemas(selected_catalog)
selected_schema = st.selectbox("スキーマ", schemas)
else:
selected_schema = None
if selected_catalog and selected_schema:
tables = list_tables(selected_catalog, selected_schema)
selected_table = st.selectbox("テーブル", tables)
else:
selected_table = None
# メインエリア
if selected_catalog and selected_schema and selected_table:
full_name = f"{selected_catalog}.{selected_schema}.{selected_table}"
st.subheader(f"📋 {full_name}")
table_info = get_table_info(selected_catalog, selected_schema, selected_table)
# テーブル情報
if table_info.comment:
st.info(table_info.comment)
# カラム一覧
st.markdown("### カラム一覧")
if table_info.columns:
import pandas as pd
col_data = [
{
"カラム名": c.name,
"データ型": c.type_text,
"コメント": c.comment or "",
}
for c in table_info.columns
]
st.dataframe(pd.DataFrame(col_data), use_container_width=True, hide_index=True)
# データプレビュー
st.markdown("### データプレビュー(先頭100行)")
if warehouse_id:
df = execute_query(f"SELECT * FROM {full_name} LIMIT 100")
if df is not None:
st.dataframe(df, use_container_width=True, hide_index=True)
else:
st.warning("SQL Warehouse IDが設定されていません。")
else:
st.info("👈 サイドバーからカタログ、スキーマ、テーブルを選択してください。")
付録: トラブルシューティング
Claude Codeが起動しない / bash関連のエラー
Git for Windowsがインストールされているか確認してください。インストール済みだがPATHに通っていない場合は、VS Codeのsettings.jsonに以下を追加します。
{ "name": "CLAUDE_CODE_GIT_BASH_PATH", "value": "C:\\Program Files\\Git\\bin\\bash.exe" }
設定変更後はVS Codeを再起動してください。
404エラー(API Error: 404 The given endpoint does not exist)
Databricks経由でClaude Codeを使う場合、ANTHROPIC_DEFAULT_SONNET_MODELの指定漏れが最も多い原因です。VS Codeのsettings.jsonのclaudeCode.environmentVariablesに以下が含まれているか確認してください。
{ "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "databricks-claude-sonnet-4-5" }
curlでエンドポイントの疎通確認をする場合:
curl -X POST "https://<ワークスペースURL>/serving-endpoints/anthropic/v1/messages" ^
-H "Authorization: Bearer <パーソナルアクセストークン>" ^
-H "Content-Type: application/json" ^
-d "{\"model\":\"databricks-claude-sonnet-4-5\",\"max_tokens\":100,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"
これで応答が返るならエンドポイント自体は正常です。Claude Code側の設定を見直してください。
Databricks CLIの認証エラー
# トークンの有効期限切れの場合
databricks auth login --host https://<ワークスペースURL>
# 認証状態の確認
databricks auth describe
デプロイ後にアプリがエラーになる
よくある原因:
- SQLウェアハウスリソース未設定: Phase 5のリソース追加手順を確認してください
-
requirements.txtの不足:
databricks-sdkとstreamlitが含まれているか確認 - Pythonバージョン不一致: Databricks Appsは3.10以上が必要です
syncコマンドでエラーが出る
# パスが正しいか確認
databricks workspace ls /Workspace/Users/<your-email>/
# 手動でディレクトリを作成してからsync
databricks workspace mkdirs /Workspace/Users/<your-email>/apps/uc-browser-<your-name>
databricks sync . /Workspace/Users/<your-email>/apps/uc-browser-<your-name>
まとめ
Claude Code for VS CodeとDatabricks Appsの組み合わせにより、以下のことが実現できます。
- VS Codeの中で完結する開発体験: チャットパネルでコード生成 → インライン差分で確認 → 統合ターミナルでデプロイ
- CLAUDE.mdによる知識の蓄積: Databricks Apps固有のルールを定義しておくことで、一貫した品質のコード生成が可能
-
git不要の手軽なデプロイ:
databricks syncでローカルファイルを直接ワークスペースに同期
前回のCLI版と比較して、VS Code拡張版はインライン差分やチェックポイント(巻き戻し)などビジュアルな操作が充実しており、ターミナル操作に慣れていない方でもとっつきやすい構成になっています。
参考リンク
- 前回のワークショップ記事(CLI版)
- WindowsでClaude Code + Databricks連携の落とし穴4つ
- Claude Code公式ドキュメント: VS Code
- Claude Code公式ドキュメント: セットアップ
- Claude Codeベストプラクティス
- Databricks Apps公式ドキュメント
- Databricks CLI公式ドキュメント
- Databricks: コーディングエージェントの統合