David Wheeler：pg_clickhouse 与 chdb 更新：编码、嵌套与类型
内容提要
pg_clickhouse v0.11.0 与 chdb 扩展 v0.1.2 发布，重点提升跨数据库兼容性。新增 check_encoding 选项处理字符编码错误，支持 fail、remove、replace、truncate 四种方式；新增 ClickHouse 各类 Interval 类型映射为 Postgres interval；支持参数化 JSON 列映射为 jsonb，并改进未展平 Nested 类型支持，可映射为多维数组或自定义复合类型。此外还优化了整数、几何等类型映射，移除旧函数并停止支持 PostgreSQL 13。
延伸解读
编码错误处理：灵活应对无效字节
pg_clickhouse v0.11.0 新增 check_encoding 选项，提供 fail、remove、replace、truncate 四种处理方式。对于 UTF-8 数据库，replace 会将无效字节替换为 Unicode 替换字符（�），而其他编码则直接移除。若需保留原始字节，可将列映射为 bytea，但转换为文本时会失败。这一改进让用户能根据数据完整性需求选择策略，避免因编码问题导致查询中断。
Interval 类型映射：从报错到无缝支持
此前 pg_clickhouse 不支持 ClickHouse 的 Interval 类型，导入时会报错。v0.11.0 和 chdb_hook 0.1.2 将这些类型映射为 Postgres interval 列，并支持条件下推，例如 start_at + duration 的过滤能在 ClickHouse 端执行。用户也可选择将 interval 导入为 bigint。需要注意的是，ClickHouse 的 interval 类型尚不支持聚合函数，如 avg(duration) 会失败。
嵌套与 JSON 类型：更自然的映射方式
对于参数化 JSON 列，新版本将其映射为 jsonb，使 ORDER BY 属性访问能正确下推。未展平的 Nested 类型默认映射为二维文本数组，但也可映射为自定义复合类型数组，前提是字段顺序、类型和名称完全匹配。这为处理复杂嵌套数据提供了更结构化的选择，同时保留了插入时的类型转换能力。
其他改进与升级注意
本次更新还优化了整数、几何等类型映射，例如 Int128 映射为 numeric(39,0)，Point 映射为 point。旧函数 clickhouse_raw_query() 已被移除，需改用 clickhouse_query() 或 clickhouse_perform()。此外，停止支持 PostgreSQL 13，并新增了 sha224 等函数的条件下推。升级前请检查代码兼容性。
Q&A
pg_clickhouse v0.11.0 新增的 check_encoding 选项有哪些处理方式？
check_encoding 提供四种编码错误处理方式：fail（默认，抛出错误）、remove（移除无效字节）、replace（在 UTF-8 编码下将无效字节替换为 Unicode 替换字符 �，其他编码等同于 remove）、truncate（在第一个无效字节处截断文本）。
如何让 pg_clickhouse 导入 ClickHouse 的 Interval 类型？
pg_clickhouse v0.11.0 和 chdb_hook 0.1.2 会自动将 ClickHouse 的 Interval 类型（如 IntervalMillisecond）导入为 Postgres 的 interval 列。如果希望导入为 bigint，只需在创建外部表或复制目标表时将对应列定义为 bigint 即可。
pg_clickhouse 如何处理 ClickHouse 的参数化 JSON 列？
pg_clickhouse v0.11.0 和 chdb_hook v0.1.2 将参数化 JSON 列映射为 Postgres 的 jsonb（或 json）类型，从而支持对 JSON 属性进行 ORDER BY 等操作并正确下推。
未展平的 Nested 类型在 pg_clickhouse 中如何映射？
默认情况下，未展平的 Nested 列会映射为二维 text 数组（如 text[][]）。此外，也可以映射为自定义复合类型数组，前提是复合类型的字段顺序、类型和名称与 Nested 结构完全一致。
pg_clickhouse v0.11.0 移除了哪个旧函数？应该用什么替代？
移除了已弃用的 clickhouse_raw_query() 函数。应改用 clickhouse_query(server, sql) 来读取行，使用 CALL clickhouse_perform(server, sql) 来执行不返回结果的语句。
pg_clickhouse v0.11.0 还改进了哪些数据类型映射？
大整数类型映射为合适的 Postgres numeric，例如 Int128 映射为 numeric(39,0)、Int256 映射为 numeric(77,0)、UInt64 映射为 numeric(20,0) 等。此外，BFloat16 映射为 float4，Time 映射为 time，Tuple 映射为 text[]，Map 映射为 text[][]，几何类型如 LineString 映射为 path 等。
