使用内部 Volume
内部 Volume（Internal Volume）是 Lakehouse 提供的默认文件存储区域，用于临时存放待处理或待加载的数据文件。
- 对于没有云存储的用户，可以直接上传文件到内部 Volume 作为数据文件的主要存储区域，系统提供完全托管的存储服务
- 而已使用云对象存储的用户，则可以选择使用外部 Volume（External Volume），通过直接挂载云存储路径进行访问，无需额外的数据迁移和复制
系统提供三种类型的内部 Volume：User Volume、Table Volume 和 Named Volume。其中 User Volume 和 Table Volume 由系统自动创建，Named Volume 需要用户显式创建，用户自行管理其生命周期。
使用 User Volume
User Volume 是用户专属的个人存储空间，类似于操作系统中用户的默认工作目录。在 Lakehouse 中，每个用户默认拥有 User Volume 的读写权限。
User Volume 操作
| 操作 | 命令 |
|---|
| 查看文件列表 | SHOW USER VOLUME DIRECTORY
SHOW USER VOLUME DIRECTORY |
| SQL 查询文件 | SELECT FROM USER VOLUME
SELECT FROM USER VOLUME |
| 上传文件 | PUT ... TO USER VOLUME
PUT ... TO USER VOLUME |
| 下载文件 | GET USER VOLUME FILE ... TO ...
GET USER VOLUME FILE ... TO ... |
| 删除文件 | REMOVE USER VOLUME FILE ...
REMOVE USER VOLUME FILE ... |
查看 User Volume 下文件
-- 查看 User Volume 根目录下的文件
SHOW USER VOLUME DIRECTORY;
relative_path url size last_modified_time
---------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------ ------ -------------------
images/image-2024-05-22-11-25-23-519.png oss://lakehouse-hz/86/workspaces/ql_ws_8133192700078175627/internal_volume/user_4371011337311368544/images/image-2024-05-22-11-25-23-519.png 200494 2024-05-28 23:30:27
images/image.png oss://lakehouse-hz/86/workspaces/ql_ws_8133192700078175627/internal_volume/user_4371011337311368544/images/image.png 513894 2024-05-28 23:30:27
taxi_zone_lookup.csv oss://lakehouse-hz/86/workspaces/ql_ws_8133192700078175627/internal_volume/user_4371011337311368544/taxi_zone_lookup.csv 12331 2024-05-28 23:04:54
tmp/taxi_zone_lookup.csv oss://lakehouse-hz/86/workspaces/ql_ws_8133192700078175627/internal_volume/user_4371011337311368544/tmp/taxi_zone_lookup.csv 12331 2024-05-28 23:05:54
上传、下载与删除文件
-- 上传文件至 User Volume 根目录
PUT '/Users/Downloads/taxi_zone_lookup.csv' TO USER VOLUME;
-- 上传文件并保存到 User Volume 指定路径
PUT '/Users/Downloads/taxi_zone_lookup.csv' TO USER VOLUME FILE 'tmp/taxi_zone_lookup_02.csv';
-- 通过通配符上传多个文件到 Volume 子目录
PUT '/Users/Downloads/images/*' TO USER VOLUME SUBDIRECTORY 'images/';
-- 从 User Volume 下载文件
GET USER VOLUME FILE 'images/image-2024-05-22-11-25-23-519.png' TO '/Users/Downloads/output/';
-- 删除 User Volume 下指定文件
REMOVE USER VOLUME FILE 'images/image-2024-05-22-11-25-23-519.png';
-- 删除 User Volume 下指定路径下所有文件
REMOVE USER VOLUME SUBDIRECTORY '/';
通过 SQL 查询 User Volume 下文件
-- 查询 User Volume 下指定文件
SELECT * FROM USER VOLUME
USING CSV
OPTIONS(
'header' = 'true'
)
FILES ('taxi_zone_lookup.csv')
LIMIT 5;
LocationID Borough Zone service_zone
---------- ------------- ----------------------- ------------
1 EWR Newark Airport EWR
2 Queens Jamaica Bay Boro Zone
3 Bronx Allerton/Pelham Gardens Boro Zone
4 Manhattan Alphabet City Yellow Zone
5 Staten Island Arden Heights Boro Zone
-- 查询 User Volume 指定路径下所有文件
SELECT * FROM USER VOLUME USING CSV SUBDIRECTORY '/tmp/';
获取文件临时访问链接
使用
get_presigned_url
get_presigned_url
函数，获取 Volume 下文件在对象存储的临时签名访问路径：
-- 获取 presign url（内网）
SELECT get_presigned_url(USER VOLUME, 'images/image.png', 60) as url;
-- 获取 presign url（外网）
SET cz.sql.function.get.presigned.url.force.external = true;
SELECT get_presigned_url(USER VOLUME, 'images/image.png', 60) as url;
使用 Table Volume
每个 Lakehouse 表默认关联一个存储空间，我们称之为 Table Volume。用户对指定表的 Table Volume 进行操作时需要具备对应的表权限：
| Table Volume 操作 | 对应 Table 权限需求 |
|---|
SHOW TABLE VOLUME DIRECTORY <table_name>
SHOW TABLE VOLUME DIRECTORY <table_name> | SELECT |
SELECT FROM VOLUME <table_name>
SELECT FROM VOLUME <table_name> | SELECT |
PUT ... TO TABLE VOLUME <table_name>
PUT ... TO TABLE VOLUME <table_name> | INSERT, UPDATE, DELETE |
GET TABLE VOLUME <table_name> FILE ...
GET TABLE VOLUME <table_name> FILE ... | SELECT |
SHOW TABLE VOLUME DIRECTORY
SHOW TABLE VOLUME DIRECTORY | SCHEMA READ |
REMOVE TABLE VOLUME <table_name> FILE ...
REMOVE TABLE VOLUME <table_name> FILE ... | INSERT, UPDATE, DELETE |
Table Volume 操作示例
-- 创建表（自动创建关联的 Table Volume）
CREATE TABLE t_copy_from_volume(id INT, name STRING);
-- 查看指定表的 Table Volume
SHOW TABLE VOLUME DIRECTORY t_copy_from_volume;
上传文件至目标表的 Table Volume，要求访问用户具有目标表的写入权限：
-- 上传文件至 Table Volume，不指定存储路径默认保存在根路径下
PUT '/Users/Downloads/data.csv' TO TABLE VOLUME t_copy_from_volume FILE 'data.csv';
source target source_size target_size status
-------------------------------- -------- ----------- ----------- -------
/Users/Downloads/data.csv data.csv 34 34 SUCCEED
使用 SQL 探查上传至 Table Volume 下文件数据：
-- 查询 Table Volume 中的文件
SELECT * FROM TABLE VOLUME t_copy_from_volume
USING CSV
OPTIONS(
'header' = 'true',
'lineSep' = '\n'
);
id name
-- -----
1 hello
2 world
3 !
使用 COPY INTO 命令导入文件数据到目标表：
COPY INTO t_copy_from_volume FROM TABLE VOLUME t_copy_from_volume(id INT, name STRING)
USING CSV
OPTIONS(
'header' = 'true',
'lineSep' = '\n'
)
FILES ('data.csv')
PURGE = TRUE; -- 导入后删除 Volume 中的文件，节省存储
查询目标表，验证导入结果：
-- 查看导入结果
SELECT * FROM t_copy_from_volume;
id name
-- -----
1 hello
2 world
3 !
删除 Table Volume 下文件：
-- 删除 Table Volume 下指定文件
REMOVE TABLE VOLUME t_copy_from_volume FILE 'data.csv';
-- 删除 Table Volume 下指定路径下所有文件
REMOVE TABLE VOLUME t_copy_from_volume SUBDIRECTORY '/';
数据操作协议
| 协议类型 | 地址格式 | 典型场景 |
|---|
| User Volume | volume:user://~/filename
volume:user://~/filename | 用户私有资源 |
| Table Volume | volume:table://table_name/file
volume:table://table_name/file | 表关联 ETL 文件 |
User Volume 格式地址
volume:user://~/upper.jar
volume:user://~/upper.jar
user
user
：表示使用 User Volume 协议~
~
：表示当前用户，为固定值upper.jar
upper.jar
：目标文件名
Table Volume 格式地址
volume:table://table_name/upper.jar
volume:table://table_name/upper.jar
table
table
：表示使用 Table Volume 协议table_name
table_name
：表名，需根据实际情况填写upper.jar
upper.jar
：目标文件名
相关文档
