使用 Azure Databricks 上的文件

项目
10/07/2024

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 安装笔记本范围的库
pandas
OSS Python 文件管理和处理实用工具

重要

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

Scala 支持在使用 Unity 目录和共享访问模式配置的计算机上运行的 FUSE for Unity Catalog 卷和工作区文件。在配置了单用户访问模式和 Databricks Runtime 14.3 及更高版本的计算机上，Scala 支持将 FUSE 用于 Unity Catalog 卷和工作区文件，但源自 Scala 的子进程除外（例如 Scala 命令 "cat /Volumes/path/to/file".!!）。

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

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

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

使用 Unity Catalog 卷中的文件

Databricks 建议使用 Unity Catalog 卷来配置对云对象存储中存储的非表格数据文件的访问权限。请参阅“什么是 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`
Pandas	`df = pd.read_csv('/Volumes/my_catalog/my_schema/my_volume/data.csv')`
OSS Python	`os.listdir('/Volumes/my_catalog/my_schema/my_volume/path/to/directory')`

注意

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

卷限制

卷具有以下限制：

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

# 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

使用工作区文件

Databrick 工作区文件是工作区中的非笔记本文件。可以使用工作区文件存储和访问与笔记本及其他工作区资产一起保存的数据和其他文件。由于工作区文件的大小限制，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`
Pandas	`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 中的工作区文件大小限制为 500MB。从群集写入时，允许的最大文件大小为 256 MB。
如果工作流使用远程 Git 存储库中的源代码，则无法写入当前目录或使用相对路径进行写入。将数据写入其他位置选项。
保存到工作区文件时，不能使用 git 命令。不允许在工作区文件中创建 .git 目录。
无服务器计算不支持使用 Spark 执行程序（如 spark.read.format("csv").load("file:/Workspace/Users/<user-folder>/data.csv") ）从工作区文件中读取数据。
执行程序无法写入到工作区文件。
不支持符号链接。
在 Databricks Runtime 14.2 及更低版本上，无法从共享访问模式的群集上的用户定义的函数 (UDF) 访问工作区文件。

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

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

请参阅删除对象。

使用云对象存储中的文件

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

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

工具	示例
Apache Spark	`spark.read.format("json").load("abfss://container-name@storage-account-name.dfs.core.chinacloudapi.cn/path/file.json").show()`
Spark SQL 和 Databricks SQL	SELECT * FROM csv.`abfss://container-name@storage-account-name.dfs.core.chinacloudapi.cn/path/file.json`; `LIST 'abfss://container-name@storage-account-name.dfs.core.chinacloudapi.cn/path';`
Databricks 文件系统实用工具	`dbutils.fs.ls("abfss://container-name@storage-account-name.dfs.core.chinacloudapi.cn/path/")` `%fs ls abfss://container-name@storage-account-name.dfs.core.chinacloudapi.cn/path/`
Databricks CLI	不支持
Databricks REST API	不支持
Bash shell 命令	不支持
库安装	`%pip install abfss://container-name@storage-account-name.dfs.core.chinacloudapi.cn/path/to/library.whl`
Pandas	不支持
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`
Pandas	`df = pd.read_csv('/dbfs/mnt/path/to/data.csv')`
OSS 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`
库安装	不支持
Pandas	`df = pd.read_csv('/path/to/data.csv')`
OSS Python	`os.listdir('/path/to/directory')`

注意

使用 Databricks 实用工具时，需要 file:/ 架构。

将数据从临时存储移到卷

你可能想要使用 Apache Spark 访问下载或保存到临时存储的数据。由于临时存储附加到驱动程序，Spark 是分布式处理引擎，因此并非所有操作都可以直接访问此处的数据。假设你必须将驱动程序文件系统中的数据移动到 Unity Catalog 卷。在这种情况下，可以使用 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>

其他资源

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

通过

使用 Azure Databricks 上的文件

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

使用 Unity Catalog 卷中的文件

卷限制

使用工作区文件

工作区文件限制

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

使用云对象存储中的文件

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

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

将数据从临时存储移到卷

其他资源

其他资源