Auto Loader で処理済みファイルをクリーンアップする

注記

cloudFiles.cleanSource は Databricks Runtime 16.4 以降で利用可能です。

cloudFiles.cleanSource を使用して、処理後のファイルをソースディレクトリから移動または削除します。処理済みのファイルを削除することで、ストレージコストが削減され、将来のリスト操作にかかる時間が短縮されます。

モード	説明
OFF （デフォルト）	ソースディレクトリ内のファイルは移動または削除されません。
MOVE	ソースディレクトリ内のファイルは、cloudFiles.cleanSource.retentionDuration で定義された保持期間 (default 30 日) が経過した後、cloudFiles.cleanSource.moveDestination で指定されたパスに移動されます。
DELETE	ソースディレクトリ内のファイルは、cloudFiles.cleanSource.retentionDuration で定義された保持期間（default 30日間）が経過した後に削除されます。

モード	説明
OFF （デフォルト）	ソースディレクトリ内のファイルは移動または削除されません。
MOVE	ソースディレクトリ内のファイルは、cloudFiles.cleanSource.retentionDuration で定義された保持期間 (default 30 日) が経過した後、cloudFiles.cleanSource.moveDestination で指定されたパスに移動されます。
DELETE	ソースディレクトリ内のファイルは、cloudFiles.cleanSource.retentionDuration で定義された保持期間（default 30日間）が経過した後に削除されます。

追加オプション	デフォルト	有効な値	説明
cloudFiles.cleanSource.retentionDuration	30 days	14 days、2 weeks、または CalendarInterval 文字列 1 month	処理済みのファイルがクリーンソースによるクリーンアップの対象となるまでに待機する時間。DELETE の場合は 7 日を超える必要があります。MOVE に最小値の制限はありません。
cloudFiles.cleanSource.waitForCompletion	false	true, false	このオプションは、Databricks Runtime 19以降で利用可能です。 クリーンソースは、デフォルトでベストエフォート型の操作です。クリーンソースによるファイルの移動または削除が完了する前にストリームがファイルの処理を完了した場合、クリーンソース操作は終了します。cloudFiles.cleanSource.waitForCompletion を設定すると、ソースのクリーンアップによるファイルの移動または削除が完了するまで、ストリームが強制的に維持されます。削除するファイルが多い場合、ストリームのランタイムが長くなる可能性があります。 これは、ストリームが単独で完了する場合（たとえば、すべてのファイルをドレインする availableNow Trigger など）にのみ適用されます。ストリームを手動で停止またはキャンセルすると、このオプションが設定されている場合でも、クリーンソース操作は直ちに終了します。
cloudFiles.cleanSource.moveDestination	なし	クラウドストレージまたは Unity Catalog ボリュームのパス	cloudFiles.cleanSource が MOVE に設定されている場合に、処理済みファイルをアーカイブするパス。これは、クラウドストレージパスまたは Unity Catalog ボリュームパス（例：/Volumes/my_catalog/my_schema/my_volume/archive/）にすることができます。 移動先は次の条件を満たす必要があります： ソースディレクトリの子ディレクトリではないこと。移動先をソースディレクトリ内に配置すると、アーカイブされたファイルが再度取り込まれます。 ソースと同じ外部ロケーション、ボリューム、または DBFS マウント内にあること。バケット間およびコンテナー間の移動はサポートされておらず、エラーになります。 Auto Loader には、このディレクトリに対する書き込み権限が必要です。

追加オプション	デフォルト	有効な値	説明
cloudFiles.cleanSource.retentionDuration	30 days	14 days、2 weeks、または CalendarInterval 文字列 1 month	処理済みのファイルがクリーンソースによるクリーンアップの対象となるまでに待機する時間。DELETE の場合は 7 日を超える必要があります。MOVE に最小値の制限はありません。
cloudFiles.cleanSource.waitForCompletion	false	true, false	このオプションは、Databricks Runtime 19以降で利用可能です。 クリーンソースは、デフォルトでベストエフォート型の操作です。クリーンソースによるファイルの移動または削除が完了する前にストリームがファイルの処理を完了した場合、クリーンソース操作は終了します。cloudFiles.cleanSource.waitForCompletion を設定すると、ソースのクリーンアップによるファイルの移動または削除が完了するまで、ストリームが強制的に維持されます。削除するファイルが多い場合、ストリームのランタイムが長くなる可能性があります。 これは、ストリームが単独で完了する場合（たとえば、すべてのファイルをドレインする availableNow Trigger など）にのみ適用されます。ストリームを手動で停止またはキャンセルすると、このオプションが設定されている場合でも、クリーンソース操作は直ちに終了します。
cloudFiles.cleanSource.moveDestination	なし	クラウドストレージまたは Unity Catalog ボリュームのパス	cloudFiles.cleanSource が MOVE に設定されている場合に、処理済みファイルをアーカイブするパス。これは、クラウドストレージパスまたは Unity Catalog ボリュームパス（例：/Volumes/my_catalog/my_schema/my_volume/archive/）にすることができます。 移動先は次の条件を満たす必要があります： ソースディレクトリの子ディレクトリではないこと。移動先をソースディレクトリ内に配置すると、アーカイブされたファイルが再度取り込まれます。 ソースと同じ外部ロケーション、ボリューム、または DBFS マウント内にあること。バケット間およびコンテナー間の移動はサポートされておらず、エラーになります。 Auto Loader には、このディレクトリに対する書き込み権限が必要です。

有効にする前の考慮事項 cloudFiles.cleanSource

• 複数のストリームが同じソースディレクトリからデータを消費する場合、Databricks ではこのオプションの使用を推奨していません。最も高速なストリームがファイルをクリーンアップするため、低速なストリームがそれらを取り込むことはありません。
• この機能を有効にするには、Auto Loaderがチェックポイントに追加の状態を保持する必要があります。これによりパフォーマンスのオーバーヘッドが発生しますが、cloud_files_stateテーブル値関数を通じて可観測性が向上します。「cloud_files_stateテーブル値関数」を参照してください。
• クリーンソースは現在の設定を使用して、特定のファイルを MOVE するか DELETE するかを決定します。たとえば、ファイルが最初に処理されたときの設定が MOVE であったが、30日後にクリーンアップの対象となったときに DELETE に変更されたとします。この場合、クリーンソースはファイルを削除します。
• cloudFiles.cleanSource.retentionDuration の有効期限が切れてすぐにファイルがクリーンアップされるとは限りません。コストを低く抑えるため、Auto Loaderはストリーム処理と並行してファイルをクリーンアップし、ストリーム処理が完了または終了するとすぐに終了します。クリーンアップの対象であったものの、ストリーム処理中にクリーンアップできなかったファイルは、次回のAuto Loaderの実行時に処理されます。

clean ソースに関する注意事項

• clean ソース は、処理対象のファイルのバッチがある場合にのみ実行されます。これは、取り込みとは独立して実行されるバックグラウンドプロセスではありません。ソースディレクトリに取り込む新しいファイルがない場合、現在のストリームランでは clean source は開始されません。その結果、ストリームが新しいファイルの受信を停止した場合、保持期間を過ぎたファイルは、後のストリームランで新しいバッチが処理されるまでクリーンアップされません。

  このバッチ要件は、cloudFiles.cleanSource.waitForCompletionに関係なく適用されます。そのオプションは、ラン内の進行中のクリーンアップを完了させるために必要な時間だけストリームを維持します。処理するバッチがない場合、クリーンなソースは起動しません。

• ファイルが N 回目のストリームランで取り込まれた場合、そのファイルの commit_time は N+1 回目のストリームランで設定されます。clean ソース がファイルが移動または削除の対象となるかどうかを判断するには commit_time を設定する必要があるため、ファイルがクリーンアップの候補となるのは最短で N+2 回目のストリーム ラン となります。

• commit_timeの設定は必要ですが、十分ではありません。ファイルは、commit_timeから測定された保持期間が経過した後にのみクリーンアップされます。たとえば、defaultのcloudFiles.cleanSource.retentionDurationが30日の場合、今日処理されたファイルは、そのcommit_timeが設定されてから30日が経過するまでクリーンアップの対象になりません。これは、その間にいくつのストリームランが発生したかに関係なく適用されます。ファイルが移動または削除される前に、両方の条件が満たされている必要があります。