使用 Azure Databricks 上的文件

项目
02/08/2025

Azure Databricks 具有多个实用工具和 API，用于与以下位置中的文件进行交互：

Unity Catalog 卷
工作区文件
云对象存储
DBFS 装载和 DBFS 根
附加到群集驱动程序节点的临时存储

本文提供了以下工具在这些位置与文件交互的示例：

Apache Spark
Spark SQL 和 Databricks SQL
Databricks 文件系统实用工具（dbutils.fs 或 %fs）
Databricks CLI
Databricks REST API
Bash shell 命令 (%sh)
使用 %pip 安装笔记本范围的库
熊猫
OSS Python 文件管理和处理实用工具

重要

需要 FUSE 数据访问的文件操作无法使用 URI 直接访问云对象存储。 Databricks 建议使用 Unity 目录卷为 FUSE 配置对这些位置的访问。

Scala 支持在配置了 Unity Catalog 和共享访问模式的计算资源上使用 FUSE 来访问 Unity Catalog 卷和工作区文件。在配置了单用户访问模式并运行 Databricks Runtime 14.3 及以上版本的计算环境中，Scala 支持 Unity Catalog 卷和工作区文件的 FUSE，唯独源自 Scala 的子进程除外，例如 Scala 命令 "cat /Volumes/path/to/file".!!。

Spark 和其他 JVM 进程只能使用支持 Unity 目录的读取器和编写器访问 Unity 目录卷或工作区文件。例如，不能将 JAR 文件指定为 Spark 配置中的依赖项，并且不能使用 PySpark 自定义数据源。如果您的库中的 JVM 工作负载需要访问卷或工作区文件，请使用 Python 或 shell 命令（如 %sh mv.）将这些文件复制到计算本地存储中。请勿使用使用 JVM 的 %fs 或 dbutils.fs。如果在群集启动时文件需要存在，请使用初始化脚本首先移动文件。请参阅什么是初始化脚本？。

是否需要提供用于访问数据的 URI 方案？

Azure Databricks 中的数据访问路径遵循以下标准之一：

URI 样式路径包括 URI 方案。对于 Databricks 本机数据访问解决方案，对于大多数用例，URI 方案是可选的。直接访问云对象存储中的数据时，必须为存储类型提供正确的 URI 方案。
POSIX 样式的路径 提供相对于驱动程序根（/）的数据访问。 POSIX 样式路径从不需要方案。可以使用 Unity Catalog 卷或 DBFS 装载来提供对云对象存储中数据的 POSIX 样式访问。许多 ML 框架和其他 OSS Python 模块都需要 FUSE，并且只能使用 POSIX 样式的路径。

使用 Unity Catalog 卷中的文件

Databricks 建议使用 Unity 目录卷来配置对存储在云对象存储中的非表格数据文件的访问。请参阅什么是 Unity Catalog 卷？。

工具	例
Apache Spark	`spark.read.format("json").load("/Volumes/my_catalog/my_schema/my_volume/data.json").show()`
Spark SQL 和 Databricks SQL	SELECT * FROM csv.`/Volumes/my_catalog/my_schema/my_volume/data.csv`; `LIST '/Volumes/my_catalog/my_schema/my_volume/';`
Databricks 文件系统实用工具	`dbutils.fs.ls("/Volumes/my_catalog/my_schema/my_volume/")` `%fs ls /Volumes/my_catalog/my_schema/my_volume/`
Databricks CLI	`databricks fs cp /path/to/local/file dbfs:/Volumes/my_catalog/my_schema/my_volume/`
Databricks REST API	`POST https://<databricks-instance>/api/2.1/jobs/create` `{"name": "A multitask job", "tasks": [{..."libraries": [{"jar": "/Volumes/dev/environment/libraries/logging/Logging.jar"}],},...]}`
Bash shell 命令	`%sh curl http://<address>/text.zip -o /Volumes/my_catalog/my_schema/my_volume/tmp/text.zip`
库安装	`%pip install /Volumes/my_catalog/my_schema/my_volume/my_library.whl`
熊猫	`df = pd.read_csv('/Volumes/my_catalog/my_schema/my_volume/data.csv')`
开源软件 Python	`os.listdir('/Volumes/my_catalog/my_schema/my_volume/path/to/directory')`

注意

使用 Databricks CLI 时，需要 dbfs:/ 架构。

容量限制

卷具有以下限制：

不支持直接追加或非顺序（随机）写入，例如写入 Zip 和 Excel 文件。对于直接追加或随机写入工作负荷，请先对本地磁盘执行操作，然后将结果复制到 Unity 目录卷。例如：

# 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：

$ 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

使用工作区文件

Databricks 工作区文件是工作区中的文件。可以使用工作区文件来存储和访问笔记本、源代码文件、数据文件和其他工作区资产等文件。由于工作区文件的大小限制，Databricks 建议仅在此处存储小型数据文件，主要用于开发和测试。

工具	例
Apache Spark	`spark.read.format("json").load("file:/Workspace/Users/<user-folder>/data.json").show()`
Spark SQL 和 Databricks SQL	SELECT * FROM json.`file:/Workspace/Users/<user-folder>/file.json`;
Databricks 文件系统实用工具	`dbutils.fs.ls("file:/Workspace/Users/<user-folder>/")` `%fs ls file:/Workspace/Users/<user-folder>/`
Databricks CLI	`databricks workspace list`
Databricks REST API	`POST https://<databricks-instance>/api/2.0/workspace/delete` `{"path": "/Workspace/Shared/code.py", "recursive": "false"}`
Bash shell 命令	`%sh curl http://<address>/text.zip -o /Workspace/Users/<user-folder>/text.zip`
库安装	`%pip install /Workspace/Users/<user-folder>/my_library.whl`
熊猫	`df = pd.read_csv('/Workspace/Users/<user-folder>/data.csv')`
开源软件 (OSS) Python	`os.listdir('/Workspace/Users/<user-folder>/path/to/directory')`

注意

使用 Databricks Utilities、Apache Spark 或 SQL 时，需要 file:/ 架构。

有关使用工作区文件的限制，请参阅限制。

删除的工作区文件在何处？

删除工作区文件会将其发送到回收站。可以使用 UI 从回收站恢复或永久删除文件。

请参阅删除对象。

使用云对象存储中的文件

Databricks 建议使用 Unity 目录卷配置对云对象存储中的文件的安全访问。如果选择使用 URI 直接访问云对象存储中的数据，则必须配置权限。请参阅管理外部位置、外部表和外部卷。

以下示例使用 URI 访问云对象存储中的数据：

工具	例
Apache Spark	`spark.read.format("json").load("abfss://container-name@storage-account-name.dfs.core.windows.net/path/file.json").show()`
Spark SQL 和 Databricks SQL	SELECT * FROM csv.`abfss://container-name@storage-account-name.dfs.core.windows.net/path/file.json`;`LIST 'abfss://container-name@storage-account-name.dfs.core.windows.net/path';`
Databricks 文件系统实用工具	`dbutils.fs.ls("abfss://container-name@storage-account-name.dfs.core.windows.net/path/")%fs ls abfss://container-name@storage-account-name.dfs.core.windows.net/path/`
Databricks CLI	不支持
Databricks REST API	不支持
Bash shell 命令	不支持
库安装	`%pip install abfss://container-name@storage-account-name.dfs.core.windows.net/path/to/library.whl`
熊猫	不支持
OSS Python	不支持

注意

使用 DBFS 装载和 DBFS 根目录中的文件

DBFS 装载无法使用 Unity Catalog 进行保护，Databricks 不再建议使用。存储在 DBFS 根目录中的数据可供工作区中的所有用户访问。 Databricks 建议不要将任何敏感代码或生产代码或数据存储在 DBFS 根目录中。请参阅什么是 DBFS？。

工具	例
Apache Spark	`spark.read.format("json").load("/mnt/path/to/data.json").show()`
Spark SQL 和 Databricks SQL	SELECT * FROM json.`/mnt/path/to/data.json`;
Databricks 文件系统实用工具	`dbutils.fs.ls("/mnt/path")` `%fs ls /mnt/path`
Databricks CLI	`databricks fs cp dbfs:/mnt/path/to/remote/file /path/to/local/file`
Databricks REST API	`POST https://<host>/api/2.0/dbfs/delete --data '{ "path": "/tmp/HelloWorld.txt" }'`
Bash shell 命令	`%sh curl http://<address>/text.zip > /dbfs/mnt/tmp/text.zip`
库安装	`%pip install /dbfs/mnt/path/to/my_library.whl`
熊猫	`df = pd.read_csv('/dbfs/mnt/path/to/data.csv')`
开放源代码Python	`os.listdir('/dbfs/mnt/path/to/directory')`

注意

使用 Databricks CLI 时，需要 dbfs:/ 架构。

使用附加到驱动程序节点的临时存储中的文件

附加到驱动程序节点的临时存储是支持基于内置 POSIX 的路径访问的块存储。当群集终止或重启时，此位置中存储的任何数据都消失。

工具	例
Apache Spark	不支持
Spark SQL 和 Databricks SQL	不支持
Databricks 文件系统实用工具	`dbutils.fs.ls("file:/path")` `%fs ls file:/path`
Databricks CLI	不支持
Databricks REST API	不支持
Bash shell 命令	`%sh curl http://<address>/text.zip > /tmp/text.zip`
库安装	不支持
熊猫	`df = pd.read_csv('/path/to/data.csv')`
开源软件 Python	`os.listdir('/path/to/directory')`

注意

使用 Databricks Utilities 时，需要 file:/ 架构。

将数据从临时存储移到卷

你可能想要使用 Apache Spark 访问下载或保存到临时存储的数据。由于临时存储附加到驱动程序，Spark 是分布式处理引擎，因此并非所有操作都可以直接访问此处的数据。假设必须将数据从驱动程序文件系统移动到 Unity 目录卷。在这种情况下，可以使用 magic 命令或 Databricks 实用工具复制文件，如以下示例所示：

dbutils.fs.cp ("file:/<path>", "/Volumes/<catalog>/<schema>/<volume>/<path>")

%sh cp /<path> /Volumes/<catalog>/<schema>/<volume>/<path>

%fs cp file:/<path> /Volumes/<catalog>/<schema>/<volume>/<path>

其他资源

有关上传本地文件或将 Internet 文件下载到 Azure Databricks 的信息，请参阅将文件上传到 Azure Databricks。

通过

使用 Azure Databricks 上的文件

是否需要提供用于访问数据的 URI 方案？

使用 Unity Catalog 卷中的文件

容量限制

使用工作区文件

删除的工作区文件在何处？

使用云对象存储中的文件

使用 DBFS 装载和 DBFS 根目录中的文件

使用附加到驱动程序节点的临时存储中的文件

将数据从临时存储移到卷

其他资源

反馈

其他资源