Unity カタログ ボリューム内のファイルを操作する

このページには、さまざまなユーザー インターフェイス、ツール、ライブラリ、言語の Unity カタログ ボリューム でファイルを管理する例が示されています。

注

ベータ版で利用可能で、 FILE 型を使ってボリューム内のファイルをテーブルの値として参照し、テーブルアクセス制御を適用できます。 FILEタイプおよび非構造化データを参照してください。

Databricks では、クラウド オブジェクト ストレージ内の表形式以外のデータへのすべてのアクセスを管理したり、ワークロード サポート ファイルを格納したりするために、ボリュームを使用することをお勧めします。 例を次に示します。

  • 取り込み用のデータ ファイル (CSV、JSON、Parquet など)
  • データ サイエンス、ML、AI ワークロード用のテキスト、画像、およびオーディオ ファイル
  • 外部システムとの統合のために Azure Databricks によって記述された CSV または JSON 成果物
  • ライブラリ、init スクリプト、アーティファクトのビルド

ボリュームには、Filesystem in Userspace (FUSE) に依存するツールやフレームワークで動作する、Portable Operating System Interface (POSIX) 形式のパスを提供します。 これにより、POSIX スタイルのアクセスを必要とする機械学習フレームワークやオープン ソースの Python モジュールに最適です。 URI スキーム、POSIX パス、およびボリュームとの関係の詳細については、「 データにアクセスするための URI スキームを提供する必要がありますか?」を参照してください。

ボリューム内のファイルを管理するためのメソッド

各方法の簡単な例については、 Unity カタログ ボリューム内のファイルの操作に関するページを参照してください。

インターフェイス Description
カタログエクスプローラーUI Azure Databricks ワークスペースを使用した対話型ファイル管理
プログラムによるアクセス Apache Spark、Pandas、または SQL を使用したファイルの読み取りと書き込み
Databricksユーティリティ ノートブックの dbutils.fs コマンドまたはマジック コマンド (%fs、 %sh) を使用したファイル操作
ファイルの一覧表示とクエリ READ_FILESを使用してファイル メタデータのクエリを実行し、プロパティでフィルター処理する
SQLコマンド SQL キーワード (LIST、 PUT INTO、 GET、 REMOVE) とコネクタを使用したファイル操作
Databricks CLI databricks fs コマンドを使用したコマンド ライン操作
SDKs Python、Java、または Go SDK を使用したファイル操作
REST API カスタム統合用の直接 API アクセス

カタログ エクスプローラーを使用する

カタログ エクスプローラーには、Unity カタログ ボリュームに格納されているファイルの一般的なファイル管理タスクのオプションがあります。

ボリューム内のファイルを操作するには、次のようにします。

  1. Azure Databricks ワークスペースで、[ データ] アイコンをクリックします。カタログ。
  2. 操作するボリュームを検索または参照して、それを選択します。

ボリュームの作成と管理の詳細については、「 Unity カタログ ボリュームの作成と管理」を参照してください。

ボリュームにファイルをアップロードする

構造化、半構造化、非構造化のファイルを任意の形式でボリュームにアップロードできます。 ボリュームは、基になるクラウド ストレージでサポートされる最大サイズまでのファイルをサポートします。 ただし、Azure Databricks UI を使用してボリュームにファイルをアップロードする場合、5 GB のファイル サイズ制限があります。 大きなファイルをアップロードするには、Python v0.72.0以上のDatabricks SDKをご利用ください。 「Unity Catalog ボリューム内のファイルを管理する」を参照してください。 また、Files API 3.0のマルチパートアップロードもベータ版で利用できます。

Azureストレージアカウントにファイアウォールが有効になっている場合、Python用のDatabricks SDKを通じたアップロードは5GBに制限されます。

Requirements

ボリュームにアップロードする前に、次のものを用意してください。

  • Unity カタログが有効になっているワークスペース
  • WRITE VOLUME をターゲット ボリュームに対して
  • USE SCHEMA 親スキーマ上で
  • 親カタログの USE CATALOG

詳細については、 Unity カタログの特権リファレンスを参照してください。

アップロード手順

  1. サイドバーで[ 新規]、[データの 追加またはアップロード]の順にクリックします。
  2. [ ファイルをボリュームにアップロード] をクリックします。
  3. [ ファイル] で、[ 参照 ] をクリックするか、ドロップ ゾーンにファイルをドラッグ アンド ドロップします。
  4. [ 宛先ボリューム] で、ボリュームまたはディレクトリを選択するか、ボリューム パスを貼り付けます。

ターゲット スキーマにボリュームが存在しない場合は、[ボリュームの作成] をクリックして ボリュームを作成できます。 ボリューム内に新しいディレクトリを作成できます。

注

最初にカタログ、スキーマ、ボリュームを作成せずに独自のファイルをアップロードするには、宛先としてユーザーごとのボリュームである [マイ ファイル] を選択できます。 マイ ファイルは ベータ版です。 「 マイ ファイルにファイルを保存する」を参照してください。

UIを使ってファイルをボリュームにアップロードする方法

アップロード UI には、次の方法でアクセスすることもできます。

  • カタログ エクスプローラー: データの追加>ボリュームへのファイルのアップロード
  • ノートブックから: ファイル>ボリュームへのファイルのアップロード

次のステップ

ボリュームにアップロードした後、次の操作を行うことができます。

ボリューム内のファイルを編集する

Azure Databricksのファイルエディターでボリュームに保存されたテキストファイルを開いて、その場で編集できます。ファイルをダウンロードして再度アップロードする必要はありません。 エディターは変更内容を自動的にボリュームに保存します。

エディターでファイルを開くには以下の権限が必要です:

ボリューム内のファイルを編集するには:

  1. Catalog Explorer で、ファイルを含むボリュームに移動します。

  2. ファイル名の隣にある Kebabメニュー アイコンのKebabメニューをクリックしてから、「Editorで開く」をクリックしてください。

    ファイル名をクリックしてプレビューを開き、次に Notebook アイコン。[エディターで開く] アイコンをクリックすることもできます。

  3. ファイルを編集します。 エディターは変更内容を自動的にボリュームに保存します。

ノートブックやSQLエディタからボリュームファイルを開くことも可能です。 スキーマ ブラウザーでファイルにカーソルを合わせ、ケバブ メニュー アイコンケバブ メニューをクリックして、[ファイルを開く] をクリックします。

エディターを開いたままファイルがエディターの外部で変更された場合、エディターは「競合が検出されました」ダイアログを表示します。 はい、最新の変更を取得するをクリックしてファイルの最新バージョンを読み込むか、いいえ、内容を上書きをクリックしてその上に自分のバージョンを保存します。

エディターでは Genie Code を使ってファイルを読み編集できます。 Genie Code が編集できるのは、エディターで開いているファイルのみです。また、それはボリュームに対する WRITE VOLUME 権限を持っている場合に限られます。

サポートされているファイルの種類

エディターは以下の拡張子のファイルを開きます:

  • テキストファイル:txt、log、md
  • コードファイル:py、scala、sql、r、sh
  • 半構造化データ ファイル: json, ndjson, jsonl, csv, tsv, tab
  • 構成ファイル: yaml, yml, toml, ini, conf, properties, env

stdoutやstderrと名付けられたファイルもエディターで開かれます。

Limitations

エディターには以下の制限があります:

  • ファイルが10MBを超えると、エディターで開くことはできません。 ファイルを編集するには、ダウンロードしてローカルで編集し、再度アップロードしてください。
  • 画像、PDF、Parquetファイルのように前のリストにない拡張子を持つファイルは、エディターで開くことはできません。 画像、PDF、Parquetファイルなど対応フォーマットもプレビュー可能です。 ボリューム内のファイルのプレビューを参照してください。
  • ファイルエディタはAzure GovernmentやAzure Chinaのリージョンでは利用できません。

ボリュームからファイルをダウンロードする

ボリュームからファイルをダウンロードするには、次のようにします。

  1. 1 つ以上のファイルを選択します。
  2. [ ダウンロード ] をクリックしてこれらのファイルをダウンロードします。

ボリュームからファイルを削除する

ボリュームからファイルを削除するには、次のようにします。

  1. 1 つ以上のファイルを選択します。
  2. [ 削除] をクリックします。
  3. 表示されるダイアログで[ 削除 ]をクリックして確定します。

空のディレクトリを作成する

ボリュームに新しいディレクトリを作成するには、次のようにします。

  1. [ボリュームの概要] タブで、[ ディレクトリの作成] をクリックします。
  2. ディレクトリの名前を入力します。
  3. Create をクリックしてください。

ディレクトリをダウンロードする

ボリューム内のディレクトリをダウンロードするには、次の操作を行います。

  1. Kebab メニュー アイコン をクリックします。ディレクトリの右側にある kebab メニュー。
  2. [ ディレクトリのダウンロード] をクリックします。

ディレクトリは ZIP ファイルとしてダウンロードされます。

ボリュームからディレクトリを削除する

ボリュームからディレクトリを削除するには、次のようにします。

  1. 1 つ以上のディレクトリを選択します。
  2. [ 削除] をクリックします。
  3. 表示されるダイアログで[ 削除 ]をクリックして確定します。

ボリューム向けの UI におけるファイル管理タスク

ファイル名の横にある ケバブ メニュー アイコン ケバブ メニューをクリックして、以下の操作を行います。

  • エディターで開く(サポートされているテキスト ファイルのみ)。 「 ボリューム内のファイルを編集する」を参照してください。
  • パスをコピー
  • ファイルのダウンロード
  • ファイルを削除する
  • テーブルの作成

ボリューム内のデータからテーブルを作成する

Azure Databricks には、Unity Catalog ボリュームに保存されている 1 つ以上のファイルまたはファイルのディレクトリから Unity Catalog のマネージド テーブルを作成するための UI が用意されています。

ターゲット スキーマでの CREATE TABLE アクセス許可があり、実行中の SQL ウェアハウスにアクセスできる必要があります。

  1. 1 つ以上のファイルまたはディレクトリを選択します。 ファイルのデータ レイアウトは同じである必要があります。

  2. [ テーブルの作成] をクリックします。 [Create table from volumes] (ボリュームからテーブルを作成) ダイアログが表示されます。

  3. 提供されたダイアログを使用して、データのプレビューを確認し、次の構成を完了します。

    • [新しいテーブルの作成] または [既存のテーブルの上書き] を選択する。
    • ターゲットの カタログ とスキーマを選択 します。
    • テーブル名を指定します。
    • (オプション) 既定の列名と型をオーバーライドするか、列の除外を選択します。

    注

    [ 詳細属性 ] をクリックすると、追加のオプションが表示されます。

  4. [ テーブルの作成 ] をクリックして、指定した属性を持つテーブルを作成します。 完了すると、Catalog Explorer にテーブルの詳細が表示されます。

プログラムによってボリューム内のファイルを操作する

次の形式を使用して、サポートされているすべての言語およびワークスペース エディターからボリューム内のファイルの読み取りと書き込みを行います。

/Volumes/catalog_name/schema_name/volume_name/path/to/files

ボリューム内のファイルの操作方法は、クラウド オブジェクト ストレージの場所にあるファイルの操作方法と同じです。 つまり、現在クラウド URI、DBFS マウント パス、または DBFS ルート パスを使用してデータやファイルを操作するコードを管理している場合は、代わりにボリュームを使用するようにコードを更新できます。

注

ボリュームは、表形式以外のデータにのみ使用されます。 Databricks では、Unity Catalog テーブルを使用して表形式データを登録してから、テーブル名を使用してデータの読み取りと書き込みを行うことをお勧めします。

ボリューム内のデータの読み取りと書き込み

Apache Spark、pandas、Spark SQL、およびその他の OSS ライブラリを使用して、ボリューム内のデータ ファイルの読み取りと書き込みを行います。

次の例は、ボリュームに保存されている CSV ファイルの読み取りを示しています。

Python

df = spark.read.format("csv").load("/Volumes/catalog_name/schema_name/volume_name/data.csv")

display(df)

Pandas

import pandas as pd

df = pd.read_csv('/Volumes/catalog_name/schema_name/volume_name/data.csv')

display(df)

SQL

SELECT * FROM csv.`/Volumes/catalog_name/schema_name/volume_name/data.csv`

ボリューム内のファイルに対するユーティリティ コマンド

Databricks には、ボリューム内のファイルを管理するための次のツールが用意されています。

これらのツールを使用して、インターネットからファイルをダウンロードし、ファイルを解凍し、エフェメラル ブロック ストレージからボリュームにファイルを移動する方法の例については、「インターネットからデータをダウンロードする」を参照してください。

次の例に示すように、Python os モジュールなどのファイル ユーティリティ コマンドに OSS パッケージを使用することもできます。

import os

os.mkdir('/Volumes/catalog_name/schema_name/volume_name/directory_name')

ボリューム内のDataFrameチェックポイント

Unity カタログ のボリューム パスを使用して 、DataFrame チェックポイントを格納できます。 DataFrame チェックポイントでは、DataFrame の実行プランが切り捨てられ、その内容がストレージに保存されます。 これにより、DataFrame を再利用するときに系列が過度に長くなりすぎないようにすることで、反復アルゴリズムと複雑なクエリ プランのパフォーマンスを向上させることができます。

Unity カタログ ボリュームにチェックポイントを格納すると、ガバナンスとアクセス制御がチェックポイント データに適用され、管理されていないクラウド ストレージ パスから離れるのに役立ちます。

Requirements

  • Databricks Runtime 18.1 以降。
  • 専用または標準アクセス モードの Unity カタログ対応コンピューティング。 ボリューム内の DataFrame チェックポイントは、サーバーレス コンピューティングではサポートされていません。

チェックポイント ディレクトリを構成する

チェックポイント ディレクトリを設定する方法は、コンピューティングのアクセス モードによって異なります。

専用アクセス モード

専用アクセス モードのコンピューティングでは、 SparkContext.setCheckpointDirを使用します。

spark.checkpoint.dir=/Volumes/<catalog>/<schema>/<volume>/checkpoint
標準アクセス モード

標準アクセス モードのコンピューティングでは、 spark.checkpoint.dir Spark 構成を使用します。

spark.conf.set("spark.checkpoint.dir", "/Volumes/<catalog>/<schema>/<volume>/checkpoints")

DataFrame チェックポイントを作成する

チェックポイント ディレクトリを構成した後、 DataFrame.checkpoint() を使用して実行プランを切り捨て、データを保存します。

df = spark.range(100).withColumn("doubled", col("id") * 2)
checkpointed_df = df.checkpoint()

注

DataFrame チェックポイントは、構造化ストリーミング チェックポイントとは異なります。 ストリーミング チェックポイント データをボリュームに格納する方法については、「 構造化ストリーミング チェックポイント」を参照してください。

SQL を使用してボリューム内のファイルを一覧表示およびクエリする

read_filesテーブル値関数 SQL 関数を使用して、ボリューム内のファイルを一覧表示し、そのメタデータに対してクエリを実行できます。 これは、ファイルの検出、ファイル プロパティによるフィルター処理、 AI 関数を使用した処理のためのファイルの準備に役立ちます。

READ_FILESでformat => "binaryFile"を使用すると、関数は次の列を持つテーブルを返します。

  • path:ファイルパス全体
  • modificationTime:最後の修正タイムスタンプ
  • length: ファイルサイズ(バイト単位)
  • content: 生のファイルの内容(バイナリデータ)

_metadata列を選択して、file_path、file_name、file_size、file_modification_timeなどの追加のファイル情報にアクセスすることもできます。

ボリューム内のすべてのファイルを一覧表示する

次の例では、バイナリ コンテンツを除き、ボリューム内のすべてのファイルを一覧表示します。

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  "/Volumes/<catalog>/<schema>/<volume>",
  format => "binaryFile"
);

種類とサイズでファイルをフィルター処理する

次の例では、20 KB から 1 MB の画像ファイルをフィルター処理します。

SELECT * EXCEPT (content), _metadata
FROM read_files(
  "/Volumes/my_catalog/my_schema/my_volume",
  format => "binaryFile",
  fileNamePattern => "*.{jpg,jpeg,png,JPG,JPEG,PNG}"
)
WHERE _metadata.file_size BETWEEN 20000 AND 1000000;

変更時刻でファイルをフィルター処理する

次の例では、最後の日に変更された PDF ファイルを検索します。

SELECT * EXCEPT (content), _metadata
FROM read_files(
  "/Volumes/my_catalog/my_schema/my_volume",
  format => "binaryFile",
  fileNamePattern => "*.{pdf,PDF}"
)
WHERE modificationTime >= current_timestamp() - INTERVAL 1 DAY;

AI 関数を使用して画像を処理する

次の例では、ai_query関数関数を使用して、イメージ ファイルの説明を生成します。

SELECT
  path AS file_path,
  ai_query(
    'system.ai.llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  "/Volumes/my_catalog/my_schema/my_volume",
  format => "binaryFile",
  fileNamePattern => "*.{jpg,jpeg,png}"
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

AI 関数を使用してドキュメントを解析する

次の例では、 ai_parse_document 関数を 使用して PDF レシートから構造化データを抽出します。

SELECT
  path AS file_path,
  ai_parse_document(content, map('version', '2.0')) AS result
FROM read_files(
  "/Volumes/main/public/my_files/",
  format => "binaryFile",
  fileNamePattern => "*.{pdf,PDF}"
)
WHERE _metadata.file_name ILIKE '%receipt%';

外部ツールからボリューム内のファイルを管理する

Databricks には、ローカル環境または統合システムからボリューム内のファイルをプログラムで管理するための一連のツールが用意されています。

ボリューム内のファイルに対する SQL コマンド

Azure Databricks では、ボリューム内のファイルを操作するための次の SQL キーワードがサポートされています。

Azure Databricks ノートブックと SQL クエリ エディターでは、 LIST コマンドのみがサポートされています。 その他の SQL コマンド (PUT INTO、 GET、 REMOVE) は、ボリューム内のファイルの管理をサポートする次の Databricks SQL コネクタとドライバーを使用して使用できます。

Databricks CLI を使用してボリューム内のファイルを管理する

databricks fsでサブコマンドを使用します。 コマンド グループfs参照してください。

注

Databricks CLI では、すべてのボリューム パスの前にスキーム dbfs:/ を付ける必要があります。 たとえば、「 dbfs:/Volumes/catalog_name/schema_name/volume_name/path/to/data 」のように入力します。

SDK を使用してボリューム内のファイルを管理する

次の SDK では、ボリューム内のファイルの管理がサポートされています。

REST API を使用してボリューム内のファイルを管理する

Files API を使用して、ボリューム内のファイルを管理します。

ボリューム内のファイルに対する REST API の例

以下の例では、 curl とFiles API 3.0を用いてボリューム内のファイル管理タスクを実行します。

Important

Files API 3.0は ベータ版です。 使用するには、ワークスペース管理者がPreviewsページからFiles API V3 with Large File Upload Supportを有効にする必要があります。 Manage Azure Databricks プレビューを参照してください。

次の例では、指定したボリュームに my-folder という名前の空のフォルダーを作成します。

curl --request PUT "https://${REGIONAL_WORKSPACE_HOST}/api/3.0/fs/directories/Volumes/main/default/my-volume/my-folder/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

次の例では、ボリューム内の指定したパスに指定したデータを含む data.csv という名前のファイルを作成します。

curl --request PUT "https://${REGIONAL_WORKSPACE_HOST}/api/3.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv?overwrite=true" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/octet-stream" \
--data-binary $'id,Text\n1,Hello World!'

次の例では、指定したパス内のボリュームの内容を一覧表示します。 この例では 、jq を使用して、読みやすくするために応答本文の JSON を書式設定します。

curl --request GET "https://${REGIONAL_WORKSPACE_HOST}/api/3.0/fs/directories/Volumes/main/default/my-volume/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq .

次の例では、指定したパスにあるボリューム内のフォルダーの内容を一覧表示します。 この例では 、jq を使用して、読みやすくするために応答本文の JSON を書式設定します。

curl --request GET "https://${REGIONAL_WORKSPACE_HOST}/api/3.0/fs/directories/Volumes/main/default/my-volume/my-folder" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" | jq .

次の例では、ボリューム内の指定したパスにあるファイルの内容を出力します。

curl --request GET "https://${REGIONAL_WORKSPACE_HOST}/api/3.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

次の例では、指定したパス内のファイルをボリュームから削除します。

curl --request DELETE "https://${REGIONAL_WORKSPACE_HOST}/api/3.0/fs/files/Volumes/main/default/my-volume/my-folder/data.csv" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

次の例では、指定したボリュームからフォルダーを削除します。

curl --request DELETE "https://${REGIONAL_WORKSPACE_HOST}/api/3.0/fs/directories/Volumes/main/default/my-volume/my-folder/" \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

ボリューム内のファイル扱いの制限

ボリューム内のファイルを操作する前に、次の制限事項を考慮してください。

  • 直接追加書き込みまたは非順次 (ランダム) 書き込みはサポートされていません。 これは、Zip ファイルや Excel ファイルの書き込みなどの操作に影響します。 これらのワークロードの場合:

    1. 最初にローカル ディスクに対して操作を実行する
    2. 結果をボリュームにコピーする

    例えば次が挙げられます。

    # python
    import xlsxwriter
    from shutil import copyfile
    
    workbook = xlsxwriter.Workbook('/local_disk0/tmp/excel.xlsx')
    worksheet = workbook.add_worksheet()
    worksheet.write(0, 0, "Key")
    worksheet.write(0, 1, "Value")
    workbook.close()
    
    copyfile('/local_disk0/tmp/excel.xlsx', '/Volumes/my_catalog/my_schema/my_volume/excel.xlsx')
    
  • カタログエクスプローラーは1MBを超えるスプレッドシートファイル(xls、xlsx)やZIP64形式のファイルをプレビューできません。 ボリューム内のファイルのプレビューを参照してください。

  • スパース ファイルはサポートされていません。 スパース ファイルをコピーするには、 cp --sparse=neverを使用します。

    $ cp sparse.file /Volumes/my_catalog/my_schema/my_volume/sparse.file
    error writing '/dbfs/sparse.file': Operation not supported
    $ cp --sparse=never sparse.file /Volumes/my_catalog/my_schema/my_volume/sparse.file