AWS CLI での DynamoDB BatchWriteItem

aws dynamodb batch-write-item は、1つのコマンドで最大25個のアイテムをプットまたは削除します（合計16 MB、1アイテムあたり400 KB）。書き込みは --request-items に、テーブル → PutRequest/DeleteRequest エントリのマップとして DynamoDB JSON で渡します。そして出力の UnprocessedItems を必ず確認してください。バッチ全体はアトミックではないからです。

Code

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"}}}}
    ]
  }'

すべてが反映されると、出力の残りマップは空になります。

{
    "UnprocessedItems": {}
}

Explanation

--request-items — テーブル名 → 最大25個の PutRequest/DeleteRequest エントリの配列のマップ（1つのコマンドが複数のテーブルにまたがることもできます）。各 PutRequest.Item には完全なプライマリキーが必要です。各 DeleteRequest.Key はキーだけです。値は DynamoDB JSON で、数値は N の下では文字列です。
トランザクションではない — 各プット/削除は個別にはアトミックですが、バッチ全体はそうではありません。オール・オア・ナッシングが必要ですか？transact-write-items を使いましょう。
UnprocessedItems — CLI は部分的なバッチを自動リトライしません。マップが空でない場合（通常はスロットリングが原因）は、その正確なマップを --request-items として再実行し（すでに正しい形式です）、試行の合間にバックオフを入れてください。
更新なし、条件なし — batch-write-item は update-item、--condition-expression、--return-values を表現できません。既存のキーへのプットはアイテム全体を静かに置き換えます。重複キー、同じアイテムへのプット+削除、25個を超えるリクエスト、400 KB を超えるアイテム、合計16 MB 超は、いずれも DynamoDB にバッチ全体を拒否させます。
ヒント: マップをファイルに保持して --request-items file://writes.json を渡しましょう。25個のアイテムをインラインでシェルクォートするのは苦行です。

Do it visually

シェルのクォート内で入れ子の DynamoDB JSON を手書きするのはミスを招きます。DynamoDB Expression Builder は型付きの値マップを構築してすぐに実行できる CLI コマンドをコピーし、item size calculator は各アイテムを400 KB の上限に照らして確認します。

アイテムを GUI で一括追加・編集・削除するには（JSON エスケープの代わりに CSV/JSON インポート）、DynoTable をダウンロードしてください。

DynamoDB BatchWriteItem in Node.js — AWS SDK v3 での同じバッチ書き込み。
DynamoDB batch write in Python — boto3 の batch_writer() がリトライループを代わりに行います。
DynamoDB PutItem with the AWS CLI — これがバッチ化する単一アイテムの書き込み。
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 ドキュメントに照らして確認しました。

AWS CLI での DynamoDB BatchWriteItem

Code

Explanation

Do it visually

Related examples

References