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

> File 表引擎将数据以某种受支持的文件格式（`TabSeparated`、`Native` 等）保存在文件中。

# File 表引擎

File 表引擎将数据以某种受支持的[文件格式](/zh/reference/formats#formats-overview) (`TabSeparated`、`Native` 等) 保存在文件中。

使用场景：

* 将数据从 ClickHouse 导出到文件。
* 将数据从一种格式转换为另一种格式。
* 通过编辑磁盘上的文件来更新 ClickHouse 中的数据。

<Note>
  该引擎目前在 ClickHouse Cloud 中不可用，请[改用 S3 表函数](/zh/reference/functions/table-functions/s3)。
</Note>

<div id="usage-in-clickhouse-server">
  ## 在 ClickHouse Server 中使用
</div>

```sql theme={null}
File(Format)
```

`Format` 参数用于指定一种可用的文件格式。要执行
`SELECT` 查询，该格式必须支持输入；要执行
`INSERT` 查询，则必须支持输出。可用格式见
[格式](/zh/reference/formats#formats-overview)部分。

ClickHouse 不允许为 `File` 指定文件系统路径。它会使用服务器配置中由 [path](/zh/reference/settings/server-settings/settings) 设置定义的目录。

使用 `File(Format)` 创建表时，会在该目录中创建一个空子目录。当数据写入该表时，数据会写入该子目录中的 `data.Format` 文件。

你也可以在服务器文件系统中手动创建这个子目录和文件，然后使用 [ATTACH](/zh/reference/statements/attach) 将其附加到同名表的元数据，这样就可以查询该文件中的数据。

<Note>
  请谨慎使用此功能，因为 ClickHouse 不会跟踪对此类文件的外部更改。通过 ClickHouse 和在 ClickHouse 外部同时写入时，结果是未定义的。
</Note>

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

**1.** 创建 `file_engine_table` 表：

```sql theme={null}
CREATE TABLE file_engine_table (name String, value UInt32) ENGINE=File(TabSeparated)
```

默认情况下，ClickHouse 会创建文件夹 `/var/lib/clickhouse/data/default/file_engine_table`。

**2.** 手动创建 `/var/lib/clickhouse/data/default/file_engine_table/data.TabSeparated`，内容如下：

```bash theme={null}
$ cat data.TabSeparated
one 1
two 2
```

**3.** 查询数据：

```sql theme={null}
SELECT * FROM file_engine_table
```

```text theme={null}
┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘
```

<div id="usage-in-clickhouse-local">
  ## 在 ClickHouse-local 中的用法
</div>

在 [clickhouse-local](/zh/concepts/features/tools-and-utilities/clickhouse-local) 中，File 表引擎除了接受 `Format` 外，还接受文件路径。默认输入/输出流可以使用数字或便于人类阅读的名称指定，例如 `0` 或 `stdin`、`1` 或 `stdout`。此外，还可以根据额外的引擎参数或文件扩展名 (`gz`、`br` 或 `xz`) 读写压缩文件。

**示例：**

```bash theme={null}
$ echo -e "1,2\n3,4" | clickhouse-local -q "CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin); SELECT a, b FROM table; DROP TABLE table"
```

<div id="details-of-implementation">
  ## 实现细节
</div>

* 可并发执行多个 `SELECT` 查询，但 `INSERT` 查询之间会相互等待。
* 支持通过 `INSERT` 查询创建新文件。
* 如果文件已存在，`INSERT` 会向其中追加新数据。
* 不支持：
  * `ALTER`
  * `SELECT ... SAMPLE`
  * 索引
  * 复制

<div id="partition-by">
  ## PARTITION BY
</div>

`PARTITION BY` — 可选。可以通过按分区键对数据进行分区来创建独立的文件。大多数情况下，你不需要分区键；即使需要，通常也不需要比按月分区更细的粒度。分区不会加快查询速度 (这与 `ORDER BY` 表达式不同) 。切勿使用粒度过细的分区。不要按客户标识符或名称对数据进行分区 (应改为将客户标识符或名称作为 `ORDER BY` 表达式中的第一列) 。

对于按月分区，请使用 `toYYYYMM(date_column)` 表达式，其中 `date_column` 是一个 [Date](/zh/reference/data-types/date) 类型的日期列。这里的分区名称采用 `"YYYYMM"` 格式。

<div id="virtual-columns">
  ## 虚拟列
</div>

* `_path` — 文件路径。类型：`LowCardinality(String)`。
* `_file` — 文件名。类型：`LowCardinality(String)`。
* `_size` — 文件大小 (字节) 。类型：`Nullable(UInt64)`。如果大小未知，则值为 `NULL`。
* `_time` — 文件的最后修改时间。类型：`Nullable(DateTime)`。如果时间未知，则值为 `NULL`。

<div id="settings">
  ## 设置
</div>

* [engine\_file\_empty\_if\_not\_exists](/zh/reference/settings/session-settings#engine_file_empty_if_not_exists) - 允许从不存在的文件中读取空数据。默认禁用。
* [engine\_file\_truncate\_on\_insert](/zh/reference/settings/session-settings#engine_file_truncate_on_insert) - 允许在插入前截断文件。默认禁用。
* [engine\_file\_allow\_create\_multiple\_files](/zh/reference/settings/session-settings#engine_file_allow_create_multiple_files) - 如果 `format` 带有后缀，则允许在每次 insert 时创建新文件。默认禁用。
* [engine\_file\_skip\_empty\_files](/zh/reference/settings/session-settings#engine_file_skip_empty_files) - 允许在读取时跳过空文件。默认禁用。
* [storage\_file\_read\_method](/zh/reference/settings/session-settings#engine_file_empty_if_not_exists) - 从存储文件读取数据的方式，可选值为：`read`、`pread`、`mmap`。`mmap` 方式不适用于 clickhouse-server (仅适用于 clickhouse-local) 。默认值：clickhouse-server 为 `pread`，clickhouse-local 为 `mmap`。