Parquet

Parquet 格式文档

输入	输出	别名
✔	✔

​

说明

Apache Parquet 是一种在 Hadoop 生态系统中广泛使用的列式存储格式。ClickHouse 支持读取和写入这种格式。

​

数据类型匹配

下表展示了 Parquet 数据类型与 ClickHouse 数据类型 之间的对应关系。

Parquet 类型 (逻辑类型、转换类型或物理类型)	ClickHouse 数据类型
BOOLEAN	Bool
UINT_8	UInt8
INT_8	Int8
UINT_16	UInt16
INT_16	Int16/Enum16
UINT_32	UInt32
INT_32	Int32
UINT_64	UInt64
INT_64	Int64
DATE	Date32
TIMESTAMP, TIME	DateTime64
FLOAT	Float32
DOUBLE	Float64
INT96	DateTime64(9, ‘UTC’)
BYTE_ARRAY, UTF8, ENUM, BSON	String
JSON	JSON
FIXED_LEN_BYTE_ARRAY	FixedString
DECIMAL	Decimal
LIST	Array
MAP	Map
struct	Tuple
FLOAT16	Float32
UUID	FixedString(16)
INTERVAL	FixedString(12)
Point (GeoParquet)	Point
LineString (GeoParquet)	LineString
Polygon (GeoParquet)	Polygon
MultiLineString (GeoParquet)	MultiLineString
MultiPolygon (GeoParquet)	MultiPolygon
混合/未知几何体 (GeoParquet)	Geometry

写入 Parquet 文件时，没有对应 Parquet 类型的数据类型会被转换为最接近的可用类型：

ClickHouse 数据类型	Parquet 类型
IPv4	UINT_32
IPv6	FIXED_LEN_BYTE_ARRAY (16 字节)
Date (16 位)	DATE (32 位)
DateTime (32 位，秒)	TIMESTAMP (64 位，毫秒)
Int128/UInt128/Int256/UInt256	FIXED_LEN_BYTE_ARRAY (16/32 字节，小端序)
Point	BYTE_ARRAY (WKB) + GeoParquet 元数据
LineString	BYTE_ARRAY (WKB) + GeoParquet 元数据
Polygon	BYTE_ARRAY (WKB) + GeoParquet 元数据
MultiLineString	BYTE_ARRAY (WKB) + GeoParquet 元数据
MultiPolygon	BYTE_ARRAY (WKB) + GeoParquet 元数据

Array 可以嵌套，其参数值也可以是 Nullable 类型。Tuple 和 Map 类型同样可以嵌套。

ClickHouse 表列的数据类型可以与插入的 Parquet 数据中对应字段的类型不同。插入数据时，ClickHouse 会先根据上表解释数据类型，然后将数据 转换 为 ClickHouse 表列所设置的数据类型。例如，UINT_32 Parquet 列可以读入 IPv4 ClickHouse 列中。

对于某些 Parquet 类型，并没有与之非常接近的 ClickHouse 类型。我们按如下方式读取它们：

• TIME (一天中的时间) 会被读取为时间戳。例如，10:23:13.000 会变成 1970-01-01 10:23:13.000。
• 设置了 isAdjustedToUTC=false 的 TIMESTAMP/TIME 表示本地挂钟时间 (即本地时区中的年、月、日、时、分、秒和亚秒字段，不论具体将哪个 timezone 视为本地) ，与 SQL TIMESTAMP WITHOUT TIME ZONE 相同。但 ClickHouse 读取时会改为将其视作 UTC 时间戳。例如，2025-09-29 18:42:13.000 (表示本地挂钟上的读数) 会变成 2025-09-29 18:42:13.000 (DateTime64(3, 'UTC')，表示一个时间点) 。如果将其转换为 String，会显示正确的年、月、日、时、分、秒和亚秒，此时可以将其理解为某个本地时区中的时间，而不是 UTC。违反直觉的是，把类型从 DateTime64(3, 'UTC') 改为 DateTime64(3) 也没有帮助，因为这两种类型表示的都是时间点，而不是时钟读数；但 DateTime64(3) 还会错误地使用本地时区进行格式化。
• INTERVAL 当前会被读取为 FixedString(12)，内容是时间间隔的原始二进制表示，编码方式与 Parquet 文件中一致。

​

Geo 类型 (GeoParquet)

ClickHouse 支持按照 GeoParquet 规范读写几何列。几何列以 WKB 编码的 BYTE_ARRAY 载荷形式存储 (读取时也支持 WKT) ，并在文件级 Parquet 元数据中通过一个 JSON geo 键描述每个几何列的编码、几何类型和 CRS。

​

读取行为

读取时，几何列会映射为对应的 ClickHouse geo data types：

• 声明为 Point、LineString、Polygon、MultiLineString 或 MultiPolygon 的列，会读取为对应的 ClickHouse geo type。
• 包含多种或未知几何类型的列，会读取为 Geometry 类型，它是一个涵盖所有受支持 geo types 的 Variant。
• 如果请求的列类型为 String，则会忽略 GeoParquet 元数据，并按原样返回原始编码的几何载荷——WKB 或 WKT 字节，具体取决于 GeoParquet 列声明的编码类型。如果设置 input_format_parquet_allow_geoparquet_parser 为 0，也是如此。

​

写入行为

写入时，类型为 Point、LineString、Polygon、MultiLineString 或 MultiPolygon 的顶层列会编码为 BYTE_ARRAY (WKB) ，并将相应的 geo JSON 元数据 追加到 Parquet 文件页脚。顶层的 Geometry Variant 也会被编码为 WKB BYTE_ARRAY 载荷 (其子值会转换为 WKB，并存储为 Nullable(String) 列) ，但不会为其输出 geo 元数据，因此读取时，结果不会被识别为 GeoParquet 几何列。其他与 geo 相关的类型 (例如 Ring) 则会使用其原生底层表示写入，不附带任何 GeoParquet 元数据。将 output_format_parquet_geometadata 设置为 0 可完全禁用此行为；在这种情况下，即使是受支持的 geo 类型，也会使用其原生底层表示写入 (Point 写为 Tuple(Float64, Float64)，LineString 写为 Array(Point)，Polygon 写为 Array(Array(Point))，等等) ，并且不会输出任何 GeoParquet 元数据。

几何列必须位于 schema 根级，或嵌套在 Tuple (struct) 内；不支持将其嵌套在 Array 或 Map 中。geo 列同样也不支持 Nullable。

​

使用示例

​

插入数据

使用一个名为 football.parquet 的 Parquet 文件，内容如下：

    ┌───────date─┬─season─┬─home_team─────────────┬─away_team───────────┬─home_team_goals─┬─away_team_goals─┐
 1. │ 2022-04-30 │   2021 │ Sutton United         │ Bradford City       │               1 │               4 │
 2. │ 2022-04-30 │   2021 │ Swindon Town          │ Barrow              │               2 │               1 │
 3. │ 2022-04-30 │   2021 │ Tranmere Rovers       │ Oldham Athletic     │               2 │               0 │
 4. │ 2022-05-02 │   2021 │ Port Vale             │ Newport County      │               1 │               2 │
 5. │ 2022-05-02 │   2021 │ Salford City          │ Mansfield Town      │               2 │               2 │
 6. │ 2022-05-07 │   2021 │ Barrow                │ Northampton Town    │               1 │               3 │
 7. │ 2022-05-07 │   2021 │ Bradford City         │ Carlisle United     │               2 │               0 │
 8. │ 2022-05-07 │   2021 │ Bristol Rovers        │ Scunthorpe United   │               7 │               0 │
 9. │ 2022-05-07 │   2021 │ Exeter City           │ Port Vale           │               0 │               1 │
10. │ 2022-05-07 │   2021 │ Harrogate Town A.F.C. │ Sutton United       │               0 │               2 │
11. │ 2022-05-07 │   2021 │ Hartlepool United     │ Colchester United   │               0 │               2 │
12. │ 2022-05-07 │   2021 │ Leyton Orient         │ Tranmere Rovers     │               0 │               1 │
13. │ 2022-05-07 │   2021 │ Mansfield Town        │ Forest Green Rovers │               2 │               2 │
14. │ 2022-05-07 │   2021 │ Newport County        │ Rochdale            │               0 │               2 │
15. │ 2022-05-07 │   2021 │ Oldham Athletic       │ Crawley Town        │               3 │               3 │
16. │ 2022-05-07 │   2021 │ Stevenage Borough     │ Salford City        │               4 │               2 │
17. │ 2022-05-07 │   2021 │ Walsall               │ Swindon Town        │               0 │               3 │
    └────────────┴────────┴───────────────────────┴─────────────────────┴─────────────────┴─────────────────┘

插入数据：

INSERT INTO football FROM INFILE 'football.parquet' FORMAT Parquet;

​

读取数据

使用 Parquet 格式读取数据：

SELECT *
FROM football
INTO OUTFILE 'football.parquet'
FORMAT Parquet

Parquet 是一种二进制格式，无法在终端中以人类可读的形式显示。请使用 INTO OUTFILE 输出 Parquet 文件。

如需与 Hadoop 交换数据，可以使用 HDFS 表引擎。

​

格式设置

设置	说明	默认值
input_format_parquet_case_insensitive_column_matching	匹配 Parquet 列与 CH columns 时忽略大小写。	0
input_format_parquet_preserve_order	从 Parquet 文件读取时避免对行重新排序。通常会明显变慢。	0
input_format_parquet_filter_push_down	读取 Parquet 文件时，根据 WHERE/PREWHERE 表达式以及 Parquet 元数据中的最小/最大统计信息，跳过整个行组。	1
input_format_parquet_bloom_filter_push_down	读取 Parquet 文件时，根据 WHERE 表达式以及 Parquet 元数据中的 bloom filter，跳过整个行组。	0
input_format_parquet_allow_missing_columns	读取 Parquet 输入格式时允许存在缺失列。	1
input_format_parquet_local_file_min_bytes_for_seek	在 Parquet 输入格式中，本地读取 (文件) 执行寻道而不是通过跳过读取时所需的最小字节数。	8192
input_format_parquet_enable_row_group_prefetch	在解析 Parquet 期间启用行组预取。目前只有单线程解析支持预取。	1
input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference	对 Parquet 格式进行 schema inference 时，跳过类型不受支持的列。	0
input_format_parquet_max_block_size	parquet reader 的最大块大小。	65409
input_format_parquet_prefer_block_bytes	parquet reader 输出的平均块字节数。	16744704
input_format_parquet_enable_json_parsing	读取 Parquet 文件时，将 JSON columns 解析为 ClickHouse JSON Column。	1
input_format_parquet_allow_geoparquet_parser	读取 Parquet 文件时，识别 GeoParquet geo 元数据，并将几何列 (WKB 或 WKT，具体取决于列声明的编码) 解码为 ClickHouse geo 数据类型。如果为 0，几何列将以其原始物理表示 (String) 形式呈现。	1
output_format_parquet_row_group_size	目标行组大小 (按行数计) 。	1000000
output_format_parquet_row_group_size_bytes	压缩前的目标行组大小 (按字节计) 。	536870912
output_format_parquet_string_as_string	对 String 列使用 Parquet String 类型，而不是 Binary。	1
output_format_parquet_fixed_string_as_fixed_byte_array	对 FixedString 列使用 Parquet FIXED_LEN_BYTE_ARRAY 类型，而不是 Binary。	1
output_format_parquet_compression_method	Parquet output format 的压缩方法。支持的 codec：snappy、lz4、brotli、zstd、gzip、none (未压缩) 。	zstd
output_format_parquet_parallel_encoding	使用多个线程进行 Parquet 编码。	1
output_format_parquet_data_page_size	压缩前的目标页大小 (按字节计) 。	1048576
output_format_parquet_batch_size	每隔这么多行检查一次页大小。如果列的平均值大小超过几个 KB，可考虑减小此值。	1024
output_format_parquet_write_page_index	允许将页索引写入 parquet 文件。	1
output_format_parquet_geometadata	将 GeoParquet geo 元数据写入 Parquet 文件页脚，并将顶层 ClickHouse geo 列 (Point、LineString、Polygon、MultiLineString、MultiPolygon) 编码为 WKB。如果为 0，则这些列会使用其原生底层表示形式写入 (例如将 Point 写为 Tuple(Float64, Float64)) ，且不会生成任何 GeoParquet 元数据。	1
input_format_parquet_import_nested	已废弃设置，不起任何作用。	0
input_format_parquet_local_time_as_utc	true	确定对 isAdjustedToUTC=false 的 Parquet 时间戳进行 schema inference 时使用的数据类型。如果为 true：DateTime64(..., 'UTC')；如果为 false：DateTime64(...)。这两种行为都不完全正确，因为 ClickHouse 没有表示本地挂钟时间的数据类型。反直觉的是，true 可能反而是相对没那么不正确的选项，因为将 'UTC' 时间戳格式化为 String 时，会得到正确的本地时间表示。