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)

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

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 字节，小端序）

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 表示本地挂钟时间（本地时区下的年、月、日、时、分、秒和子秒字段，而不考虑具体本地时区是哪一个），等同于 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 文件中编码的时间间隔的原始二进制表示。

示例用法

插入数据

使用一个包含以下数据的 Parquet 文件，文件名为 football.parquet：

    ┌───────日期─┬─赛季───┬─主队─────────────────┬─客队───────────────┬─主队进球数───────┬─客队进球数───────┐
 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 table engine。

格式设置

设置	描述	默认
`input_format_parquet_case_insensitive_column_matching`	在匹配 Parquet 列与 ClickHouse 列时不区分大小写。	`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 元数据中的布隆过滤器跳过整个行组。	`0`
`input_format_parquet_use_native_reader`	在读取 Parquet 文件时，使用原生读取器而不是 Arrow 读取器。	`0`
`input_format_parquet_allow_missing_columns`	在读取 Parquet 输入格式时允许列缺失	`1`
`input_format_parquet_local_file_min_bytes_for_seek`	在 Parquet 输入格式中，本地读取文件时，为执行 seek 而不是执行带 ignore 选项的读取所需的最小字节数	`8192`
`input_format_parquet_enable_row_group_prefetch`	在解析 Parquet 时启用行组预取。当前仅支持在单线程解析时进行预取。	`1`
`input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference`	在为 Parquet 格式进行模式推断时跳过类型不受支持的列	`0`
`input_format_parquet_max_block_size`	Parquet 读取器的最大块大小。	`65409`
`input_format_parquet_prefer_block_bytes`	Parquet 读取器输出的平均数据块大小（字节）	`16744704`
`input_format_parquet_enable_json_parsing`	在读取 Parquet 文件时，将 JSON 列解析为 ClickHouse 的 JSON Column 类型。	`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_version`	输出时使用的 Parquet 格式版本。支持的版本：1.0、2.4、2.6 和 2.latest（默认）	`2.latest`
`output_format_parquet_compression_method`	Parquet 输出格式的压缩方式。支持的编解码器：snappy、lz4、brotli、zstd、gzip、none（不压缩）	`zstd`
`output_format_parquet_compliant_nested_types`	在 Parquet 文件模式中，列表元素的名称应使用 'element' 而不是 'item'。这是 Arrow 库实现中的历史遗留问题。一般情况下可以提高兼容性，但某些旧版本的 Arrow 可能不兼容。	`1`
`output_format_parquet_use_custom_encoder`	使用更快速的 Parquet 编码器实现。	`1`
`output_format_parquet_parallel_encoding`	使用多线程进行 Parquet 编码。需要启用 output_format_parquet_use_custom_encoder。	`1`
`output_format_parquet_data_page_size`	压缩前的目标页大小（字节）。	`1048576`
`output_format_parquet_batch_size`	每隔这么多行检查一次页大小。如果某些列中单个值的平均大小超过数 KB，建议适当减小该值。	`1024`
`output_format_parquet_write_page_index`	新增在 Parquet 文件中写入页索引的能力。	`1`
`input_format_parquet_import_nested`	已废弃的设置，不会产生任何作用。	`0`
`input_format_parquet_local_time_as_utc`	true	确定在 `isAdjustedToUTC=false` 的情况下，模式推断对 Parquet 时间戳使用的数据类型。若为 true：DateTime64(..., 'UTC')，若为 false：DateTime64(...)。这两种行为都不完全正确，因为 ClickHouse 没有用于本地墙钟时间的数据类型。看似有些反直觉，但 true 可能是错误更小的选项，因为将带有 'UTC' 的时间戳格式化为 String 时，会得到正确本地时间的表示。

描述​

数据类型匹配​

示例用法​

插入数据​

读取数据​

格式设置​

描述

数据类型匹配

示例用法

插入数据

读取数据

格式设置