使用内部 Volume

内部 Volume（Internal Volume）是系统提供的默认文件存储区域，用于临时存放待处理或加载的数据文件。

对于没有云存储的用户，可以直接上传文件到内部 Volume 作为数据文件的主要存储区域，系统提供完全托管的存储服务。
而已使用云对象存储的用户，则可以选择使用外部 Volume（External Volume），通过直接挂载云存储路径进行访问，无需额外的数据迁移和复制。

系统目前支持三种类型的内部 Volume：User Volume 、 Table Volume和命名Volume。

使用User Volume

User Volume 是用户专属的个人存储空间，类似于操作系统中用户的默认工作目录，在Lakehouse 中这个目录不可删除。空间用户默认对 User Volume 具备读写权限。

用户对 USER VOLUME 操作
SHOW USER VOLUME DIRECTORY
SELECT FROM VOLUME
PUT
GET
LIST USER VOLUME
REMOVE

查看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 
tmp/taxi_zone_lookup_02.csv              oss://lakehouse-hz/86/workspaces/ql_ws_8133192700078175627/internal_volume/user_4371011337311368544/tmp/taxi_zone_lookup_02.csv              12331  2024-05-28 23:34:24

上传与下载与删除文件


--上传文件至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下文件


--通过SQL查询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    


--通过SQL查询User Volume指定路径下所有文件
SELECT * FROM USER VOLUME using csv subdirectory '/tmp/';

使用get_presigned_url函数, 获取Volume下文件在对象存储的待临时签名的真实访问路径。


--获取presign url, 获取oss内网url
SELECT get_presigned_url(USER VOLUME , 'images/image.png' , 60) as url;

--获取presign url,获取对外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>	SELECT
SELECT FROM VOLUME <table_name>	SELECT
PUT	INSERT,UPDATE,DELETE
GET	SELECT
LIST	SCHEMA READ
REMOVE	INSERT, UPDATE ,DELETE

以下通过示例说明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下文件数据。


--查询
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')
--删除volume中的文件，节省存储
PURGE=TRUE;

查询目标表，验证导入结果。


--查看导入结果
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 '/'

使用命名Volume

命名 Volume 是用户显式创建，创建完成后储在 Lakehouse管理的内部存储中，无需额外云存储配置。提供比自动生成的用户级（User Volume）和表级（Table Volume）更精细的控制能力。

语法说明

创建命名Volume


CREATE VOLUME [ IF NOT EXISTS ] <volume_name>
    DIRECTORY = (
        enable =  true,    
        auto_refresh = true
    )
    RECURSIVE = true          -- 是否递归扫描子目录（默认false）

删除Volume


DROP VOLUME [ IF EXISTS ] <volume_name>

使用具体案例

上传和下载数据


--创建volume
CREATE  VOLUME my_volume
    DIRECTORY = (
        enable=true,
        auto_refresh=true
    )
    RECURSIVE=true;
SHOW VOLUME DIRECTORY my_volume;

COPY INTO VOLUME my_volume  SUBDIRECTORY 'dau_unload/'
FROM TABLE public.students01
file_format = (
    type= CSV
    writebom=true
);
SHOW VOLUME DIRECTORY my_volume;
--本地上传下载测试
GET VOLUME my_volume FILE 'dau_unload/part00001.csv' TO '/tmp';
+---------------+--------------------+-------------+-------------+---------+
|    source     |       target       | source_size | target_size | status  |
+---------------+--------------------+-------------+-------------+---------+
| part00001.csv | /tmp/part00001.csv | 1472        | 1472        | SUCCEED |
+---------------+--------------------+-------------+-------------+---------+

 PUT '/tmp/part00001.csv' to volume my_volume file 'my.csv';
+--------------------+--------+-------------+-------------+---------+
|       source       | target | source_size | target_size | status  |
+--------------------+--------+-------------+-------------+---------+
| /tmp/part00001.csv | my.csv | 1472        | 1472        | SUCCEED |
+--------------------+--------+-------------+-------------+---------+

数据操作协议

协议类型	地址格式	典型场景
User Volume	volume:user://~/filename	用户私有资源
Table Volume	volume:table://table_name/file	表关联ETL文件
Named Volume	volume://volume_name/path	跨团队共享资源

User Volume 格式地址:volume:user://~/upper.jar
- user 表示使用 User Volume 协议。
- ~ 表示当前用户，为固定值。
- upper.jar 表示目标文件名。
Table Volume 格式地址volume:table://table_name/upper.jar
- table 表示使用 Table Volume 协议。
- table_name 表示表名，需根据实际情况填写。
- upper.jar 表示目标文件名。
Volume 格式地址volume://volume_name/upper.jar
- volume_name 创建的vollume名称
- upper.jar 表示目标文件名。

联系我们