ボリュームを作成して操作する

[アーティクル]
04/23/2024

この記事では、表形式ではないデータセットのガバナンスを有効にする Unity Catalog オブジェクトであるボリュームの概要を説明します。ボリュームを作成、管理、操作する方法についても説明します。

ボリューム内のファイルのアップロードと管理の詳細については、「Unity Catalog ボリュームにファイルをアップロードする」および「Unity Catalog ボリュームのファイル管理操作」を参照してください。

Note

ボリュームを操作するときは、カタログエクスプローラーなどの Azure Databricks UI を使っている場合を除き、Databricks Runtime 13.3 LTS 以降を実行している SQL ウェアハウスまたはクラスターを使う必要があります。

Unity Catalog ボリュームとは

ボリュームは、クラウドオブジェクトの保存場所にあるストレージの論理ボリュームを表す Unity Catalog オブジェクトです。ボリュームにより、ファイルのアクセス、格納、管理、整理を行うための機能が提供されます。テーブルにより、表形式データセットに対するガバナンスが提供される一方、ボリュームにより、表形式以外のデータセットに対するガバナンスが追加されます。ボリュームを使うと、構造化データ、半構造化データ、非構造化データなど、任意の形式でファイルの格納とアクセスを実行できます。

重要

ボリュームをテーブルの場所として使用することはできません。ボリュームは、パスベースのデータアクセスのみを目的としています。 Unity Catalog で表形式データを格納するためにテーブルを使用します。

マネージドボリュームとは

マネージドボリュームは、含まれているスキーマの既定の保存場所内に作成される、Unity Catalog によって管理されるストレージボリュームです。マネージドボリュームを使うと、外部の場所やストレージ資格情報のオーバーヘッドなしで、ファイルを操作するための管理されたストレージを作成できます。マネージドボリュームを作成するときに場所を指定する必要はありません。また、マネージドボリューム内のデータに対するすべてのファイルアクセスは、Unity Catalog によって管理されるパスを介して行われます。「ボリューム内のファイルにアクセスするために使用されるパス」を参照してください。

マネージドボリュームを削除すると、このボリュームに格納されているファイルも 30 日以内にクラウドテナントから削除されます。

外部ボリュームとは

外部ボリュームは、Unity Catalog によって管理されるストレージ資格情報を使って外部の場所にあるディレクトリに対して登録された、Unity Catalog によって管理されるストレージボリュームです。外部ボリュームを使うと、既存のクラウドオブジェクトストレージのディレクトリに Unity Catalog データガバナンスを追加できます。外部ボリュームのユースケースとしては、次のようなものがあります。

移行なしでデータファイルにガバナンスを追加する。
Azure Databricks によって取り込むかアクセスする必要がある他のシステムによって生成されたファイルを管理する。
他のシステムによってクラウドオブジェクトストレージから直接アクセスする必要がある Azure Databricks によって生成されたデータを管理する。

外部ボリュームは、Unity Catalog ストレージ資格情報によって管理される外部の場所内のディレクトリである必要があります。 Unity Catalog では、外部ボリューム内のファイルのライフサイクルやレイアウトは管理されません。外部ボリュームを削除しても、Unity Catalog では基になるデータは削除されません。

Note

ボリュームを定義すると、ボリュームパスの下のデータへのクラウド URI アクセスは、そのボリュームのアクセス許可によって管理されます。

ボリューム内のファイルにアクセスするために使用されるパス

ボリュームにアクセスするためのパスは、Apache Spark、SQL、Python、またはその他の言語とライブラリを使う場合でも同じです。これは、Azure Databricks ワークスペースにバインドされたオブジェクトストレージ内のファイルに対する従来のアクセスパターンとは異なります。

ボリューム内のファイルにアクセスするためのパスでは、次の形式を使います。

/Volumes/<catalog>/<schema>/<volume>/<path>/<file-name>

Azure Databricks では、Apache Spark を使う場合にオプションの dbfs:/ のスキームもサポートされるため、次のパスも機能します。

dbfs:/Volumes/<catalog>/<schema>/<volume>/<path>/<file-name>

パス内のシーケンス /<catalog>/<schema>/<volume> は、ファイルに関連付けられている 3 つの Unity Catalog オブジェクト名に対応します。これらのパス要素は読み取り専用であり、ユーザーが直接書き込むことはできません。つまり、ファイルシステム操作を使ってこれらのディレクトリを作成または削除することはできません。これらは自動的に管理され、対応する UC エンティティと同期されます。

Note

クラウドストレージの URI を使用して、外部ボリュームのデータにアクセスすることもできます。

ボリュームの特権

ボリュームではテーブルと同じ基本的な特権モデルが使われますが、テーブルの特権ではテーブル内の行のクエリと操作へのアクセスを許可することに重点が置かれているのに対し、ボリュームの特権ではファイルの操作に重点が置かれています。そのため、ボリュームでは次の特権が導入されます。

「Unity Catalog の権限とセキュリティ保護可能なオブジェクト」を参照してください。

ボリューム特権を管理できるユーザー

ボリューム特権を管理したり、ボリュームを削除したりするには、ボリュームに対する所有者特権が必要です。 Unity Catalog の各オブジェクトに所有者として割り当てられるプリンシパルは 1 つだけであり、所有権は連鎖しない (つまり、カタログの所有者が自動的にそのカタログ内のすべてのオブジェクトの所有者になるわけではない) ため、所有権に関連付けられている特権は、オブジェクト内に含まれるすべてのオブジェクトに適用されます。

つまり、Unity Catalog ボリュームの場合、次のプリンシパルがボリューム特権を管理できます。

親カタログの所有者。
親スキーマの所有者。
ボリュームの所有者。

各オブジェクトは 1 人の所有者しか持つことができませんが、Databricks では、ほとんどのオブジェクトの所有権を個々のユーザーではなく、グループに割り当てることをお勧めします。すべてのオブジェクトの初期所有権は、そのオブジェクトを作成するユーザーに割り当てられます。「Unity Catalog オブジェクトの所有権を管理する」を参照してください。

マネージドボリュームを作成する

マネージドボリュームを作成するには、次のアクセス許可が必要です。

リソース	必要なアクセス許可
[スキーマ]	`USE SCHEMA`、`CREATE VOLUME`
カタログ	`USE CATALOG`

Sql

マネージドボリュームを作成するには、次の構文を使います。

CREATE VOLUME <catalog>.<schema>.<volume-name>;

カタログエクスプローラー

カタログエクスプローラーで管理ボリュームを作成するには:

Azure Databricks ワークスペースで、カタログ をクリックします。
ボリュームを追加するスキーマを検索または参照して、選択します。
[ボリュームの作成] ボタンをクリックします。 (十分な特権が必要です。)
ボリュームの名前を入力します。
コメントを入力します (省略可能)。
Create をクリックしてください。

外部ボリュームを作成する

外部ボリュームを作成するには、次のアクセス許可が必要です。

リソース	必要なアクセス許可
外部の場所	`CREATE EXTERNAL VOLUME`
[スキーマ]	`USE SCHEMA`、 `CREATE VOLUME`
カタログ	`USE CATALOG`

Sql

外部ボリュームを作成するには、次の構文を使って外部の場所内のパスを指定します。

CREATE EXTERNAL VOLUME <catalog>.<schema>.<external-volume-name>
LOCATION 'abfss://<container-name>@<storage-account>.dfs.core.windows.net/<path>/<directory>';

カタログエクスプローラー

カタログエクスプローラーで外部ボリュームを作成するには:

Azure Databricks ワークスペースで、カタログ をクリックします。
ボリュームを追加するスキーマを検索または参照して、選択します。
[ボリュームの作成] ボタンをクリックします。 (十分な特権が必要です。)
ボリュームの名前を入力します。
ボリュームを作成する外部の場所を選択します。
ボリュームを作成するサブディレクトリを反映するようにパスを編集します。
コメントを入力します (省略可能)。
Create をクリックしてください。

ボリュームを削除する

ボリュームを削除できるのは、所有者特権を持つユーザーだけです。「ボリューム特権を管理できるユーザー」を参照してください。

ボリュームを削除するには、次の構文を使います。

DROP VOLUME IF EXISTS <volume-name>;

マネージドボリュームを削除すると、Azure Databricks では 30 日以内に基になるデータが削除されます。外部ボリュームを削除すると、Unity Catalog からボリュームが削除されますが、基になるデータは外部の場所では変更されません。

ボリューム内のファイルを読み取る

ボリュームの内容を表示したり、ボリュームに格納されているファイルにアクセスしたりするには、次のアクセス許可が必要です。

リソース	必要なアクセス許可
体積	`READ`
[スキーマ]	`USE SCHEMA`
カタログCatalog	`USE CATALOG`

パスを使ってボリュームの内容を操作します。「ボリューム内のファイルにアクセスするために使用されるパス」を参照してください。

ボリュームに対するその他のファイル管理操作を作成、削除、実行する

ボリュームに格納されているファイルに対するファイル管理操作を行うには、次のアクセス許可が必要です:

リソース	必要なアクセス許可
ボリューム	`READ`、`WRITE`
[スキーマ]	`USE SCHEMA`
Catalog	`USE CATALOG`

以下のツールを使ってボリュームに対するファイル管理操作を実行できます:

カタログエクスプローラーには、ファイル管理タスク用の UI オプションが多数あります。「カタログエクスプローラーとは」を参照してください。
Databricks ユーティリティ fs コマンド。ファイルシステムユーティリティ (dbutils.fs) を参照してください。
この %fs マジックコマンドは、dbutils.fs と同じ機能を提供します。
ファイルをボリューム UI にアップロードします。「Unity Catalog ボリュームにファイルをアップロードする」を参照してください。
os.listdir() などのソースコマンドを開きます。
一部の bash コマンドがサポートされています。 %sh cp はサポートされていますが、%sh mv はサポートされていません。

ボリューム上のファイルをプログラムで操作する方法の完全な詳細については、「Unity Catalog でファイルを操作する」を参照してください。

ノートブックの例: ボリュームを作成して操作する

次のノートブックは、Unity Catalog ボリュームを作成して操作するための基本的な SQL 構文を示しています。

チュートリアル: Unity Catalog ボリュームのノートブック

ノートブックを入手

ボリュームの予約済みパス

ボリュームには、ボリュームへのアクセスに使われる次の予約済みパスが導入されています。

dbfs:/Volumes
/Volumes

Note

パスは、Apache Spark API と dbutils からのこれらのパスの入力ミスの可能性も考慮して予約されています。前に dbfs:/ が付いているかどうかに関係なく、/volumes、/Volume、/volume が含まれます。パス /dbfs/Volumes も予約されていますが、ボリュームへのアクセスには使用できません。

ボリュームは、Databricks Runtime 13.3 LTS 以降でのみサポートされています。 Databricks Runtime 12.2 LTS 以前では、/Volumes パスに対する操作が成功する可能性がありますが、想定どおりに Unity Catalog ボリュームにデータを保持するのではなく、コンピューティングクラスターにアタッチされたエフェメラルストレージディスクにデータが書き込まれる場合もあります。

重要

DBFS ルートの予約済みパスに格納されている既存のデータがある場合は、サポートチケットを提出してこのデータへの一時的なアクセス権を取得し、別の場所に移動することができます。

制限事項

Unity Catalog ボリュームを操作するには、Unity Catalog 対応コンピューティングを使用する必要があります。すべてのワークロードがボリュームでサポートされているわけではありません。

Note

Executor に配布される dbutils.fs コマンドはボリュームでサポートされていません。

次の制限事項が適用されます。

Databricks Runtime 14.3 LTS 以降:

シングルユーザーのユーザークラスターでは、Scala のスレッドとサブプロセスからボリュームにアクセスすることはできません。

Databricks Runtime 14.2 以前:

共有アクセスモードで構成されたコンピューティングでは、UDF を使用してボリュームにアクセスすることはできません。
- Python と Scala の両方がドライバーから FUSE にアクセスできますが、Executor からはアクセスできません。
- I/O 操作を実行する Scala コードは、ドライバーで実行できますが、Executor ではできません。
シングルユーザーアクセスモードで構成されたコンピューティングでは、Scala の FUSE、ボリュームパスを使用してデータにアクセスする Scala IO コード、または Scala UDF はサポートされません。 Python UDF は、シングルユーザーアクセスモードでサポートされています。

すべてのサポートされている Databricks Runtime バージョン:

Unity Catalog UDF は、ボリュームファイルパスへのアクセスをサポートしていません。
RDD からボリュームにアクセスすることはできません。
ボリュームに格納されている JAR では、spark-submit を使用できません。
Wheel または JAR ファイル内のボリュームパスを介してアクセスされる他のライブラリへの依存関係を定義することはできません。
/Volumes/<catalog-name> パターンまたは /Volumes/<catalog-name>/<schema-name> パターンを使って Unity Catalog オブジェクトを一覧表示することはできません。ボリューム名を含む完全修飾パスを使う必要があります。
REST API の DBFS エンドポイントは、ボリュームパスをサポートしていません。
ボリュームは、Azure Databricks ワークスペースのグローバル検索結果から除外されます。
クラスターログの配信の宛先としてボリュームを指定することはできません。
ボリューム間でのファイルの移動では、%sh mv はサポートされていません。代わりに、dbutils.fs.mv タグまたは %sh cp タグを使用してください。

ボリュームを使ってカスタム Hadoop ファイルシステムを作成することはできません。つまり、以下はサポートされていません。

import org.apache.hadoop.fs.Path
val path =  new Path("dbfs:/Volumes/main/default/test-volume/file.txt")
val fs = path.getFileSystem(sc.hadoopConfiguration)
fs.listStatus(path)

ボリュームは、Azure Government リージョンまたは FedRAMP 準拠のワークスペースでは使用できません。
Azure Data Factory ライブラリ構成パネルでは、dbfs:/ スキームのパス形式を使う必要があります。たとえば、 dbfs:/Volumes/<catalog-name>/<schema-name>/<volume-name>/file です。

ボリュームを作成して操作する

Unity Catalog ボリュームとは

マネージド ボリュームとは

外部ボリュームとは

ボリューム内のファイルにアクセスするために使用されるパス

ボリュームの特権

ボリューム特権を管理できるユーザー

マネージド ボリュームを作成する

Sql

カタログ エクスプローラー

外部ボリュームを作成する

Sql

カタログ エクスプローラー

ボリュームを削除する

ボリューム内のファイルを読み取る

ボリュームに対するその他のファイル管理操作を作成、削除、実行する

ノートブックの例: ボリュームを作成して操作する

チュートリアル: Unity Catalog ボリュームのノートブック

ボリュームの予約済みパス

制限事項

その他のリソース

マネージドボリュームとは

マネージドボリュームを作成する

カタログエクスプローラー

カタログエクスプローラー