FILE タイプと非構造化データ

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。Databricksのプレビューを管理するを参照してください。

FILE タイプは、パスやサイズなどのメタデータと共に、非構造化ファイルへのガバナンスされた参照を保存します。Unity Catalog で FILE 列を使用して、構造化データと並んでドキュメント、イメージ、およびオーディオを保存します。

タイプのリファレンスについては、FILEタイプを参照してください。

次の図は、ルート、シーンの説明、危険ラベルなどの構造化列と並んで、運転クリップを参照する video という名前の FILE 列を示しています：

ファイルメタデータとストレージ

各行について、FILEタイプはメタデータとストレージ内のファイルへの管理されたLinkを格納します。FILE値には、uri、size、content_type、およびchecksumのメタデータフィールドが含まれます。メタデータクエリーはファイル全体を読み取る必要がないため、クエリーのパフォーマンスが向上します。

FILE値を、ai_parse_document 関数 のような AI 関数 や、ユーザー定義関数（UDF） に渡すことができます。

次の図は、パスとサイズのメタデータ、およびストレージ内のファイルへの参照を含む、マネージド FILE カラムの例を示しています。

BINARY や STRING ではなく FILE を使用する理由

以下の表は、BINARY または STRING 型の大きな非構造化ファイルを扱う際の課題を詳述しています。

列タイプ	説明	図
BINARY	ファイルサイズやパスなどのメタデータのみが必要な場合でも、読み取りのたびにオブジェクト全体をマテリアライズします。これにより、不要な計算が発生し、クエリーが低速化します。
STRING	サイズやバージョン情報などのメタデータを含まないファイルパスを格納し、テーブルとファイル間にガバナンスされたLinkを持たせません。別のワークロードがファイルを削除した場合、テーブルには古い情報が残ります。テーブルの行を削除しても、参照されているファイルは手動で削除するまでストレージに残ります。

列タイプ	説明	図
BINARY	ファイルサイズやパスなどのメタデータのみが必要な場合でも、読み取りのたびにオブジェクト全体をマテリアライズします。これにより、不要な計算が発生し、クエリーが低速化します。
STRING	サイズやバージョン情報などのメタデータを含まないファイルパスを格納し、テーブルとファイル間にガバナンスされたLinkを持たせません。別のワークロードがファイルを削除した場合、テーブルには古い情報が残ります。テーブルの行を削除しても、参照されているファイルは手動で削除するまでストレージに残ります。

チェックサム

checksum フィールドは、ファイルバイトの整合性トークンであり、形式は <prefix>:<digest> です。これを使用してファイルを比較したり、ファイルが変更されていないことを検証したりします。リーダーは、認識できないプレフィックスを持つチェックサムを無視します。

チェックサムは常に利用できるとは限りません。to_file 関数、create_file 関数、および copy_file 関数は、オブジェクトストアが ETAG を返すときにチェックサムを生成します。list_files テーブル値関数および read_files テーブル値関数は、チェックサムを生成しません。

checksum フィールドは、次のいずれかのプレフィックスを使用します：

プレフィックス	ダイジェストエンコーディング	説明
ETAG	不透明	ファイル全体に対するオブジェクト ストアの eTag。ストアからそのまま提供され、等価比較にのみ使用され、再計算はできません。
MD5	小文字の hex	MD5 ダイジェスト (RFC 1321)、32 文字の 16 進数。
CRC32	小文字の hex	CRC32チェックサム（RFC 2083）、8桁の16進文字。
CRC32C	小文字の hex	CRC32C チェックサム (RFC 3385)、8 桁の 16 進文字。
SHA-256	小文字の hex	SHA-256 ダイジェスト（RFC 6234）、64 桁の 16 進文字。

プレフィックス	ダイジェストエンコーディング	説明
ETAG	不透明	ファイル全体に対するオブジェクト ストアの eTag。ストアからそのまま提供され、等価比較にのみ使用され、再計算はできません。
MD5	小文字の hex	MD5 ダイジェスト (RFC 1321)、32 文字の 16 進数。
CRC32	小文字の hex	CRC32チェックサム（RFC 2083）、8桁の16進文字。
CRC32C	小文字の hex	CRC32C チェックサム (RFC 3385)、8 桁の 16 進文字。
SHA-256	小文字の hex	SHA-256 ダイジェスト（RFC 6234）、64 桁の 16 進文字。

たとえば、MD5チェックサムは MD5:d41d8cd98f00b204e9800998ecf8427e のようになり、オブジェクトストアのeTagは、オブジェクトストアから返される周囲の二重引用符を含めて ETAG:"686897696a7c876b7e" のようになります。

FILEから BINARY

次の表は、非構造化ファイルを操作するためのオプションを比較したものです。

列タイプ	値	ユースケース
FILE	ファイルへのガバナンスされた参照とメタデータ (uri、size、content_type、checksum)。	構造化データと並行して非構造化ファイルを管理および処理し、ファイルを組み込み関数や AI 関数に渡すために使用します。
BINARY	列にインライン化されたファイルの未加工バイト。	データファイルに直接格納される小さなオブジェクト（defaultで最大64 KB）に使用します。これは、メタデータのオーバーヘッドを低く抑え、ファイル管理を簡素化する必要がある場合に役立ちます。例えば、これを使用してサムネイルを行データとインラインで保存します。

列タイプ	値	ユースケース
FILE	ファイルへのガバナンスされた参照とメタデータ (uri、size、content_type、checksum)。	構造化データと並行して非構造化ファイルを管理および処理し、ファイルを組み込み関数や AI 関数に渡すために使用します。
BINARY	列にインライン化されたファイルの未加工バイト。	データファイルに直接格納される小さなオブジェクト（defaultで最大64 KB）に使用します。これは、メタデータのオーバーヘッドを低く抑え、ファイル管理を簡素化する必要がある場合に役立ちます。例えば、これを使用してサムネイルを行データとインラインで保存します。

FILE EXTERNAL および FILE MANAGED

FILE タイプは、ファイルを管理するための 2 つのアプローチをサポートしています。

• FILE EXTERNAL 列は、Unity Catalogボリューム内の既存のファイルを参照します。ファイルはUnity Catalogボリュームの権限によって保護されていますが、そのライフサイクルはUnity Catalogによって管理されておらず、コピーもされません。データを移動したり、既存のボリュームから読み取るツールを中断したりすることなくファイルを参照する必要がある場合は、このアプローチを使用してください。
• FILE MANAGED 列はファイルをマネージドストレージにコピーします。Unity Catalogがストレージとして使用できるように、databricks.filespace-previewテーブルプロパティをマネージドボリュームパスに設定します。機械学習（ML）トレーニングや検索拡張生成（RAG）など、テーブル経由でのみファイルにアクセスするワークロードに対して、テーブルを通じて管理される簡素化された権限が必要な場合は、このアプローチを使用してください。取り込みパターンについては、FILEタイプとしてのファイルの取り込みを参照してください。

クエリーの場合、外部ファイルとマネージドファイルに違いはありません。

次の図は、FILE 型がどのようにコードをクラウドオブジェクトストレージ内のファイルに接続するかを示しています。

FILE EXTERNAL

FILE EXTERNAL 列は、Unity Catalog ボリューム内に既に存在するファイルへの参照です。

ボリュームに対する必要な権限がある場合は、これらのファイルを更新または削除できます。Databricks では、不変（イミュータブル）ファイルを使用することを推奨しています。テーブルの権限付与によりファイルメタデータは公開されますが、ファイルのバイトを読み取るには、基盤となるボリュームに対する READ VOLUME 権限も必要です。

外部ファイルは、各テーブル行を Unity Catalog ボリューム内の既存のパスにあるファイルにマッピングします：

FILE EXTERNAL の例

FILE EXTERNAL 列を持つテーブルを作成するには：

SQL

CREATE TABLE documents (id BIGINT, file FILE EXTERNAL);

既存のテーブルに FILE EXTERNAL 列を追加するには：

SQL

ALTER TABLE documents ADD COLUMN file FILE EXTERNAL;

ボリュームからテーブルを作成してデータを投入し、各ファイルに一意の ID を割り当てるには、次の手順を実行します。

SQL

CREATE TABLE documents AS
  SELECT monotonically_increasing_id() AS id, file
  FROM list_files('/Volumes/samples/sec/contracts/');

FILE MANAGED

FILE MANAGED 列は、テーブルがマネージドストレージとして使用するために宣言する Unity Catalog ボリュームである FileSpace にファイルのコピーを格納します。それらのライフサイクルは、それらを参照するテーブルに結び付けられています。

以下の動作が FILE MANAGED に適用されます。

• FileSpace を宣言するには、databricks.filespace-preview テーブルプロパティが必要です。
• 管理対象ファイルの読み取りまたは書き込みには、テーブルと FileSpace をバックアップするボリュームの両方へのアクセスが必要です。
• 参照されていないファイルの自動ガベージコレクションはサポートされていません。

SharePoint、Google Drive、OneDrive、SFTP などの外部ソースに保存されている非構造化ファイルは、ai_parse_document 関数や ユーザー定義関数（UDF）などの関数で使用する前に、管理対象ファイルとして取り込む必要があります。取り込みパターンについては、「FILE タイプとしてファイルを取り込む」を参照してください。

マネージド ファイルを使用するには、FILE MANAGED 列を持つテーブルを作成し、databricks.filespace-preview テーブル プロパティをボリューム パスに設定して、ボリュームを FileSpace として宣言します。

Text

'databricks.filespace-preview' = '/Volumes/<catalog>/<schema>/<volume_name>/<optional_path>'

完全な例については、以下の FILE MANAGED の例を参照してください。FileSpace 内のファイルのライフサイクルは、それらを参照する行と結びついています。それらの行を削除すると、ファイルはガベージコレクションの対象となります。

FILE MANAGED の例

FILE MANAGED 列を持つテーブルを作成するには：

SQL

CREATE TABLE reports (id BIGINT, file FILE MANAGED)
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

既存のテーブルに FILE MANAGED カラムを追加するには、次のコードのように、カラムを追加する前に databricks.filespace-preview テーブルプロパティを設定します。

SQL

ALTER TABLE reports SET TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

ALTER TABLE reports ADD COLUMN attachment FILE MANAGED;

FILE MANAGED カラムを FileSpace がないテーブルに追加すると失敗します。

ガバナンスとライフサイクルの比較

次の表は、FILE EXTERNALとFILE MANAGEDがどのようにファイルアクセスを管理し、ファイルのライフサイクルを処理するかを比較したものです：

列のタイプ	FILE EXTERNAL	FILE MANAGED
ファイルアクセス制御	READ VOLUME などのボリューム権限によって管理されます。	テーブルに対する SELECT やボリュームに対する READ VOLUME など、テーブルおよびボリュームの権限によって管理されます。
ライフサイクルとガベージコレクション	ファイルはご自身で管理します。テーブルの行を削除しても、ボリューム内の基礎となるファイルには影響しません。	ファイルは、それらを参照する行に紐付けられています。それらの行を削除すると、ファイルはガベージコレクションの対象となります。自動ガベージコレクションはサポートされていません。

列のタイプ	FILE EXTERNAL	FILE MANAGED
ファイルアクセス制御	READ VOLUME などのボリューム権限によって管理されます。	テーブルに対する SELECT やボリュームに対する READ VOLUME など、テーブルおよびボリュームの権限によって管理されます。
ライフサイクルとガベージコレクション	ファイルはご自身で管理します。テーブルの行を削除しても、ボリューム内の基礎となるファイルには影響しません。	ファイルは、それらを参照する行に紐付けられています。それらの行を削除すると、ファイルはガベージコレクションの対象となります。自動ガベージコレクションはサポートされていません。

FILEタイプのユースケース

外部およびマネージドの FILE 型はどちらも、非構造化データを使用するユースケースにおける次の課題に対処します。

課題	サポートされている FILE タイプ	利点
インラインで保存するにはファイルが大きすぎます。 BINARY	FILE MANAGED または FILE EXTERNAL	FILE 列は参照を格納するため、ファイルは AI 関数または UDF がそれを処理するときにのみ読み取られます。これにより、大きなオブジェクトがテーブル内にインラインでマテリアライズされるのを回避します。
ファイルシステムとテーブル間でのライフサイクルとガバナンスの切断	FILE MANAGED	Databricks は各ファイルのライフサイクルをテーブルに関連付けるため、行を削除すると、ストレージに孤立したファイルが残るのではなく、そのファイルがクリーンアップの対象となります。
ファイルが同じ場所に留まることを必要とする並列ワークロード	FILE EXTERNAL	ファイルは既存のボリュームパスに留まり、テーブルのライフサイクルの影響を受けないため、同じファイルを読み取る他のツールが中断されることはありません。

課題	サポートされている FILE タイプ	利点
インラインで保存するにはファイルが大きすぎます。 BINARY	FILE MANAGED または FILE EXTERNAL	FILE 列は参照を格納するため、ファイルは AI 関数または UDF がそれを処理するときにのみ読み取られます。これにより、大きなオブジェクトがテーブル内にインラインでマテリアライズされるのを回避します。
ファイルシステムとテーブル間でのライフサイクルとガバナンスの切断	FILE MANAGED	Databricks は各ファイルのライフサイクルをテーブルに関連付けるため、行を削除すると、ストレージに孤立したファイルが残るのではなく、そのファイルがクリーンアップの対象となります。
ファイルが同じ場所に留まることを必要とする並列ワークロード	FILE EXTERNAL	ファイルは既存のボリュームパスに留まり、テーブルのライフサイクルの影響を受けないため、同じファイルを読み取る他のツールが中断されることはありません。

次のステップ

• FILE タイプ
• ファイルを FILE タイプとして取り込みます
• チュートリアル: FILEタイプを使用してファイル処理パイプラインを構築する
• ai_parse_document function