外部 Volume（External Volume）
外部 Volume 用于挂载外部对象存储（阿里云 OSS、腾讯云 COS、亚马逊 S3）。通过 External Volume，Lakehouse 能够直接访问和管理存储在外部云存储中的文件，数据不迁入 Lakehouse。
什么是 External Volume
External Volume 是 Lakehouse 中的对象，它指向外部对象存储中的特定路径，通过
CREATE EXTERNAL VOLUME
CREATE EXTERNAL VOLUME
创建，挂载外部对象存储（OSS/COS/S3）。
⚠️ 注意：Named Volume（通过
CREATE VOLUME
CREATE VOLUME
创建）属于
内部 Volume，数据存储在 Lakehouse 内部，与 External Volume 是不同类型。详见
Named Volume。
通过 External Volume，你可以：
- 直接查询对象存储中的 CSV/JSON/Parquet 文件
- 将对象存储中的数据导入到 Lakehouse 表中
- 将 Lakehouse 表数据导出到对象存储
- 统一管理外部存储中的文件
核心特点：
- 数据存储在外部云存储中，Lakehouse 仅存储路径元信息
- 支持阿里云 OSS、腾讯云 COS、亚马逊 S3
创建 External Volume
前置条件
创建 External Volume（挂载外部存储）之前，需要先创建 Storage Connection 存储连接：
-- 创建阿里云 OSS 存储连接
CREATE STORAGE CONNECTION IF NOT EXISTS oss_conn
TYPE oss
ENDPOINT = 'oss-cn-hangzhou.aliyuncs.com'
ACCESS_ID = 'your_access_key_id'
ACCESS_KEY = 'your_access_key_secret';
创建 External Volume（挂载外部存储）
CREATE EXTERNAL VOLUME [IF NOT EXISTS] [schema_name.]<volume_name>
LOCATION '<storage_url>'
USING CONNECTION <connection_name>
DIRECTORY = (
enable = true,
auto_refresh = true
)
RECURSIVE = true;
参数说明：
| 参数 | 说明 |
|---|
volume_name
volume_name | Volume 名称，在同一 schema 下唯一 |
LOCATION
LOCATION | 对象存储路径，格式如 oss://bucket_name/path/
oss://bucket_name/path/ |
USING CONNECTION
USING CONNECTION | 引用的 Storage Connection 名称 |
DIRECTORY.enable
DIRECTORY.enable | 是否启用目录功能 |
DIRECTORY.auto_refresh
DIRECTORY.auto_refresh | 是否自动刷新文件元数据 |
RECURSIVE
RECURSIVE | 是否递归扫描子目录 |
示例：
-- 创建 External Volume 挂载 OSS bucket
CREATE EXTERNAL VOLUME my_oss_vol
LOCATION 'oss://mcp-data-hangzhou/test/'
USING CONNECTION oss_conn
DIRECTORY = (enable = true, auto_refresh = true)
RECURSIVE = true;
创建 Named Volume
查看 External Volume
查看 Volume 详情
DESC VOLUME my_oss_vol;
+------------------------+--------------------------------+
| info_name | info_value |
+------------------------+--------------------------------+
| name | my_oss_vol |
| creator | qiliang |
| created_time | 2026-05-20 00:23:49.074 |
| last_modified_time | 2026-05-20 00:23:49.074 |
| external | true |
| url | oss://mcp-data-hangzhou/test/ |
| connection_name | quick_start.oss_conn |
| recursive | true |
| directory_enabled | true |
| directory_auto_refresh | true |
+------------------------+--------------------------------+
列出 Volume 中的文件
SHOW VOLUME DIRECTORY my_oss_vol;
+---------------------------------+--------------------------------------------------------------+----------+---------------------+
| relative_path | url | size | last_modified_time |
+---------------------------------+--------------------------------------------------------------+----------+---------------------+
| green_tripdata_2025-03.parquet | oss://mcp-data-hangzhou/test/green_tripdata_2025-03.parquet | 1253510 | 2025-09-03 17:33:05 |
| taxi_data.parquet | oss://mcp-data-hangzhou/test/taxi_data.parquet | 69964745 | 2025-06-07 03:42:52 |
+---------------------------------+--------------------------------------------------------------+----------+---------------------+
查询 External Volume 中的文件
-- 查询 Parquet 文件
SELECT * FROM VOLUME my_oss_vol
USING PARQUET
FILES ('green_tripdata_2025-03.parquet')
LIMIT 5;
-- 查询 CSV 文件
SELECT * FROM VOLUME my_oss_vol
USING CSV
OPTIONS ('header' = 'true')
FILES ('data.csv')
LIMIT 5;
导入 External Volume 数据到表
-- 创建目标表
CREATE TABLE green_trip (
VendorID INT,
lpep_pickup_datetime TIMESTAMP,
trip_distance DOUBLE,
fare_amount DOUBLE,
total_amount DOUBLE
);
-- 从 Volume 导入数据
COPY INTO green_trip FROM VOLUME my_oss_vol
(VendorID INT, lpep_pickup_datetime TIMESTAMP, trip_distance DOUBLE, fare_amount DOUBLE, total_amount DOUBLE)
USING PARQUET
FILES ('green_tripdata_2025-03.parquet');
导出数据到 External Volume
-- 导出表数据到 External Volume
COPY INTO VOLUME my_oss_vol
SUBDIRECTORY 'export/'
FROM green_trip
FILE_FORMAT = (TYPE = CSV HEADER = true);
Named Volume 同样支持
COPY INTO VOLUME
COPY INTO VOLUME
导出，语法相同，将
my_oss_vol
my_oss_vol
替换为 Named Volume 名称即可。
刷新 Volume 文件元数据
当外部存储中的文件发生变化时，可以手动刷新 Volume 的文件元数据：
ALTER VOLUME my_oss_vol REFRESH;
⚠️ 注意：仅 External Volume（挂载外部存储）支持 REFRESH 操作，Named Volume（内部存储）不需要刷新。
删除 External Volume
DROP VOLUME [IF EXISTS] my_oss_vol;
⚠️ 注意：删除 External Volume 仅删除 Lakehouse 中的元数据引用，不会删除外部对象存储或内部存储中的实际文件。如需删除文件，请先使用
REMOVE
REMOVE
命令。
权限要求
| 权限 | 说明 |
|---|
| READ METADATA | 查看 Volume 对象元信息 |
| READ VOLUME | 读取 Volume 下文件及目录 |
| WRITE VOLUME | 写入数据到 Volume |
| ALTER VOLUME | 修改 Volume 属性（如 REFRESH） |
注意事项
- External Volume（外部存储）仅存储路径元信息，实际数据存储在外部云存储中
- External Volume（外部存储）的存储费用按云厂商标准收取，Lakehouse 侧无额外存储费用
- Named Volume（内部存储）的存储费用按 Lakehouse 存储标准收取
- 不支持跨云厂商创建：阿里云实例只能创建 OSS Connection，腾讯云实例只能创建 COS Connection
- 删除 External Volume 不会删除外部存储或内部存储中的实际文件
相关文档
