向ClickHouse插入Pandas DataFrame时birthDate字段序列化失败问题

问题根源 #

虽然报错指向birthDate字段，但实际触发问题的是**addresses字段的类型不匹配**：
测试数据中addresses列的值是空列表[]，而ClickHouse表定义该字段为Nullable(String)——ClickHouse无法将Python列表类型直接序列化为String类型，这种类型冲突会干扰整个插入流程，进而引发看似无关的birthDate序列化报错。移除addresses字段后，类型冲突消失，插入流程恢复正常。

解决方案 #

将addresses列的空列表转换为ClickHouse可识别的String类型值（空字符串""或None），具体处理代码如下：

# 处理addresses字段：将空列表转为空字符串，也可根据需求转为None
df2['addresses'] = df2['addresses'].apply(lambda x: "" if x == [] else x)

# 处理birthDate字段（原代码保留）
df2['birthDate'] = pd.to_datetime(df2['birthDate'], format='mixed', errors='coerce')
# 可选：将NaT转为None，确保和ClickHouse的Nullable(Date)兼容
df2['birthDate'] = df2['birthDate'].where(df2['birthDate'].notna(), None)

# 执行插入
client.insert_df('employees', df2[['code', 'num', 'addresses', 'birthDate', 'employeeID']])

额外验证 #

如果仍有问题，可检查：

• birthDate列是否存在NaT值，确认clickhouse-connect客户端是否支持将NaT自动转为ClickHouse的Null（若不支持，就用上面代码中的where方法转为None）
• 确保所有字段的类型和ClickHouse表定义严格对应：code/num/addresses为字符串类型，birthDate为日期/None，employeeID为整数类型

内容的提问来源于stack exchange，提问作者silverxak