> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# filesystem 表函数

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

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

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

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

<div id="syntax">
  ## 语法
</div>

```sql theme={null}
filesystem([path])
```

<div id="arguments">
  ## 参数
</div>

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

<div id="returned_columns">
  ## 返回的列
</div>

| 列                   | 类型                         | 描述                                                                                                                         |
| ------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `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`) 会更高效。

<div id="examples">
  ## 示例
</div>

<div id="list-files">
  ### 列出 user\_files 中的文件
</div>

```sql theme={null}
SELECT name, type, size, depth
FROM filesystem()
ORDER BY name;
```

<div id="find-large-files">
  ### 查找大文件
</div>

```sql theme={null}
SELECT path, name, size
FROM filesystem()
WHERE type = 'regular' AND size > 1000000
ORDER BY size DESC;
```

<div id="read-contents">
  ### 读取文件内容
</div>

```sql theme={null}
SELECT name, content
FROM filesystem('my_directory')
WHERE name LIKE '%.csv';
```

<div id="list-immediate">
  ### 仅列出一级子项
</div>

```sql theme={null}
SELECT name, type
FROM filesystem('my_directory')
WHERE depth = 0;
```