LIST 命令

列出 Lakehouse 内部或外部 Volume 中存储的文件。该命令可在 Studio 和 Lakehouse 客户端中运行。

语法

LIST { VOLUME volume_name | TABLE VOLUME table_name | USER VOLUME } [SUBDIRECTORY 'subdir'] [REGEXP = 'pattern'];

参数说明

参数	必填	说明
`VOLUME volume_name` VOLUME volume_name	与其他目标参数三选一	列出指定外部 Volume 中的文件
`TABLE VOLUME table_name` TABLE VOLUME table_name	与其他目标参数三选一	列出指定表的 Volume 空间下的文件
`USER VOLUME` USER VOLUME	与其他目标参数三选一	列出当前用户的个人 Volume 空间下的文件
`SUBDIRECTORY 'subdir'` SUBDIRECTORY 'subdir'	否	指定要列出内容的子目录，缩小结果范围
`REGEXP = 'pattern'` REGEXP = 'pattern'	否	按正则表达式过滤文件名，精确筛选符合命名规则的文件

返回列说明

列名	说明
`relative_path` relative_path	文件在 Volume 中的相对路径
`url` url	文件的访问 URL（外部 Volume 可能为空）
`size` size	文件大小（字节）
`last_modified_time` last_modified_time	文件最后修改时间（UTC）

使用示例

列出当前用户 Volume 中的所有文件：

LIST USER VOLUME;

+----------------------------------+-----+--------+-------------------------+ | relative_path | url | size | last_modified_time | +----------------------------------+-----+--------+-------------------------+ | test_export/part00001.csv | | 61 | 2026-05-09 06:34:53.000 | | university_info.csv | | 414724 | 2026-05-17 13:19:19.000 | +----------------------------------+-----+--------+-------------------------+

列出外部 Volume
```
parquet_files
```
parquet_files
中
```
t_search_log
```
t_search_log
子目录下的所有文件：

LIST VOLUME parquet_files SUBDIRECTORY 't_search_log';

列出外部 Volume
```
foodimages
```
foodimages
中文件名包含数字
```
1
```
1
的文件：

LIST VOLUME foodimages REGEXP = '.*1.*';

列出外部 Volume
```
parquet_file
```
parquet_file
中
```
t_search_log
```
t_search_log
子目录下以
```
c000
```
c000
结尾的文件：

LIST VOLUME parquet_file SUBDIRECTORY 't_search_log' REGEXP = '.*c000';

列出指定表的 Volume 空间下的文件：

LIST TABLE VOLUME my_schema.my_table;

注意事项

执行
```
LIST
```
LIST
命令需要对应 Volume 的
```
READ
```
READ
权限。
```
SUBDIRECTORY
```
SUBDIRECTORY
和
```
REGEXP
```
REGEXP
可以组合使用，先按子目录缩小范围，再按正则过滤文件名。
```
LIST
```
LIST
命令仅列出文件，不会修改 Volume 中的任何内容。
若需查看当前工作空间中已创建的 Volume 对象列表（而非 Volume 内的文件），请使用
```
SHOW VOLUMES
```
SHOW VOLUMES
命令。

联系我们