AWS SDK for Pandas 中写入索引列导致 Parquet 读取异常问题分析

在 AWS SDK for Pandas（原 awswrangler）项目中，用户在使用 s3.to_parquet 方法写入带有索引的 DataFrame 时，如果多次执行写入操作并尝试读取，会遇到 InvalidSchemaConvergence 异常。本文将深入分析该问题的技术背景、产生原因以及解决方案。

问题现象

当开发者使用以下代码模式时会出现问题：

import awswrangler as wr
import pandas as pd

df = pd.DataFrame({"idx": [1, 2, 3], "val": [1.0, 2.0, 3.0]})
df = df.set_index("idx")

# 第一次写入和读取正常
wr.s3.to_parquet(df, path="s3://...", index=True, dataset=True)
wr.s3.read_parquet(path="s3://...", validate_schema=True)

# 第二次写入和读取会抛出异常
wr.s3.to_parquet(df, path="s3://...", index=True, dataset=True)
wr.s3.read_parquet(path="s3://...", validate_schema=True)

在第二次读取时会抛出 InvalidSchemaConvergence 异常，提示检测到至少两种不同的 schema。

技术背景

Parquet 文件格式特性

Parquet 是一种列式存储格式，具有以下特点：

1. 自描述性：文件内包含完整的 schema 信息
2. 高效压缩：针对列式数据优化压缩
3. 模式演化：支持 schema 随时间变化

AWS SDK for Pandas 的 schema 验证

validate_schema=True 参数会强制验证所有文件的 schema 一致性，这是确保数据质量的重要机制。当检测到 schema 不一致时，会抛出 InvalidSchemaConvergence 异常。

问题根源分析

该问题源于 AWS SDK for Pandas 3.5.0 版本引入的一个新功能：支持通过索引列进行分区（PR #2528）。这个改动影响了 Parquet 文件的元数据处理方式：

1. 第一次写入时，索引信息被正确写入文件元数据
2. 第二次写入时，由于某些内部处理逻辑，索引信息在元数据中的表示方式发生了变化
3. 读取时 schema 验证器检测到元数据不一致，认为这是不同的 schema

解决方案

该问题已在最新版本中修复，主要修改点包括：

1. 统一索引列在 Parquet 元数据中的表示方式
2. 确保多次写入时元数据的一致性
3. 改进 schema 比较逻辑，使其能正确处理索引列的元数据变化

最佳实践建议

对于需要频繁更新 Parquet 数据集的情况，建议：

1. 明确指定索引列的名称，避免使用匿名索引
2. 对于生产环境，建议固定 AWS SDK for Pandas 的版本
3. 在开发阶段开启 schema 验证，但在生产环境可以考虑关闭以获得更好的性能
4. 考虑使用 Delta Lake 或 Iceberg 等支持 ACID 特性的表格式，它们能更好地处理 schema 演化问题

总结

这个问题展示了数据工程中 schema 管理的重要性。AWS SDK for Pandas 通过严格的 schema 验证帮助用户及早发现潜在的数据一致性问题，但也需要在功能开发和用户体验之间找到平衡。理解底层存储格式的特性和工具的行为模式，有助于开发者构建更健壮的数据处理流程。