在 Node.js（AWS SDK v3）中使用 DynamoDB BatchWriteItem

BatchWriteItem 在單一請求中 put 或 delete 多達 25 個項目（合計 16 MB，每個項目 400 KB）。在 AWS SDK v3 中，你送出一個 BatchWriteItemCommand，其 RequestItems 混合 PutRequest 與 DeleteRequest 項目 — 而你必須對 UnprocessedItems 進行迴圈，因為整個批次並非 atomic。

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 項目陣列的 map（一個請求可橫跨多個表格）。每個 PutRequest.Item 需要完整的 primary key；每個 DeleteRequest.Key 只需 key。
不是交易 — 每個 put/delete 各自是 atomic，但整個批次不是：有些寫入可能成功，而其他被節流。需要全有或全無？請用 TransactWriteItems。
UnprocessedItems — 重試迴圈並非選用。被節流的寫入會以 RequestItems 形式回到這裡，可直接重送；AWS 強烈建議在嘗試之間採用指數退避。
不支援更新、不支援條件 — BatchWriteItem 無法表達 UpdateItem、ConditionExpression 或 ReturnValues；對既有 key 的 put 會靜默取代整個項目。重複的 key、對同一項目混合 put+delete、超過 25 個請求、超過 400 KB 的項目，或合計超過 16 MB，都會讓 DynamoDB 拒絕整個批次。
批次省下的是往返，而非容量：每個 put/delete 都與各自單獨執行時計費相同的 WCU（對不存在的項目 delete 仍計 1 個 WCU）。

改用視覺化操作

不想手動組裝 DynamoDB-JSON 項目？DynamoDB Expression Builder 會建立帶型別的 value map 並複製可執行的程式碼，而項目大小計算機會在你送出前對照 400 KB 上限檢查每個項目。

想在 GUI 中大量新增、編輯與刪除項目 — 不需自己寫重試迴圈 — 下載 DynoTable。

References

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。

在 Node.js（AWS SDK v3）中使用 DynamoDB BatchWriteItem

Code

說明

改用視覺化操作

相關範例

References