使用Spark的MERGE INTO/INSERT INTO操作Iceberg表时写入异常

问题现象 #

在EMR Notebook中对Iceberg表执行写入操作（追加、MERGE INTO）完全正常，但通过spark-submit提交Scala版Spark应用时，所有写入操作都会删除现有数据，仅保留新写入的内容，而非预期的追加行为。

背景信息 #

1. Iceberg表通过EMR Notebook创建，之后执行过分区列重命名：

ALTER TABLE my_catalog.raw_data.civ RENAME COLUMN date TO snapshot_day

2. spark-submit使用的配置：

--conf spark.sql.catalog.my_catalog=org.apache.iceberg.spark.SparkCatalog 
--conf spark.sql.catalog.my_catalog.type=glue 
--conf spark.sql.catalog.my_catalog.warehouse=s3://<some_location>/ 
--conf spark.sql.sources.partitionOverwriteMode=dynamic

排查与结论 #

经过对比测试不同写入API的表现，定位到问题根源：

• 无效写法（触发覆盖）：

df.write.format("iceberg").mode("append").saveAsTable(outputTableName)

• 有效写法（正常追加）：

df.writeTo(outputTableName).append()

问题本质是Jar包构建错误，导致旧版的Iceberg写入API无法正确识别Iceberg表的元数据（尤其是分区列重命名后的元信息），进而错误触发了覆盖逻辑；而新版的writeTo API不受该构建问题影响，能正确执行追加操作。

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