Node.js (AWS SDK v3) での DynamoDB BatchWriteItem

BatchWriteItem は、1回のリクエストで最大25個のアイテムをプットまたは削除します（合計16 MB、1アイテムあたり400 KB）。AWS SDK v3 では、RequestItems が PutRequest と DeleteRequest のエントリを混在させる BatchWriteItemCommand を送信します。そして 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');

Explanation

RequestItems — テーブル名 → 最大25個の PutRequest/DeleteRequest エントリの配列のマップ（1回のリクエストが複数のテーブルにまたがることもできます）。各 PutRequest.Item には完全なプライマリキーが必要です。各 DeleteRequest.Key はキーだけです。
トランザクションではない — 各プット/削除は個別にはアトミックですが、バッチ全体はそうではありません。一部の書き込みが成功する一方で、他がスロットルされることがあります。オール・オア・ナッシングが必要ですか？TransactWriteItems を使いましょう。
UnprocessedItems — リトライループは任意ではありません。スロットルされた書き込みはここに RequestItems 形式で返り、再投入できるようになっています。AWS は試行の合間に指数バックオフを強く推奨しています。
更新なし、条件なし — BatchWriteItem は UpdateItem、ConditionExpression、ReturnValues を表現できません。既存のキーへのプットはアイテム全体を静かに置き換えます。重複キー、同じアイテムでのプット+削除の混在、25個を超えるリクエスト、400 KB を超えるアイテム、合計16 MB 超は、いずれも DynamoDB にバッチ全体を拒否させます。
バッチ化が節約するのはラウンドトリップであってキャパシティではありません。各プット/削除は個別に行う場合と同じ WCU を課金します（存在しないアイテムに対する削除でも1 WCU を課金します）。

Do it visually

DynamoDB JSON のアイテムを手作業で組み立てたくないですか？DynamoDB Expression Builder は型付きの値マップを構築して実行可能なコードをコピーし、item size calculator は送信前に各アイテムを400 KB の上限に照らして確認します。

アイテムを GUI で一括追加・編集・削除するには（書くべきリトライループなし）、DynoTable をダウンロードしてください。

DynamoDB batch write in Python — boto3 の batch_writer() がリトライループを代わりに行います。
DynamoDB BatchWriteItem with the AWS CLI — シェルからの同じバッチ書き込み。
DynamoDB TransactWriteItems in Node.js — 書き込みがまとめて成功または失敗する必要があるとき。
Batch operations in DynamoDB — 制限、部分的な失敗、そしてバッチ化が割に合うのはいつか。
"Too many items requested for the BatchWriteItem call" — 1つのバッチに25個を超えるプット/削除リクエスト。
"Provided list of item keys contains duplicates" — 1つのバッチで同じキーに触れる2つのリクエスト。

References

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

Node.js (AWS SDK v3) での DynamoDB BatchWriteItem

Code

Explanation

Do it visually

Related examples

References