Node.js 中的 DynamoDB BatchWriteItem(AWS SDK v3)

BatchWriteItem 在单次请求中写入或删除多达 25 个项目(合计 16 MB,每项 400 KB)。在 AWS SDK v3 中,你发送一个 BatchWriteItemCommand,其 RequestItems 混合了 PutRequestDeleteRequest 条目——而且你必须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 无法表达 UpdateItemConditionExpressionReturnValues;对已存在键的 put 会静默地替换整个项目。重复键、对同一项目混合 put+delete、超过 25 个请求、单项超过 400 KB,或合计超过 16 MB,都会导致 DynamoDB 拒绝整个批次。
  • 批处理节省的是往返次数,而非容量:每个 put/delete 消耗的 WCU 与单独执行时相同(对不存在项目的 delete 仍会消耗一个 WCU)。

可视化操作

不想手工拼装 DynamoDB-JSON 项目?DynamoDB Expression Builder 会构建带类型的值映射并复制可运行代码,而项目大小计算器会在发送前对照 400 KB 上限检查每个项目。

想在 GUI 中批量添加、编辑和删除项目——无需编写重试循环——请下载 DynoTable

相关示例

References

Last verified 2026-07-13 against the official AWS documentation linked above.

无需控制台即可使用 DynamoDB

DynoTable 是面向 DynamoDB 的快速桌面客户端 —— 浏览表、运行 SQL 风格的查询,并在本地编辑项。