使用 COPY INTO 通过 Unity Catalog 存储卷或外部位置加载数据

本文介绍如何使用 COPY INTO 命令将数据从 Azure 帐户中的 Azure Data Lake Storage （ADLS）容器加载到 Databricks SQL 中的表中。

本文中的步骤假定管理员已配置 Unity 目录卷或外部位置，以便可以在 ADLS 中访问源文件。如果管理员已将计算资源配置为使用服务主体，请参阅使用 COPY INTO 和服务主体加载数据或教程：COPY INTO 和 Spark SQL。如果管理员为你提供了临时凭据（Blob SAS 令牌），请按照使用 COPY INTO 和临时凭据加载数据中的步骤操作。

Databricks 建议使用卷来访问云存储中的文件，作为使用 COPY INTO 执行的引入过程的一部分。有关使用卷和外部位置的建议的详细信息，请参阅 Unity Catalog 最佳做法。

开始之前

在使用 COPY INTO 从被定义为 Unity Catalog 外部位置的 Unity Catalog 存储卷或云对象存储路径来加载数据之前，您必须具备以下条件：

对 READ VOLUME 卷的特权或 READ FILES 对外部位置的特权。有关创建卷的详细信息，请参阅什么是 Unity Catalog 卷？。有关创建外部位置的详细信息，请参阅外部位置概述。
您的源数据路径，可以是云对象存储的 URL 或卷路径。

示例云对象存储 URL：abfss://container@storageAccount.dfs.core.chinacloudapi.cn/raw-data/json。

示例卷路径：/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data/json。
对包含目标表的架构的 USE SCHEMA 特权。
父目录上的 USE CATALOG 特权。

有关 Unity 目录特权的详细信息，请参阅 Unity 目录特权参考。

从卷加载数据

若要从 Unity Catalog 卷加载数据，必须拥有 READ VOLUME 特权。卷特权适用于指定卷下的所有嵌套目录。

例如，如果您有权访问路径为 /Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/ 的卷。以下命令是有效的：

COPY INTO landing_table
FROM '/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data'
FILEFORMAT = PARQUET;

COPY INTO json_table
FROM '/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data/json'
FILEFORMAT = JSON;

卷路径（例如 dbfs:）也支持使用 dbfs:/Volumes/... 方案前缀，但 Databricks 建议使用上面所示的 /Volumes/ 路径格式。

使用外部位置加载数据

注意事项

Databricks 建议使用卷访问云存储中的文件。支持使用外部位置，但这并不是推荐的方法。请参阅托管表和外部表。

以下示例使用 Unity 目录外部位置将数据从 ADLS 加载到表中，以提供对源数据的访问权限。

COPY INTO my_json_data
FROM 'abfss://container@storageAccount.dfs.core.chinacloudapi.cn/jsonData'
FILEFORMAT = JSON;

外部位置特权继承

外部位置特权适用于指定位置下的所有嵌套目录。

例如，如果有权访问使用 URL abfss://container@storageAccount.dfs.core.chinacloudapi.cn/raw-data 定义的外部位置，则以下命令有效：

COPY INTO landing_table
FROM 'abfss://container@storageAccount.dfs.core.chinacloudapi.cn/raw-data'
FILEFORMAT = PARQUET;

COPY INTO json_table
FROM 'abfss://container@storageAccount.dfs.core.chinacloudapi.cn/raw-data/json'
FILEFORMAT = JSON;

此外部位置权限不提供对指定位置之上或平行目录的任何权限。例如，以下两个命令都无效：

COPY INTO parent_table
FROM 'abfss://container@storageAccount.dfs.core.chinacloudapi.cn'
FILEFORMAT = PARQUET;

COPY INTO sibling_table
FROM 'abfss://container@storageAccount.dfs.core.chinacloudapi.cn/json-data'
FILEFORMAT = JSON;

目标表的三级命名空间

可以使用三级命名空间（<catalog_name>.<schema_name>.<table_name>）将 Unity 目录表作为目标。使用USE CATALOG <catalog_name>和USE SCHEMA <schema_name>命令为当前查询或笔记本设置默认目录和模式。

以下示例使用三级命名空间将数据从卷加载到表中：

COPY INTO quickstart_catalog.quickstart_schema.landing_table
FROM '/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data'
FILEFORMAT = PARQUET;

还可以首先设置默认目录和架构：

USE CATALOG quickstart_catalog;
USE SCHEMA quickstart_schema;

COPY INTO landing_table
FROM '/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data'
FILEFORMAT = PARQUET;

Last updated on 2026-05-08