ADF upsert写入同主键多条记录时报主键冲突错误如何解决

核心根因 #

ADF Copy活动/数据流的Upsert逻辑不会在单个写入批次内自动对同主键记录做去重，逻辑是先对批次内所有记录做目标表主键存在性校验，不存在则插入、存在则更新。如果同一个写入批次里包含两条及以上同主键的记录（比如同customer ID+联合主键的Order Received、Order Update事件），校验阶段就会判定要插入多条同主键记录，直接抛出主键冲突错误，和是否勾选Upsert选项、是否配置主键字段没有直接关系。

可落地修复步骤 #

• 写入Sink前增加批次内去重逻辑
  在数据流的源转换之后、Sink转换之前，加一个「聚合」转换：按配置的所有联合主键字段（customer ID+其他主键字段）分组，取事件时间戳最大的那条记录即可。不要直接用Distinct做全字段去重，必须按事件触发时间排序筛选：Order Received事件的触发时间早于对应Order Update事件，同主键下仅保留时间戳最新的单条记录，保证送入Sink的每个主键值仅对应1条数据。
  注意统一事件时间字段的时区，避免时区偏差导致旧事件被判定为最新事件、反向覆盖新数据。
• 对齐ADF配置与目标SQL表的主键定义
  ADF Sink中配置的「键列」（Upsert匹配键）必须和目标SQL表实际定义的主键/唯一约束字段完全一致，不能缺字段也不能多字段。执行以下SQL查询目标表的实际主键字段，和ADF配置逐字段比对：

  SELECT COLUMN_NAME
  FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
  WHERE OBJECTPROPERTY(OBJECT_ID(CONSTRAINT_SCHEMA + '.' + CONSTRAINT_NAME), 'IsPrimaryKey') = 1
    AND TABLE_NAME = '你的订单目标表名'
  

• 快速校验问题触发点
  临时把Sink的写入批次大小调整为1后运行管道：如果调整后不再报主键错误，可100%确认是单批次内同主键多记录导致的问题，验证完成后把批次大小改回1000~10000的常规性能配置即可，不需要长期保留批次=1的设置（性能损耗极高）。
• 校验Sink写入配置
  写入逻辑仅勾选「允许插入」「允许更新」即可，不要误开启「批量插入兼容」「跳过键匹配」类开关；如果目标是Azure SQL DB，确认表上没有配置异常触发器、没有手动开启IDENTITY_INSERT，避免写入逻辑绕过Upsert判断直接走纯插入路径。

补充：订单类事件流本身存在乱序到达的可能，前置增加按事件时间取最新记录的逻辑，除了解决主键冲突，还能避免早到的旧更新事件反向覆盖新状态的问题。

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