Databricks Workspace Filesで実現するコード配置と依存ファイル管理

Databricksではノートブック以外にもPythonモジュール、SQLファイル、設定ファイル、requirements.txtなどを ワークスペース内に配置する必要があります。Workspace Filesは、 ノートブックと同じファイルツリー上にあらゆるファイルタイプを配置し、 相対インポートや依存管理を実現する機能です。

この記事では、Workspace Filesの概要、Reposとの比較、相対インポートの方法、 requirements.txtによるパッケージ管理、そして実務でよく使われる依存管理パターンを解説します。

Workspace Filesとは

Workspace Filesは、Databricksワークスペースの/Workspace/配下に配置される 非ノートブックファイルの総称です。2023年以降のDatabricksでは、ワークスペースのファイルブラウザから Pythonファイル（.py）、テキストファイル（.txt/.csv/.json）、YAML、設定ファイルなどを 直接アップロード・作成・編集できます。

Workspace Filesが導入される以前は、ノートブック以外のファイルをDatabricks上で管理するには DBFSにアップロードするか、%runマジックコマンドで他のノートブックを呼び出す必要がありました。 Workspace Filesにより、通常のPythonプロジェクトと同じディレクトリ構造・インポート方式が使えるようになっています。

Repos vs Workspace Files

チーム開発のコード本体はReposで管理し、個人の実験スクリプトや一時的な設定ファイルは Workspace Filesに配置する使い分けが一般的です。

相対インポートの仕組み

Workspace Files（Repos含む）では、ノートブックと同じディレクトリに配置したPythonファイルを 通常のimport文で読み込めます。これはノートブック実行時にカレントディレクトリがsys.pathに自動追加されるためです。

ディレクトリ構造の例

/Workspace/Users/[email protected]/my-project/
├── main_notebook.py        # メインのノートブック
├── utils.py                # ユーティリティ関数
├── config.yaml             # 設定ファイル
├── requirements.txt        # 依存パッケージ定義
└── transformations/
    ├── __init__.py          # パッケージ化に必要
    ├── clean.py             # データクレンジング関数
    └── aggregate.py         # 集約処理関数

ノートブックからのインポート

# main_notebook.py

# 同じディレクトリのモジュールをインポート
from utils import validate_schema, log_metrics

# サブディレクトリのパッケージをインポート
from transformations.clean import remove_duplicates
from transformations.aggregate import daily_summary

# 設定ファイルの読み込み
import yaml
with open("config.yaml", "r") as f:
    config = yaml.safe_load(f)

# 処理の実行
df = spark.read.format("delta").load(config["input_path"])
df_clean = remove_duplicates(df)
df_summary = daily_summary(df_clean)
df_summary.write.format("delta").mode("overwrite").save(config["output_path"])

__init__.pyがサブディレクトリに配置されていることが重要です。 これがないとPythonがそのディレクトリをパッケージとして認識せず、from transformations.clean import ...が失敗します。

requirements.txtによるパッケージ管理

Workspace Files内にrequirements.txtを配置し、ノートブック内から%pipでインストールする方式は 依存パッケージ管理のシンプルなパターンです。

# requirements.txt
pandas==2.2.0
requests==2.31.0
pyyaml==6.0.1
great-expectations==0.18.0

# ノートブックの先頭セルで実行
%pip install -r ./requirements.txt

%pipはノートブックスコープのパッケージインストールを行い、 クラスタ全体の環境には影響しません。ただし%pipセルを実行するとPythonプロセスが 再起動されるため、必ずノートブックの先頭で実行する必要があります。

依存管理パターンの比較

Workspace Files APIによる管理

Workspace Filesはブラウザからのアップロードだけでなく、REST APIやDatabricks CLIで管理できます。 CI/CDパイプラインでの自動配置に便利です。

# Databricks CLIでファイルをアップロード
databricks workspace import \
  --path /Workspace/Shared/etl-project/utils.py \
  --file ./src/utils.py \
  --format SOURCE \
  --language PYTHON

# REST APIでファイル一覧を取得
curl -X GET \
  "https://<workspace-url>/api/2.0/workspace/list" \
  -H "Authorization: Bearer <token>" \
  -d '{"path": "/Workspace/Shared/etl-project"}'

# REST APIでファイルをエクスポート
curl -X GET \
  "https://<workspace-url>/api/2.0/workspace/export" \
  -H "Authorization: Bearer <token>" \
  -d '{"path": "/Workspace/Shared/etl-project/utils.py", "format": "SOURCE"}'

ベストプラクティス

• プロジェクト単位でディレクトリを構成する: ノートブック・モジュール・設定ファイルを 1つのディレクトリにまとめて、相対パスで自然に参照できる構造にする
• 共有ファイルは/Workspace/Shared/に配置: チーム共通のユーティリティモジュールは 個人フォルダではなく共有フォルダに配置してアクセス制御を明示的にする
• 大きなデータファイルはWorkspace Filesに置かない: CSVやParquetなどのデータファイルは クラウドストレージ（S3/ADLS/GCS）またはUnity Catalog Volumesに配置する
• 本格的なバージョン管理にはReposを使う: Workspace Filesにはバージョン管理がないため、 チーム開発のコード本体はReposで管理し、Workspace Filesは補助用途に限定する

試験で問われるポイント

• 「ノートブックから外部のPythonモジュールをインポートするには」→ Workspace Files / Repos内に.pyファイルを配置してimport
• 「依存パッケージをノートブック単位で管理するには」→ %pip install -r requirements.txt
• 「Workspace FilesとDBFSの違いは」→ Workspace Filesは/Workspace/配下でコード用、DBFSは/dbfs/配下でデータ用
• 「サブディレクトリのモジュールをインポートするには」→ __init__.pyを配置してパッケージ化

問題で確認

よくある質問