输入和输出数据格式

ClickHouse 中支持的输入和输出数据格式概览

ClickHouse 支持大多数常见的文本和二进制数据格式，因此可以轻松集成到几乎任何数据管道中，充分发挥 ClickHouse 的优势。

​

输入格式

输入格式用于：

• 解析提供给 INSERT 语句的数据
• 从 File、URL 或 HDFS 等以文件为后端的表执行 SELECT 查询
• 读取字典

选择合适的输入格式，对于在 ClickHouse 中高效摄取数据至关重要。支持的格式超过 70 种， 选择性能最佳的格式会显著影响插入速度、CPU 和内存占用，以及整体系统 效率。为了帮助你更好地在这些选项之间做出选择，我们对不同格式的摄取性能进行了基准测试，并总结出以下关键结论：

• Native 格式是效率最高的输入格式，具备最佳压缩效果、最低 资源占用，以及最小的服务端处理开销。
• 压缩至关重要 - LZ4 能以极低的 CPU 代价减小数据体积，而 ZSTD 则能提供更高的压缩率，但 会增加 CPU 使用。
• 预排序的影响较为有限，因为 ClickHouse 本身已经能够高效完成排序。
• 批处理可显著提升效率 - 更大的批次可减少插入开销并提高吞吐量。

如需深入了解测试结果和最佳实践， 请阅读完整的基准分析。 如需查看完整测试结果，请访问 FastFormats 在线仪表板。

​

输出格式

支持输出的格式可用于：

• 格式化 SELECT 查询结果
• 对以文件为后端的表执行 INSERT 操作

​

格式概述

支持的格式如下：

格式	输入	输出
TabSeparated	✔	✔
TabSeparatedRaw	✔	✔
TabSeparatedWithNames	✔	✔
TabSeparatedWithNamesAndTypes	✔	✔
TabSeparatedRawWithNames	✔	✔
TabSeparatedRawWithNamesAndTypes	✔	✔
Template	✔	✔
TemplateIgnoreSpaces	✔	✗
CSV	✔	✔
CSVWithNames	✔	✔
CSVWithNamesAndTypes	✔	✔
CustomSeparated	✔	✔
CustomSeparatedWithNames	✔	✔
CustomSeparatedWithNamesAndTypes	✔	✔
SQLInsert	✗	✔
Values	✔	✔
Vertical	✗	✔
JSON	✔	✔
JSONAsString	✔	✗
JSONAsObject	✔	✗
JSONStrings	✔	✔
JSONColumns	✔	✔
JSONColumnsWithMetadata	✔	✔
JSONCompact	✔	✔
JSONCompactStrings	✗	✔
JSONCompactColumns	✔	✔
JSONEachRow	✔	✔
PrettyJSONEachRow	✗	✔
JSONEachRowWithProgress	✗	✔
JSONStringsEachRow	✔	✔
JSONStringsEachRowWithProgress	✗	✔
JSONCompactEachRow	✔	✔
JSONCompactEachRowWithNames	✔	✔
JSONCompactEachRowWithNamesAndTypes	✔	✔
JSONCompactEachRowWithProgress	✗	✔
JSONCompactStringsEachRow	✔	✔
JSONCompactStringsEachRowWithNames	✔	✔
JSONCompactStringsEachRowWithNamesAndTypes	✔	✔
JSONCompactStringsEachRowWithProgress	✗	✔
JSONObjectEachRow	✔	✔
BSONEachRow	✔	✔
TSKV	✔	✔
Pretty	✗	✔
PrettyNoEscapes	✗	✔
PrettyMonoBlock	✗	✔
PrettyNoEscapesMonoBlock	✗	✔
PrettyCompact	✗	✔
PrettyCompactNoEscapes	✗	✔
PrettyCompactMonoBlock	✗	✔
PrettyCompactNoEscapesMonoBlock	✗	✔
PrettySpace	✗	✔
PrettySpaceNoEscapes	✗	✔
PrettySpaceMonoBlock	✗	✔
PrettySpaceNoEscapesMonoBlock	✗	✔
Prometheus	✗	✔
Protobuf	✔	✔
ProtobufSingle	✔	✔
ProtobufList	✔	✔
Avro	✔	✔
AvroConfluent	✔	✔
Parquet	✔	✔
ParquetMetadata	✔	✗
Arrow	✔	✔
ArrowStream	✔	✔
ORC	✔	✔
One	✔	✗
Npy	✔	✔
RowBinary	✔	✔
RowBinaryWithNames	✔	✔
RowBinaryWithNamesAndTypes	✔	✔
RowBinaryWithDefaults	✔	✗
Native	✔	✔
Buffers	✔	✔
Null	✗	✔
Hash	✗	✔
XML	✗	✔
CapnProto	✔	✔
LineAsString	✔	✔
LineAsStringWithNames	✔	✔
LineAsStringWithNamesAndTypes	✔	✔
Regexp	✔	✗
RawBLOB	✔	✔
MsgPack	✔	✔
MySQLDump	✔	✗
DWARF	✔	✗
Markdown	✗	✔
Form	✔	✗

您可以通过 ClickHouse 设置控制某些格式处理参数。更多信息，请参阅 设置 部分。

​

格式 schema

包含格式 schema 的文件名由设置 format_schema 指定。 使用 Cap'n Proto 和 Protobuf 这两种格式之一时，必须设置此项。 格式 schema 由文件名和该文件中的消息类型名称组成，二者以冒号分隔， 例如 schemafile.proto:MessageType。 如果文件使用该格式的标准扩展名 (例如 Protobuf 的 .proto) ， 则可以省略扩展名，此时格式 schema 形如 schemafile:MessageType。

如果你通过处于交互模式的客户端输入或输出数据，则格式 schema 中指定的文件名 可以包含绝对路径，或相对于客户端当前目录的路径。 如果你在批次模式下使用客户端，出于安全原因，schema 的路径必须是相对路径。

如果你通过 HTTP 接口 输入或输出数据，则格式 schema 中指定的文件名 应位于服务器配置中 format_schema_path 指定的目录下。

​

跳过错误

某些格式 (如 CSV、TabSeparated、TSKV、JSONEachRow、Template、CustomSeparated 和 Protobuf) 在发生解析错误时，可以跳过损坏的行，并从下一行的开头继续解析。请参阅设置 input_format_allow_errors_num 和 input_format_allow_errors_ratio。 限制：

• 发生解析错误时，JSONEachRow 会跳过直到换行符 (或 EOF) 之前的所有数据，因此各行必须以 \n 分隔，才能正确统计错误数。
• Template 和 CustomSeparated 通过最后一列后的分隔符以及行间分隔符来定位下一行的开头，因此只有当其中至少一个非空时，才支持跳过错误。