用 AWS CLI 执行 DynamoDB BatchWriteItem

aws dynamodb batch-write-item 用一条命令写入或删除最多 25 个项目。在 shell 里它有两处 SDK 帮你磨平、而这里不会的锋利边角：每个值都是你必须正确转义的 DynamoDB JSON，而且 CLI 完全没有抽干 UnprocessedItems 的机制。相关限制和部分失败模型见 DynamoDB 批量操作。

代码

aws dynamodb batch-write-item \
  --request-items '{
    "Music": [
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"DeleteRequest": {"Key": {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}}}
    ]
  }'

跑在 DynamoDB Local 3.3.0 上，它打印出来的全部内容是：

{
    "UnprocessedItems": {}
}

说明

一个空的剩余项映射，就是你能拿到的唯一成功信号。这条命令只打印 UnprocessedItems，别的什么都没有，所以只检查退出状态的脚本会把一个写了一半的批次判为成功。要去解析这个映射；jq -e '.UnprocessedItems | length == 0' 就是全部的检查。
没有任何参数能把它抽干。aws dynamodb query help 提供 --starting-token、--max-items 和 --page-size。aws dynamodb batch-write-item help 一个都没有，因为 UnprocessedItems 不是分页游标。重新喂回去是一个带 sleep 的 shell 循环，而且它本来就已经是 --request-items 的形状了。
这里不接受 --condition-expression 和 --return-values，而这是 API 的规定，不是 CLI 的：条件无法附加到单个的 put 和 delete 请求上。每个 PutRequest 都会替换整个存储的项目，所以用不完整的载荷拼出来的批次，会把它漏掉的属性删掉。
一个坏条目要赔上全部 25 个。表不存在、键与模式不匹配、项目超过 400 KB、总量超过 16 MB、分区键超过 2048 字节或排序键超过 1024 字节，任何一种都会让整个批次被拒绝，而不是只拒绝那个出问题的条目。

这条命令打印什么，包括被拒绝的情况

给上面的代码块加上 --return-consumed-capacity TOTAL，DynamoDB Local 3.3.0 的回答是：

{
    "UnprocessedItems": {},
    "ConsumedCapacity": [
        {
            "TableName": "Music",
            "CapacityUnits": 3.0
        }
    ]
}

两次 put 加一次 delete，算三个单元：批次买到的是一次往返，不是折扣。每个条目都按它所代表的那次单独的 PutItem 或 DeleteItem 计费，向上取整到 1 KB。

在 Ella Fitzgerald / Misty 已经没了之后再跑一次删除，DynamoDB Local 为那一个 DeleteRequest 报告了 2.0 个单元。BatchWriteItem 参考文档（2026-07-28 取回）说，对不存在的项目做删除消耗一个写容量单元，而在同一个本地引擎上单独执行 delete-item 确实报告 1.0。把本地的容量数字当成方向性参考。无论如何都成立的那一点是：一次什么都没找到的删除，照样要计费。

有两种请求服务会直接拒绝，打到 stderr，退出状态为 254：

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Too many items requested for the BatchWriteItem call
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Provided list of item keys contains duplicates

第二个值得多盯一会儿。它是由同一个键上的一个 PutRequest 和一个 DeleteRequest 产生的，而不是两次 put。DynamoDB 把一个批次里针对同一个项目的第二次操作一律算作重复，所以「删掉旧行、写入新行」作为单个批次会失败，哪怕这两个条目看起来毫不相像。

在单引号里拼那些值映射，正是时间的去处。DynamoDB Expression Builder 会产出带类型的映射并复制出一条可直接运行的命令，这样失败至少是一次真正的失败，而不是一个跑偏的反斜杠。

要从 CSV 或 JSON 批量加载或清空项目、又不用转义其中任何一个字符，请下载 DynoTable。

参考资料

最后核实于 2026-07-28，依据上方链接的 AWS 官方文档。

用 AWS CLI 执行 DynamoDB BatchWriteItem

代码

说明

这条命令打印什么，包括被拒绝的情况

相关示例

参考资料