セットアップ
前提条件
| ツール | バージョン |
|---|---|
| Node.js | v18 以上 |
| npm | Node.js 同梱のもの |
| Python | v3.9 以上 |
| pip | Python 同梱のもの |
| Databricks サービスプリンシパル | DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET を発行済みであること |
手順
作業ディレクトリに注意
以下のコマンドはすべて nodejs-fastapi-hello-world-app/ で実行する（リポジトリのルートではない）。ディレクトリ名は Databricks のテンプレート由来で、アプリの内容とは無関係。
1. リポジトリのクローン
git clone https://github.com/fourdigit/databricks-apps-survey-analysis.git
cd databricks-apps-survey-analysis/nodejs-fastapi-hello-world-app
2. 依存関係のインストール
Python は仮想環境の利用を推奨する。
python -m venv venv
source venv/bin/activate # Windows は venv\Scripts\activate
pip install -r requirements.txt
databricks-sdk は requirements.txt に含まれていない
テーブル一覧の取得（GET /api/catalogs/{catalog}/schemas/{schema}/tables）は databricks-sdk の WorkspaceClient を使う。未インストールでもアプリは起動するが、該当 API を呼んだ時点で 503 になる。必要なら pip install databricks-sdk を別途実行する。
3. 環境変数の設定
DATABRICKS_HOST と DATABRICKS_HTTP_PATH は databricks.yml / app.yaml から自動的に補われるため、.env には認証情報だけを書く。
.env の各項目を設定する。
| 変数名 | 説明 | 例 |
|---|---|---|
DATABRICKS_CLIENT_ID |
サービスプリンシパルのクライアント ID | xxxxxxxx-xxxx-... |
DATABRICKS_CLIENT_SECRET |
サービスプリンシパルのシークレット | dose... |
DATABRICKS_HOST |
ワークスペースのホスト名。省略時は databricks.yml の default target から補完 |
dbc-46ba3922-f68b.cloud.databricks.com |
DATABRICKS_HTTP_PATH |
SQL Warehouse の HTTP パス。省略時は app.yaml の env から補完 |
/sql/1.0/warehouses/e25d3da675c1b27b |
APP_MODE |
local のとき yaml からの補完を有効にする（デフォルト local） |
local |
読み込みの優先順位は .env > databricks.yml / app.yaml > システム環境変数（すでに設定済みの環境変数は上書きしない）。
.env はコミットしないこと。
4. 起動
フロントエンドとバックエンドを別々のターミナルで起動する。
# ターミナル 1: Vite dev server
npm run dev
# ターミナル 2: FastAPI
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
http://localhost:5173 にアクセスして確認する。API のドキュメントは http://localhost:8000/api/docs（Swagger UI）。
Vite dev server は /api を localhost:8000 にプロキシする。バックエンドのポートを変える場合は frontend/vite.config.ts の server.proxy も合わせて変更する。
よくあるエラー
RuntimeError: databricks-sql-connector is not installed
原因: Python の依存がインストールされていない。SQL 層は import 失敗を握りつぶして遅延エラーにしているため、アプリ自体は起動してしまう。
解決策:
503 Service Unavailable（Databricks credential configuration is incomplete）
原因: DATABRICKS_HOST / DATABRICKS_HTTP_PATH / DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET のいずれかが未設定。
解決策:
# 読み込まれている値を確認する
python -c "from backend import settings; print(settings.DATABRICKS_HOST, settings.DATABRICKS_HTTP_PATH)"
不足している値を .env に追記する。SQL Warehouse が起動しているかも確認する。
400 Bad Request（Invalid identifier）
原因: catalog / schema / table 名が ^[A-Za-z0-9_]+$ に一致しない。SQL インジェクション対策の allowlist（backend/sql/utils.py）で弾かれている。
解決策: 識別子を確認する。記号やスペースを含む識別子は現状サポートしていない。
404 Not Found（Frontend not built. Please run 'npm run build' first.）
原因: backend/static/index.html がない。バックエンド単体で SPA を配信しようとした。
解決策:
Port 8000 is already in use
原因: 既に別プロセスがポートを使用している。
解決策: