-- 外部函数引用 Named Volume 中的 JAR 包
CREATE EXTERNAL FUNCTION upper_udf(s STRING) RETURNS STRING
AS 'com.example.UpperUDF'
USING CONNECTION my_api_conn
USING FILE 'volume://fc_volume/udfs/upper.jar';
User Volume
volume:user://~/{path_to_file}
user
user
：固定关键字，表示 User Volume 协议
~
~
：固定值，代表当前登录用户
path_to_file
path_to_file
：文件在 User Volume 中的相对路径
-- 外部函数引用 User Volume 中的代码包
CREATE EXTERNAL FUNCTION sentiment(s STRING) RETURNS STRING
AS 'com.example.Sentiment'
USING CONNECTION my_api_conn
USING ARCHIVE 'volume:user://~/sentiment.zip';
# Zettapark SDK 上传文件到 User Volume
session.file.put("local/data.csv", "volume:user://~/csv/")
# 从 User Volume 下载文件
session.file.get("volume:user://~/png/photo.png", "tmp/")
-- 外部函数引用 Table Volume 中的代码包
CREATE EXTERNAL FUNCTION process(s STRING) RETURNS STRING
AS 'com.example.Process'
USING CONNECTION my_api_conn
USING FILE 'volume:table://my_schema.my_table/upper.jar';
SQL 关键字语法 vs 文件协议
这两套语法作用不同，不要混用：
用途
语法形式
示例
SQL 语句中操作 Volume 文件
关键字语法
FROM USER VOLUME
FROM USER VOLUME
、
FROM VOLUME vol_name
FROM VOLUME vol_name
字符串参数中引用 Volume 文件路径
文件协议
'volume:user://~/file.jar'
'volume:user://~/file.jar'
关键字语法用于
COPY INTO
COPY INTO
、
SELECT FROM VOLUME
SELECT FROM VOLUME
、
PUT
PUT
、
GET
GET
、
LIST
LIST
等 SQL 命令；文件协议用于需要传入字符串路径的场景（函数定义、SDK 调用、配置参数）。
快速示例
上传文件并查询
-- 上传本地 CSV 文件到 User Volume
PUT '/Users/Downloads/taxi_zone_lookup.csv' TO USER VOLUME;
-- 查看已上传的文件
SHOW USER VOLUME DIRECTORY;
-- 结果：
-- +----------------------+-----+------+----------------------------+
-- | relative_path | url | size | last_modified_time |
-- +----------------------+-----+------+----------------------------+
-- | taxi_zone_lookup.csv | | 12331| 2026-05-21T10:00:00.000Z |
-- +----------------------+-----+------+----------------------------+
-- 直接查询文件内容（无需导入到表）
SELECT * FROM USER VOLUME
USING CSV
OPTIONS ('header' = 'true')
FILES ('taxi_zone_lookup.csv')
LIMIT 3;
-- 结果：
-- +------------+-------------+-----------------------+--------------+
-- | LocationID | Borough | Zone | service_zone |
-- +------------+-------------+-----------------------+--------------+
-- | 1 | EWR | Newark Airport | EWR |
-- | 2 | Queens | Jamaica Bay | Boro Zone |
-- | 3 | Bronx | Allerton/Pelham Gardens| Boro Zone |
-- +------------+-------------+-----------------------+--------------+
导入文件到表
-- 创建目标表
CREATE TABLE IF NOT EXISTS taxi_zones (
LocationID INT,
Borough STRING,
Zone STRING,
service_zone STRING
);
-- 从 User Volume 导入数据
COPY INTO taxi_zones
FROM USER VOLUME
USING CSV
OPTIONS ('header' = 'true')
FILES ('taxi_zone_lookup.csv');
-- 验证导入结果
SELECT COUNT(*) AS cnt FROM taxi_zones;
-- 结果：
-- +-----+
-- | cnt |
-- +-----+
-- | 265 |
-- +-----+
文件查询与访问函数
除了
COPY INTO
COPY INTO
和
SELECT FROM VOLUME
SELECT FROM VOLUME
，Lakehouse 还提供以下函数和命令操作 Volume 中的文件：
LIST — 列出文件
列出 Volume 中的文件，支持子目录过滤和正则匹配。与
SHOW VOLUME DIRECTORY
SHOW VOLUME DIRECTORY
相比，
LIST
LIST
支持正则过滤，更适合脚本化处理。
-- 列出 User Volume 中所有文件
LIST USER VOLUME;
-- 列出外部 Volume 中指定子目录下的 Parquet 文件
LIST VOLUME my_oss_volume SUBDIRECTORY 'orders/2024/' REGEXP = '.*\.parquet';
-- 列出 Table Volume 中的文件
LIST TABLE VOLUME my_table;
