向Delta Lake写入DataFrame时分区失败，报IllegalArgumentException

问题背景 #

向Delta Lake写入数据时触发IllegalArgumentException，报错信息如下：

E pyspark.sql.utils.IllegalArgumentException: requirement failed: The provided partitioning does not match of the table.
E - provided: identity(class_name)
E - table:

分区写入代码如下：

df.repartition(col('class_name')).write \
    .option("mergeSchema","true") \
    .format("delta") \
    .mode("append") \
    .partitionBy("class_name") \
    .saveAsTable("dummy_table")

无分区写入可正常执行：

df.write \
    .option("mergeSchema","true") \
    .format("delta") \
    .mode("append") \
    .saveAsTable("dummy_table")

class_name列通过.withColumn创建，参考Delta官方关于添加/移除分区的文档（文档说明Delta Lake支持动态添加分区列），认为当前写法应可行。

问题原因 #

现有表dummy_table最初是无分区状态创建的，Delta Lake不允许直接在append模式下为无分区表指定新的分区列写入——这会触发元数据校验失败，因为表的原有分区配置（无分区）与写入时提供的分区配置（按class_name分区）不匹配。

解决方案 #

1. 先修改表元数据，添加分区列 #

执行SQL语句更新表的分区配置：

ALTER TABLE dummy_table ADD PARTITIONED BY (class_name)

这条语句会将class_name标记为表的分区列，更新表的元数据信息。

2. 调整写入代码 #

移除冗余的repartition操作（Delta Lake写入分区表时会自动按分区列处理数据分区），直接写入：

df.write \
    .option("mergeSchema","true") \
    .format("delta") \
    .mode("append") \
    .partitionBy("class_name") \
    .saveAsTable("dummy_table")

3. 验证结果 #

执行以下命令确认表的分区配置已更新：

DESCRIBE EXTENDED dummy_table

查看输出中的Partition Columns字段，确认class_name已被列为分区列，同时检查数据是否正确写入对应分区目录。

补充说明 #

• 确保class_name列的数据类型与表元数据中定义的类型一致，避免因隐式类型转换引发的异常。
• 若需要对历史数据按class_name重新分区以优化查询性能，可执行OPTIMIZE dummy_table ZORDER BY (class_name)，此步骤为可选操作。

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