Databricks Delta表Merge报错：多源行匹配修改同一目标行

报错信息 #

执行Merge操作时抛出如下异常：

UnsupportedOperationException: Cannot perform Merge as multiple source rows matched and attempted to modify the same
target row in the Delta table in possibly conflicting ways.

报错核心逻辑 #

该异常触发的唯一判定标准是：单条Delta目标表记录，在Merge的匹配阶段关联到了2条及以上源表记录。Delta无法判定应该使用哪条源表数据执行修改，就会直接终止操作。
常规触发场景是源表存在重复主键，但代码写法问题也会触发同类报错，和源表是否有重复主键无关。

问题代码 #

(deltadf.alias("t")
     .merge(
      df.alias("s"),
      "s.primary_key_hash = t.primary_key_hash")
    .whenMatchedUpdateAll("s.change_key_hash <> t.change_key_hash")
    .whenNotMatchedInsertAll()
   .execute()
  )

根因定位 #

代码存在两个明显的逻辑问题：

1. 混淆了Merge的匹配条件和更新执行条件
   写在merge()方法第二个参数位置的表达式才是匹配阶段的关联条件，会直接参与匹配行数校验；写在whenMatchedUpdateAll()括号内的表达式，是匹配成功之后才会判断的执行门槛，不会减少匹配阶段的关联行数。
   现有代码仅用primary_key_hash做匹配关联，哪怕源表中同主键的记录里，存在change_key_hash和目标表完全一致的条目，依然会被计入匹配关系，只要同主键下源表记录数≥2，就会触发报错。
2. 未对源表做前置去重
   Merge要求源表在关联键上必须保持唯一，无论后续更新条件怎么写，只要源表关联键存在重复，就有概率触发多行匹配异常。

修复方案 #

• 源表前置去重：传入Merge前先对源DataFrame按primary_key_hash分组，保留业务逻辑下需要生效的唯一记录（通常取最新变更时间、最大change_key的条目）
• 把更新判断条件前移到匹配阶段：将change_key_hash的不等值判断加入Merge关联条件，减少无效匹配

修复后参考代码：

from pyspark.sql.window import Window
import pyspark.sql.functions as F

# 按主键对源表去重，保留每个主键下change_key_hash最大的最新记录
dedup_window = Window.partitionBy("primary_key_hash").orderBy(F.desc("change_key_hash"))
source_dedup_df = (
    df
    .withColumn("row_num", F.row_number().over(dedup_window))
    .filter(F.col("row_num") == 1)
    .drop("row_num")
)

# 执行Merge操作
(deltadf.alias("t")
     .merge(
      source_dedup_df.alias("s"),
      # 匹配条件同时包含主键相等、变更key不等，避免无效匹配
      condition = "s.primary_key_hash = t.primary_key_hash AND s.change_key_hash <> t.change_key_hash"
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
   .execute()
)

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