说明
Apache Parquet 是一种在 Hadoop 生态系统中广泛使用的列式存储格式。ClickHouse 支持读取和写入这种格式。数据类型匹配
下表展示了 Parquet 数据类型与 ClickHouse 数据类型 之间的对应关系。
写入 Parquet 文件时,没有对应 Parquet 类型的数据类型会被转换为最接近的可用类型:
Array 可以嵌套,其参数值也可以是
Nullable 类型。Tuple 和 Map 类型同样可以嵌套。
宽整数
默认情况下,ClickHouse 会将Int128、UInt128、Int256 和 UInt256 以未标注的 FIXED_LEN_BYTE_ARRAY(16/32) 值按小端序写入。为确保较旧版本的 ClickHouse 能够读取文件,此旧版表示形式仍为默认设置。
设置 output_format_parquet_wide_integer_as_decimal = 1,以改用标准 Parquet DECIMAL 表示形式:
十进制表示形式可为标准 Parquet 列块统计信息和页面索引提供数值排序,使 ClickHouse 能够利用行组和页面的最小值/最大值进行裁剪。ClickHouse 可读取这两种编码。对于精度为 39 的十进制数,schema 推断会返回由
Decimal256 支持的 Decimal(39, 0);请显式指定 Int128 或 UInt128 结构以恢复宽整数类型。十进制精度 77 或 78 超出 ClickHouse Decimal256 的范围,因此读取这些文件时需要显式指定兼容的 Int256 或 UInt256 结构。使用显式宽整数结构时,ClickHouse 接受以任意有效宽度的 BYTE_ARRAY 或 FIXED_LEN_BYTE_ARRAY 存储的标准十进制值,并在移除符号扩展后对每个值执行范围检查。
某些 Parquet 客户端仅支持最高 38 的十进制精度,而 Arrow 的高级十进制类型仅支持最高 76 的精度。尽管精度为 77/78 的表示形式的 schema 和 33 字节物理宽度符合 Parquet 规范,此类客户端仍可能拒绝它。当文件必须由较旧版本的 ClickHouse 或十进制精度上限较低的客户端读取时,请保持禁用该设置。
ClickHouse 表列的数据类型可以与插入的 Parquet 数据中对应字段的类型不同。插入数据时,ClickHouse 会先根据上表解释数据类型,然后将数据 转换 为 ClickHouse 表列所设置的数据类型。例如,UINT_32 Parquet 列可以读入 IPv4 ClickHouse 列中。
对于某些 Parquet 类型,并没有与之非常接近的 ClickHouse 类型。我们按如下方式读取它们:
- 设置了
isAdjustedToUTC=false的TIMESTAMP表示本地挂钟时间 (即本地时区中的年、月、日、时、分、秒和亚秒字段,不论具体将哪个 timezone 视为本地) ,与 SQLTIMESTAMP 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 文件中一致。
Variant 类型
ClickHouse 会将以 ParquetVARIANT 编码存储的列 (例如由 Spark 4.0 写入的列) 读取为 Dynamic 类型。如果某列是带有 VARIANT 逻辑类型注解 (规范版本 1) 的 group,则会被识别为 variant。由于 Spark 4.0 写入 variant 列时不带此注解,因此仅包含 metadata 和 value 两个 BYTE_ARRAY 类型字段的 group 也会被读取为 variant。可以通过设置 input_format_parquet_detect_variant_by_structure 禁用此行为,此时这类 group 会像以前一样,被读取为由这两个原始字段组成的 Tuple;若为该列显式指定 Dynamic 或 JSON 类型,则无论该设置如何,都会将其作为 variant 读取。
每个值都保留各自的类型。Variant 原始类型会被读取为对应的 ClickHouse 类型 (例如,int32 读取为 Int32,decimal8 读取为 Decimal(18, S),timestamp 读取为 DateTime64(6, 'UTC'),timestamp_ntz 读取为 DateTime64(6),binary 和 string 读取为 String,uuid 读取为 UUID) ;variant null 读取为 NULL;variant 对象读取为 JSON,其中嵌套对象会被展平为以点分隔的路径 (值为 null 的字段视为不存在) ;元素全部为对象的 variant 数组读取为 Array(JSON),其他 variant 数组则读取为 Array(Dynamic)。之所以顶层类型为 Dynamic 而非 JSON,是因为 variant 值不一定是对象。
也可以通过显式指定类型,将 variant 列读取为 JSON,例如在表结构中或在 file 表函数的 structure 参数中指定。此时每个值都必须是对象,否则会抛出异常。variant null 以及整列为 null 的情况都会被读取为空对象。所请求的 JSON 类型中显式指定类型的路径会被转换为相应类型,而 SKIP 和 SKIP REGEXP 中列出的路径会被跳过。
目前尚不支持 shredded variant (包含 typed_value 字段的 group) :读取此类列会抛出异常,但文件中的其他列仍可正常读取;如果启用了 input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference,schema 推断会跳过该列。此外,也不支持将 Dynamic 或 JSON 列以 VARIANT 形式写入 Parquet。
文件引用
带有 ParquetFILE 逻辑类型注解的 group 表示对某段字节范围的引用,这段字节可以内联存储,也可以存储在外部文件中。读取时,它会被解析为一个命名 Tuple,包含文件中实际存在的字段,且每个字段均为 Nullable:uri、content_type 和 checksum 为 Nullable(String),offset 和 size 为 Nullable(Int64),inline 为存放原始字节的 Nullable(String)。值为 null 的文件引用会被读取为所有元素均为 NULL 的元组。与其他 Tuple 一样,可以通过请求元素更少的 Tuple 来只读取部分字段,也可以将单个字段作为子列读取,例如 file.uri。ClickHouse 会验证该 group 的 schema:其中只能包含上述字段,所有字段均须为 OPTIONAL,且类型须与规范定义一致,否则将抛出异常。但不会验证字段值:即使某个值无法构成有效引用 (例如只有 offset 而没有 uri) ,也会按存储时的原样返回。ClickHouse 不会解析这些引用,也就是说,不会读取外部文件。
写入时,如果启用了 output_format_parquet_write_file_logical_type 设置,此类 Tuple (元素名称为 FILE 字段的非空子集,offset 和 size 为整数,其他元素为 String 或 FixedString) 会被写为带有 FILE 注解的 group;否则会被写为普通 group。
地理空间类型 (GeoParquet)
ClickHouse 支持按照 GeoParquet 规范以及 ParquetGEOMETRY 和 GEOGRAPHY 逻辑类型读写几何列。几何列以 WKB 编码的 BYTE_ARRAY 载荷形式存储 (对于 GeoParquet,读取时也支持 WKT) 。GeoParquet 在文件级 Parquet 元数据中通过一个 JSON geo 键描述每个几何列的编码、几何类型和 CRS;逻辑类型则直接标注在列本身上,此时列块元数据中包含的是 GeospatialStatistics (一个包围盒以及几何类型列表) ,而非min/max 统计信息。一个文件可以同时采用这两种方式。
读取行为
读取时,几何列会映射为对应的 ClickHouse 地理空间类型:- 声明为
Point、MultiPoint、LineString、Polygon、MultiLineString或MultiPolygon的列,会读取为对应的 ClickHouse 地理空间类型。 - 包含多种或未知几何类型的列,会读取为
Geometry类型,它是一个涵盖所有受支持地理空间类型 的Variant。 - 对于逻辑类型为
GEOMETRY或GEOGRAPHY的列,如果文件包含 GeoParquet 元数据,则从中获取几何类型;否则,若所有列块的GeospatialStatistics都列出同一种二维几何类型,该列会读取为对应的地理空间类型,否则读取为Geometry。如果显式指定了某个地理空间类型,值会直接解码为该类型。 - ClickHouse 没有单独的地理 (geography) 类型,因此
GEOGRAPHY列会读取为与GEOMETRY相同的地理空间类型 (坐标为经度和纬度) ,边插值算法 (algorithm参数) 也不会保留。CRS (crs参数,默认为OGC:CRS84) 同样不会保留。不支持包含 Z 或 M 坐标的几何对象。 GEOMETRY和GEOGRAPHY逻辑类型的排序顺序未定义,因此会忽略此类列的 min/max 统计信息和列索引。启用input_format_parquet_spatial_filter_push_down后,会利用GeospatialStatistics中的包围盒跳过行组。- 如果请求的列类型为
String,则会忽略 GeoParquet 元数据和逻辑类型,并按原样返回原始编码的几何载荷——WKB 或 WKT 字节,具体取决于 GeoParquet 列声明的编码类型。如果设置input_format_parquet_allow_geoparquet_parser为0且未显式指定地理空间类型,也是如此。
写入行为
写入时,类型为Point、MultiPoint、LineString、Polygon、MultiLineString 或 MultiPolygon 的顶层列会编码为 BYTE_ARRAY (WKB) ,并将相应的 geo JSON 元数据 追加到 Parquet 文件页脚。顶层的 Geometry Variant 也会被编码为 WKB BYTE_ARRAY 载荷 (其子值会转换为 WKB,并存储为 Nullable(String) 列) ,但默认情况下不会为其输出 geo 元数据,因此读取时会被读作 String。默认情况下,这些列会以 BYTE_ARRAY 形式写入,并附带 min/max 统计信息。启用设置 output_format_parquet_geometry_logical_type 后,所有这些列都会使用默认 CRS (OGC:CRS84) 标注为 GEOMETRY 逻辑类型;按照规范要求,其列块元数据包含 GeospatialStatistics (包围盒和几何类型) ,但不包含 min/max 统计信息和列索引;此外,Geometry 列会在 geo 元数据中以空的几何类型列表进行描述,因此读取时会被读作 Geometry。该设置默认禁用,因为不识别此逻辑类型的读取器 (例如 Arrow C++ 以及 20 版本之前的 pyarrow) 将根本无法打开该文件。其他与 geo 相关的类型 (例如 Ring) 则会使用其原生底层表示写入,不附带任何 GeoParquet 元数据。将 output_format_parquet_geometadata 设置为 0 可完全禁用此行为;在这种情况下,即使是受支持的 地理空间类型,也会使用其原生底层表示写入 (Point 写为 Tuple(Float64, Float64),LineString 写为 Array(Point),Polygon 写为 Array(Array(Point)),等等) ,并且不会输出任何 GeoParquet 元数据。
几何列必须位于 schema 根级,或嵌套在 Tuple (struct) 内;不支持将其嵌套在 Array 或 Map 中。geo 列同样也不支持 Nullable。
使用示例
插入数据
使用一个名为football.parquet 的 Parquet 文件,内容如下:
读取数据
使用Parquet 格式读取数据:
HDFS 表引擎。