メインコンテンツまでスキップ

Unity Catalog ボリューム内のファイルを操作する

このページには、さまざまなユーザー インターフェイス、ツール、ライブラリ、言語の Unity Catalog ボリューム 内のファイルを管理する例を示します。

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

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

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

ボリューム内のファイルを管理する方法​

各方法の簡単な例については、「 Unity Catalog ボリューム内のファイルの操作」を参照してください。

インターフェイス

説明

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

Databricks ワークスペースを使用した対話型ファイル管理

プログラムによるアクセス

Apache Spark、Pandas、または SQL を使用してファイルの読み取りと書き込みを行います

Databricksユーティリティ

ノートブックで dbutils.fs コマンドまたはマジックコマンド(%fs、 %sh)を使用したファイル操作

SQL コマンド

SQL キーワード (LIST、 PUT INTO、 GET、 REMOVE) とコネクタを使用したファイル操作

Databricks CLI

コマンド databricks fs を使用したコマンド行操作

SDK

Python、Java、または Go SDK を使用したファイル操作

REST API

カスタム統合のための直接 API アクセス

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

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

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

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

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

ボリュームへのファイルのアップロード​

任意の形式 (構造化、半構造化、非構造化) のファイルをボリュームにアップロードできます。UI からアップロードする場合、ファイル サイズには 5 GB の制限があります。ただし、ボリューム自体は、基盤となるクラウドストレージでサポートされている最大サイズまでのファイルをサポートします。Spark を使用して非常に大きなファイルを書き込んだり、Databricks API または SDK を使用して大きなファイルをアップロードしたりできます。

必要条件​

ボリュームにアップロードする前に、次のものがあることを確認してください。

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

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

アップロードステップ​

  1. カタログエクスプローラで、「 データの追加 」>「 ボリュームへのアップロード」 をクリックします。
  2. [ 参照 ] をクリックするか、ファイルをドロップ ゾーンにドロップします。
  3. ボリュームまたはディレクトリを選択するか、ボリュームパスを貼り付けます。
    • ターゲット・スキーマにボリュームが存在しない場合は、ボリュームを作成します。
    • ターゲットボリューム内に新しいディレクトリを作成することもできます。

ボリュームにファイルをアップロードするためのダイアログ

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

  • サイドバーで: 新しい > データを追加 > ファイルをボリュームにアップロード
  • ノートブックから: ファイル > ボリュームにファイルをアップロード する

次のステップ​

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

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

ボリュームからファイルをダウンロードするには、次の操作を行います。

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

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

ボリュームからファイルを削除するには、次の操作を行います。

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

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

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

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

ボリュームからのディレクトリの削除​

ボリュームからディレクトリを削除するには、次の操作を行います。

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

ボリュームの UI ファイル管理タスク​

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

  • パスをコピー
  • ファイルをダウンロード
  • ファイルを削除
  • テーブルを作成

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

Databricks は、Unity Catalogボリュームに格納されているファイル、ファイル、またはファイルのディレクトリからUnity Catalogマネージドテーブルを作成するための UI を提供します。

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

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

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

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

    • 新しいテーブルの作成 または 既存のテーブルを上書きする を選択します

    • ターゲットの カタログ と スキーマ を選択します。

    • [テーブル名] を指定します。

    • (オプション)デフォルトの列名と型を上書きするか、列を除外することを選択します。

注記

詳細属性 をクリックして、追加オプションを表示します。

  1. テーブルを作成 をクリックして、指定した属性でテーブルを作成します。 完了すると、カタログエクスプローラにテーブルの詳細が表示されます。

ボリューム内のファイルをプログラムで操作する​

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

/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)

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

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

  • Databricks ユーティリティのdbutils.fsサブモジュール。ファイルシステムユーティリティ (dbutils.fs)を参照してください。
  • %fsマジック、これはdbutils.fsの別名です。
  • ボリュームに対してbashコマンドを許可する %sh マジック。

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

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

Python
import os

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

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

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

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

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

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 を使用したボリューム内のファイルの管理​

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

ボリューム内のファイルの REST API の例​

次の例では、 curl と Databricks REST API を使用して、ボリューム内のファイル管理タスクを実行します。

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

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

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

Bash
curl --request PUT "https://${DATABRICKS_HOST}/api/2.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 をフォーマットします。

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

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

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

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

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

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

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

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

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

ボリューム内のファイルの操作の制限​

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

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

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

    例えば：

    Python
    # 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')

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

    Bash
    $ 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
に最終更新