Node.js 中的 DynamoDB BatchWriteItem(AWS SDK v3)
BatchWriteItem 在单次请求中写入或删除多达 25 个项目(合计 16 MB,每项 400 KB)。在 AWS SDK v3 中,你发送一个 BatchWriteItemCommand,其 RequestItems 混合了 PutRequest 和 DeleteRequest 条目——而且你必须对 UnprocessedItems 进行循环,因为整个批次并非原子操作。
Code
import {BatchWriteItemCommand, DynamoDBClient} from '@aws-sdk/client-dynamodb';
const client = new DynamoDBClient({region: 'us-east-1'});
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
let requestItems = {
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'}}
}
}
]
};
let attempt = 0;
do {
const response = await client.send(new BatchWriteItemCommand({RequestItems: requestItems}));
// Writes that were throttled come back in UnprocessedItems — resubmit them
// with exponential backoff until the map is empty.
requestItems = response.UnprocessedItems;
if (requestItems && Object.keys(requestItems).length > 0) {
attempt += 1;
await sleep(Math.min(100 * 2 ** attempt, 5000));
}
} while (requestItems && Object.keys(requestItems).length > 0);
console.log('Batch written');说明
RequestItems— 一个表名 → 至多 25 个PutRequest/DeleteRequest条目数组的映射(一次请求可以跨多张表)。每个PutRequest.Item需要完整主键;每个DeleteRequest.Key只需键即可。- 不是事务 — 每个 put/delete 单独看是原子的,但整个批次不是:有些写入可能成功,而另一些被限流。需要全有或全无?请使用 TransactWriteItems。
UnprocessedItems— 重试循环不是可选的。被限流的写入会以RequestItems形式返回到这里,可直接重新提交;AWS 强烈建议在两次尝试之间使用指数退避。- 无更新、无条件 —
BatchWriteItem无法表达UpdateItem、ConditionExpression或ReturnValues;对已存在键的 put 会静默地替换整个项目。重复键、对同一项目混合 put+delete、超过 25 个请求、单项超过 400 KB,或合计超过 16 MB,都会导致 DynamoDB 拒绝整个批次。 - 批处理节省的是往返次数,而非容量:每个 put/delete 消耗的 WCU 与单独执行时相同(对不存在项目的 delete 仍会消耗一个 WCU)。
可视化操作
不想手工拼装 DynamoDB-JSON 项目?DynamoDB Expression Builder 会构建带类型的值映射并复制可运行代码,而项目大小计算器会在发送前对照 400 KB 上限检查每个项目。
想在 GUI 中批量添加、编辑和删除项目——无需编写重试循环——请下载 DynoTable。
相关示例
- Python 中的 DynamoDB 批量写入 — boto3 的
batch_writer()会替你完成重试循环。 - 使用 AWS CLI 的 DynamoDB BatchWriteItem — 在 shell 中完成同样的批量写入。
- Node.js 中的 DynamoDB TransactWriteItems — 当这些写入必须一起成功或一起失败时。
- DynamoDB 中的批量操作 — 限制、部分失败,以及批处理何时划算。
- "Too many items requested for the BatchWriteItem call" — 一个批次中超过 25 个 put/delete 请求。
- "Provided list of item keys contains duplicates" — 一个批次中两个请求触及同一个键。
References
- BatchWriteItem — Amazon DynamoDB API Reference
- Error handling with DynamoDB — Amazon DynamoDB Developer Guide
- DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide
Last verified 2026-07-13 against the official AWS documentation linked above.