Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

File 表引擎

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

使用场景：

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

在 ClickHouse Server 中使用

File(Format)

Format 参数用于指定一种可用的文件格式。要执行 SELECT 查询，该格式必须支持输入；要执行 INSERT 查询，则必须支持输出。可用格式见 格式部分。

ClickHouse 不允许为 File 指定文件系统路径。它会使用服务器配置中由 path 设置定义的目录。

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

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

示例

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 会向其中追加新数据，但仅限于支持追加的格式。不支持追加的格式 (如 Avro、Arrow、JSON、Npy、ORC 和 Parquet) 会拒绝向非空文件执行 INSERT，并报出 CANNOT_APPEND_TO_FILE。对于普通文件路径，请改用下方列出的 engine_file_truncate_on_insert 或 engine_file_allow_create_multiple_files 设置；两者均不适用于通过文件描述符写入的情况，因为描述符由调用方管理。
  • 不支持：
    • 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。

设置

Navigation