跳转到主要内容

说明

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 视为本地) ,与 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 文件中一致。

Variant 类型

ClickHouse 会将以 Parquet VARIANT 编码存储的列 (例如由 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。

文件引用

带有 Parquet FILE 逻辑类型注解的 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 规范以及 Parquet GEOMETRY 和 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 格式读取数据:
Parquet 是一种二进制格式,无法在终端中以人类可读的形式显示。请使用 INTO OUTFILE 输出 Parquet 文件。
如需与 Hadoop 交换数据,可以使用 HDFS 表引擎。

格式设置