Databricks Auto Loaderのファイル検出3モード比較: ディレクトリ一覧 / クラシック通知 / ファイルイベント

Posted at 2026-03-31

はじめに

Auto Loaderはクラウドオブジェクトストレージからの増分データ取り込みにおいて、Databricksで最も広く使われている機能の一つです。新しいファイルを検出する方式として、従来からディレクトリ一覧モードとファイル通知モード(クラシック) の2つが提供されてきました。

そして、Databricks Runtime 14.3 LTS以降で利用可能になったファイルイベントが、ファイル通知モードの新しいアプローチとして登場しました。Unity Catalogの外部ロケーションと統合されたこの機能により、Auto Loaderのファイル検出は大幅に簡素化・高性能化されています。

本記事では、3つのファイル検出モードを比較し、ファイルイベントの仕組みとメリットを整理した上で、実際に動かすためのサンプルコードを紹介します。

Auto Loaderの3つのファイル検出モード

Auto Loaderには以下の3つのファイル検出モードがあります。

1. ディレクトリ一覧モード

最もシンプルなモードです。入力ディレクトリを定期的にスキャンして新しいファイルを検出します。

設定: クラウドストレージへのアクセス権限のみで利用可能
メリット: 追加のインフラ設定が一切不要
デメリット: ファイル数が多いとAPI呼び出し回数が増大し、コストとレイテンシが増加
最適化: Databricks Runtime 9.1以降では、ファイルが字句順(lexical order)で到着しているかを自動検出し、API呼び出しを削減する最適化が入っています

# ディレクトリ一覧モード(デフォルト)
spark.readStream \
    .format("cloudFiles") \
    .option("cloudFiles.format", "json") \
    .option("cloudFiles.schemaLocation", checkpoint_path) \
    .load("s3://bucket/path/")

2. ファイル通知モード(クラシック)

クラウドプロバイダーのイベント通知サービスを活用するモードです。ストリームごとに個別のキュー/サブスクリプションを作成し、ファイル到着イベントを受信します。

設定: SNS/SQS(AWS)、Event Grid/Storage Queue(Azure)、Pub/Sub(GCP)のIAM権限が別途必要
メリット: イベント駆動のため、大量ファイルでも高速に検出
デメリット:
- クラウドプロバイダーの通知数上限: AWS/GCPで100/バケット、Azureで500/アカウント
- ストリームごとにキューが必要なため、リソースのライフサイクル管理が煩雑
- cloudFiles.fetchParallelismなどの手動チューニングが必要
- cloudFiles.backfillIntervalによるバックフィル設定を推奨(イベントの100%配信は保証されないため)

# クラシック通知モード
spark.readStream \
    .format("cloudFiles") \
    .option("cloudFiles.format", "json") \
    .option("cloudFiles.useNotifications", True) \
    .option("cloudFiles.region", "ap-northeast-1") \
    .option("cloudFiles.schemaLocation", checkpoint_path) \
    .load("s3://bucket/path/")

3. ファイルイベント(推奨)

Databricks Runtime 14.3 LTS以降で利用可能な、ファイル通知モードの新しいアプローチです。Unity Catalogの外部ロケーション単位でDatabricksマネージドサービスが通知リソースを管理します。

設定: Unity Catalogの外部ロケーションでファイルイベントを有効化するだけ
メリット:
- 追加のIAMポリシー作成が不要(UCの権限で完結)
- 外部ロケーションあたり1つのキューで運用するため、クラウドプロバイダーの通知数上限を回避
- Databricksがリソースのチューニングとライフサイクルを自動管理
- fetchParallelismやbackfillIntervalなどの手動パラメータ不要
- バックフィルも自動(7日以内に1回の実行を推奨)

# ファイルイベントモード(推奨)
spark.readStream \
    .format("cloudFiles") \
    .option("cloudFiles.format", "json") \
    .option("cloudFiles.useManagedFileEvents", True) \
    .option("cloudFiles.schemaLocation", checkpoint_path) \
    .load("s3://bucket/path/")

3モードの比較表

観点	ディレクトリ一覧	クラシック通知	ファイルイベント(推奨)
検出方式	定期スキャン	ストリームごとの個別キュー	マネージドキャッシュ
設定の容易さ	◎ 最も簡単	△ IAM権限設定が複雑	○ UC外部ロケーションの設定のみ
パフォーマンス	△ ファイル数依存	○ イベント駆動	◎ 最適化されたAPI
スケーラビリティ	△ スキャン依存	△ 通知数上限あり	◎ 上限回避の設計
リソース管理	不要	ユーザー管理	Databricks自動管理
バックフィル	毎回全スキャン	手動設定推奨	自動
必須ランタイム	全バージョン	全バージョン	DBR 14.3 LTS以降
Unity Catalog	不要	不要	必須
設定オプション	デフォルト	`useNotifications=true`	`useManagedFileEvents=true`

ファイルイベントのアーキテクチャ

ファイルイベントでは、Databricksのマネージドサービスが以下のように動作します。

外部ロケーションでファイルイベントを有効にすると、Databricksがクラウドストレージアカウントに通知リソース(SNS/SQS、Event Grid、Pub/Sub)を自動作成
ファイル到着イベントをマネージドサービスが受信・キャッシュ
Auto Loaderストリームは、最後に処理したファイルから再開する効率的なAPIでキャッシュから増分的にファイルを検出

従来のクラシック通知モードでは各ストリームが個別のキュー/サブスクリプションを持つ必要があったため、同じバケットに対する複数ストリームがあるとすぐにクラウドプロバイダーの通知数上限に達していました。ファイルイベントでは外部ロケーションあたり1つのキューを共有するアーキテクチャなので、この制限を大幅に緩和できます。

ベストプラクティス

Unity Catalogボリュームの活用

ファイルイベントを使用する際は、外部ロケーション上にAuto Loaderのユースケースごとに専用のUnity Catalogボリュームを作成し、クラウドストレージURLの代わりにボリュームパスを使用することが推奨されています。

# ボリュームパスを使用(推奨)
spark.readStream \
    .format("cloudFiles") \
    .option("cloudFiles.format", "json") \
    .option("cloudFiles.useManagedFileEvents", True) \
    .option("cloudFiles.schemaLocation", checkpoint_path) \
    .load("/Volumes/my_catalog/my_schema/my_volume/")

これにより、ファイルイベントサービスが関連オブジェクトのみにスコープを絞れるため、不要なファイル検出オーバーヘッドを回避でき、レートリミットの防止にもつながります。

サブパスごとにボリュームを分ける

同じ外部ロケーション配下の異なるサブパスから複数のAuto Loaderストリームが読み取る場合、1つのボリュームを共有するのではなく、サブパスごとに専用のボリュームを作成しましょう。

定期実行の確保

ファイルイベントサービスのキャッシュは最近作成されたファイルを保持していますが、Auto Loaderの実行頻度が低いとキャッシュが期限切れになり、ディレクトリ一覧へのフォールバックが発生します。少なくとも7日に1回はAuto Loaderを実行することが推奨されています。

移行ガイド

ディレクトリ一覧 → ファイルイベント

ストレージ資格情報と外部ロケーションをUnity Catalogで作成
外部ロケーションでファイルイベントを有効化
Auto LoaderストリームにcloudFiles.useManagedFileEvents = trueを追加

カタログエクスプローラで外部ロケーションを開き、拡張オプションの「ファイルイベントの有効化」をオンにします。

有効化後、「接続のテスト」でファイルイベントが正常に機能していることを確認できます。

ストリーム再起動間でモードを切り替えても、exactly-onceのデータ処理保証は維持されるため、安全に移行できます。

クラシック通知 → ファイルイベント

既存のクラシック通知ベースのストリームを停止
関連する通知リソース(SNS/SQS等)を削除
Unity Catalogの外部ロケーションでファイルイベントを有効化
cloudFiles.useNotificationsを削除し、cloudFiles.useManagedFileEvents = trueに変更
cloudFiles.fetchParallelism、cloudFiles.backfillInterval、resourceTags等の非サポートオプションを削除

Lakeflow Spark宣言的パイプラインでの利用

Lakeflow Spark宣言的パイプライン(旧DLT)でもファイルイベントを利用できます。

CREATE OR REFRESH STREAMING TABLE my_table
AS SELECT *
FROM STREAM read_files(
    's3://bucket/path/',
    format => 'json',
    useManagedFileEvents => 'true'
);

サポートされているクラウドストレージ

クラウドストレージ	ディレクトリ一覧	クラシック通知	ファイルイベント
AWS S3	全バージョン	全バージョン	DBR 14.3 LTS以降
ADLS	全バージョン	全バージョン	DBR 14.3 LTS以降
GCS	全バージョン	全バージョン	DBR 14.3 LTS以降
Azure Blob Storage	全バージョン	全バージョン	非サポート
Unity Catalog ボリューム	DBR 13.3 LTS以降	非サポート	DBR 14.3 LTS以降

まとめ

Auto Loaderのファイル検出モードは、ディレクトリ一覧 → クラシック通知 → ファイルイベントと進化してきました。ファイルイベントは、Unity Catalogとの統合によりセットアップの簡素化、パフォーマンスの向上、運用負荷の低減を同時に実現しています。

新規のAuto Loaderストリームではファイルイベントの利用を、既存のディレクトリ一覧やクラシック通知からの移行も積極的に検討することをお勧めします。