> ## 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.

> Provides access to the file system to list files and return their metadata and contents.

# filesystem Table Function

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>;
};

Recursively iterates a directory and returns a table with file metadata (paths, sizes, types, permissions, modification times) and, optionally, file contents.

In `clickhouse-server` mode, the path must be within the [user\_files\_path](/reference/settings/server-settings/settings#user_files_path) directory. Symlinks inside `user_files_path` that point outside of it are followed, but only entries whose path (through the symlink) starts with `user_files_path` are returned.

In `clickhouse-local` mode, there are no path restrictions.

<h2 id="syntax">
  Syntax
</h2>

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

<h2 id="arguments">
  Arguments
</h2>

| Parameter | Description                                                                                                                                                                                   |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`    | The directory to list. Can be an absolute path (must be inside `user_files_path` in server mode) or a path relative to `user_files_path`. If empty or omitted, defaults to `user_files_path`. |

<h2 id="returned_columns">
  Returned columns
</h2>

| Column              | Type                       | Description                                                                                                                                                                                            |
| ------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path`              | `String`                   | Directory containing the entry (does not include the file/directory name itself).                                                                                                                      |
| `name`              | `String`                   | File or directory name (the last component of the path).                                                                                                                                               |
| `file`              | `String` (ALIAS of `name`) | Alias for the `name` column.                                                                                                                                                                           |
| `type`              | `Enum8`                    | File type: `'none'`, `'not_found'`, `'regular'`, `'directory'`, `'symlink'`, `'block'`, `'character'`, `'fifo'`, `'socket'`, `'unknown'`.                                                              |
| `size`              | `Nullable(UInt64)`         | File size in bytes (for regular files). `NULL` for non-regular files (directories, symlinks, etc.) and on error.                                                                                       |
| `depth`             | `UInt16`                   | Recursion depth. `0` for the queried directory itself and its immediate children, `1` for entries one level deeper, and so on.                                                                         |
| `modification_time` | `Nullable(DateTime64(6))`  | Last modification time with microsecond precision. `NULL` on error.                                                                                                                                    |
| `is_symlink`        | `Bool`                     | Whether the entry is a symbolic link.                                                                                                                                                                  |
| `content`           | `Nullable(String)`         | File contents (for regular files). `NULL` for non-regular files (directories, symlinks, etc.). Read errors raise an exception. Reading this column triggers actual file I/O, so omit it if not needed. |
| `owner_read`        | `Bool`                     | Owner has read permission.                                                                                                                                                                             |
| `owner_write`       | `Bool`                     | Owner has write permission.                                                                                                                                                                            |
| `owner_exec`        | `Bool`                     | Owner has execute permission.                                                                                                                                                                          |
| `group_read`        | `Bool`                     | Group has read permission.                                                                                                                                                                             |
| `group_write`       | `Bool`                     | Group has write permission.                                                                                                                                                                            |
| `group_exec`        | `Bool`                     | Group has execute permission.                                                                                                                                                                          |
| `others_read`       | `Bool`                     | Others have read permission.                                                                                                                                                                           |
| `others_write`      | `Bool`                     | Others have write permission.                                                                                                                                                                          |
| `others_exec`       | `Bool`                     | Others have execute permission.                                                                                                                                                                        |
| `set_gid`           | `Bool`                     | Set-GID bit.                                                                                                                                                                                           |
| `set_uid`           | `Bool`                     | Set-UID bit.                                                                                                                                                                                           |
| `sticky_bit`        | `Bool`                     | Sticky bit.                                                                                                                                                                                            |

Only columns actually used in the query are computed, so selecting a subset of columns (especially omitting `content`) is efficient.

<h2 id="examples">
  Examples
</h2>

<h3 id="list-files">
  List files in user\_files
</h3>

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

<h3 id="find-large-files">
  Find large files
</h3>

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

<h3 id="read-contents">
  Read file contents
</h3>

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

<h3 id="list-immediate">
  List only immediate children
</h3>

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