filesystem 表函数

用于访问文件系统，列出文件并返回其元数据和内容。

递归遍历目录，并返回一个包含文件元数据 (路径、大小、类型、权限、修改时间) 以及可选文件内容的表。

在 clickhouse-server 模式下，路径必须位于 user_files_path 目录内。对于 user_files_path 内部指向外部的符号链接，也会继续跟随，但只会返回其路径 (经由该符号链接) 以 user_files_path 开头的条目。

在 clickhouse-local 模式下，路径不受限制。

​

语法

filesystem([path])

​

参数

参数	描述
path	要列出的目录。可以是绝对路径 (在服务器模式下必须位于 user_files_path 内) ，也可以是相对于 user_files_path 的路径。如果为空或省略，则默认为 user_files_path。

​

返回的列

列	类型	描述
path	String	包含该条目的目录 (不包括文件/目录名本身) 。
name	String	文件或目录名 (路径的最后一个组件) 。
file	String (ALIAS of name)	name 列的别名。
type	Enum8	文件类型：'none'、'not_found'、'regular'、'directory'、'symlink'、'block'、'character'、'fifo'、'socket'、'unknown'。
size	Nullable(UInt64)	文件大小 (以字节为单位，仅适用于普通文件) 。对于非普通文件 (目录、符号链接等) 以及发生错误时，为 NULL。
depth	UInt16	递归深度。被查询目录本身及其直接子项为 0，更深一层的条目为 1，以此类推。
modification_time	Nullable(DateTime64(6))	最后修改时间，精度为微秒。发生错误时为 NULL。
is_symlink	Bool	该条目是否为符号链接。
content	Nullable(String)	文件内容 (仅适用于普通文件) 。对于非普通文件 (目录、符号链接等) ，为 NULL。读取错误会引发异常。读取此列会触发实际的文件 I/O，因此如果不需要，建议省略。
owner_read	Bool	所有者具有读取权限。
owner_write	Bool	所有者具有写入权限。
owner_exec	Bool	所有者具有执行权限。
group_read	Bool	所属组具有读取权限。
group_write	Bool	所属组具有写入权限。
group_exec	Bool	所属组具有执行权限。
others_read	Bool	其他用户具有读取权限。
others_write	Bool	其他用户具有写入权限。
others_exec	Bool	其他用户具有执行权限。
set_gid	Bool	Set-GID 位。
set_uid	Bool	Set-UID 位。
sticky_bit	Bool	粘滞位。

只会计算查询中实际使用到的列，因此仅选择部分列 (尤其是不包含 content) 会更高效。

​

示例

​

列出 user_files 中的文件

SELECT name, type, size, depth
FROM filesystem()
ORDER BY name;

​

查找大文件

SELECT path, name, size
FROM filesystem()
WHERE type = 'regular' AND size > 1000000
ORDER BY size DESC;

​

读取文件内容

SELECT name, content
FROM filesystem('my_directory')
WHERE name LIKE '%.csv';

​

仅列出一级子项

SELECT name, type
FROM filesystem('my_directory')
WHERE depth = 0;