跳转到主要内容
File 表引擎将数据以某种受支持的文件格式 (TabSeparated、Native 等) 保存在文件中。 使用场景：
  • 将数据从 ClickHouse 导出到文件。
  • 将数据从一种格式转换为另一种格式。
  • 通过编辑磁盘上的文件来更新 ClickHouse 中的数据。
该引擎目前在 ClickHouse Cloud 中不可用，请改用 S3 表函数。

​
在 ClickHouse Server 中使用

File(Format)
Format 参数用于指定一种可用的文件格式。要执行 SELECT 查询，该格式必须支持输入；要执行 INSERT 查询，则必须支持输出。可用格式见 格式部分。 ClickHouse 不允许为 File 指定文件系统路径。它会使用服务器配置中由 path 设置定义的目录。 使用 File(Format) 创建表时，会在该目录中创建一个空子目录。当数据写入该表时，数据会写入该子目录中的 data.Format 文件。 你也可以在服务器文件系统中手动创建这个子目录和文件，然后使用 ATTACH 将其附加到同名表的元数据，这样就可以查询该文件中的数据。
请谨慎使用此功能，因为 ClickHouse 不会跟踪对此类文件的外部更改。通过 ClickHouse 和在 ClickHouse 外部同时写入时，结果是未定义的。

​
示例

1. 创建 file_engine_table 表： 
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，内容如下： 
$ cat data.TabSeparated
one 1
two 2
3. 查询数据： 
SELECT * FROM file_engine_table

┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘

​
在 ClickHouse-local 中的用法

在 clickhouse-local 中，File 表引擎除了接受 Format 外，还接受文件路径。默认输入/输出流可以使用数字或便于人类阅读的名称指定，例如 0 或 stdin、1 或 stdout。此外，还可以根据额外的引擎参数或文件扩展名 (gz、br 或 xz) 读写压缩文件。 示例： 
$ 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"

​
实现细节

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

​
PARTITION BY

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

​
虚拟列

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

​
设置

最后修改于 2026年6月10日