Java AWS SDK操作DynamoDB时遇“键元素不匹配架构”错误排查

错误原因 #

你的DynamoDB表使用复合主键（分区键driveUniqueId + 排序键createTime），而你在ConditionCheck中仅指定了分区键driveUniqueId，这不符合表的主键结构要求。

DynamoDB规定，所有针对单条记录的操作（包括ConditionCheck）必须提供完整的主键组合（分区键+排序键），才能唯一定位到某一条记录。仅传入分区键的话，DynamoDB无法确定你要检查的具体记录（同一分区键下可存在多条不同排序键的记录），因此抛出The provided key element does not match the schema错误。

正确配置方式 #

根据你“仅允许插入、禁止更新/替换”的需求，分两种场景给出解决方案：

1. 确保特定driveUniqueId+createTime组合仅插入一次 #

这是复合主键表的常规幂等插入场景，需在ConditionCheck中传入完整主键，并校验该主键对应的记录不存在：

// 构建ConditionCheck请求
ConditionCheck conditionCheck = ConditionCheck.builder()
    .tableName("你的表名")
    .key(Map.of(
        "driveUniqueId", AttributeValue.builder().s("目标driveId").build(),
        "createTime", AttributeValue.builder().s("目标时间字符串").build()
    ))
    .conditionExpression("attribute_not_exists(driveUniqueId)")
    .build();

// 组装事务写入请求
TransactWriteItemsRequest transactRequest = TransactWriteItemsRequest.builder()
    .transactItems(
        TransactWriteItem.builder().conditionCheck(conditionCheck).build(),
        TransactWriteItem.builder().put(你的PutItem请求实例).build()
    )
    .build();

这里利用“若记录存在则分区键必然存在”的特性，通过attribute_not_exists(driveUniqueId)确保只有当该主键组合的记录不存在时，事务才会执行。

2. 确保同一driveUniqueId下无任何记录 #

如果你的需求是禁止同一driveUniqueId创建任何多条记录，当前的复合主键设计无法直接用ConditionCheck实现——因为DynamoDB的ConditionCheck仅能针对单条记录，无法校验整个分区下的所有记录。

这种情况可选择两种调整方案：

• 修改表主键为仅driveUniqueId（移除排序键createTime），此时ConditionCheck仅传入driveUniqueId即可校验该分区是否存在记录。
• 新增全局二级索引（GSI），将driveUniqueId设为GSI的主键，先通过GSI查询该driveUniqueId是否存在记录（注意：事务中无法直接包含查询操作，需先执行查询再决定是否发起事务，该方式存在竞态风险）。

额外提示 #

使用Quarkus的DynamoDB扩展时，需确保构建键值时严格匹配表的主键字段名和类型，避免字段拼写错误或类型不匹配（比如误将字符串类型用n()方法构建而非s()）。

内容的提问来源于stack exchange，提问作者João Pedro Schmitt