AWS CLI での DynamoDB BatchWriteItem

aws dynamodb batch-write-item は、1 つのコマンドで 最大 25 件のアイテム を put または削除します。シェルから使うと、SDK が和らげてくれる 2 つの鋭い角が残ります。値はすべて正しくクォートしなければならない DynamoDB JSON であること、そして CLI に UnprocessedItems を汲み出す仕組みが一切ないことです。上限と部分的な失敗のモデルは DynamoDB のバッチ操作にあります。

コード

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

DynamoDB Local 3.3.0 に対して実行すると、出力はこれで全部です。

{
    "UnprocessedItems": {}
}

解説

空の残りマップが、得られる唯一の成功シグナルです。このコマンドは UnprocessedItems だけを出力し、それ以外は何も出しません。だから終了ステータスしか見ないスクリプトは、半分しか書けなかったバッチを成功と呼びます。マップをパースしましょう。jq -e '.UnprocessedItems | length == 0' がチェックのすべてです。
それを汲み出すフラグはありません。aws dynamodb query help は --starting-token、--max-items、--page-size を提供します。aws dynamodb batch-write-item help はそのどれも提供しません。UnprocessedItems はページネーションのカーソルではないからです。再投入は sleep 付きのシェルループの仕事であり、その中身は既に --request-items の形をしています。
--condition-expression と --return-values はここでは受け付けられません。これは CLI ではなく API の話です。個々の put および delete リクエストに条件は付けられません。すべての PutRequest は保存済みのアイテムを丸ごと置き換えるので、部分的なペイロードから組み立てたバッチは、含めなかった属性を消します。
インライン JSON ではなく file:// を使いましょう。--request-items file://writes.json は、間違いうるものリストからシェルのクォートを取り除きます。このコマンドで起きる問題の大半がクォートなので、これは効きます。
1 件の不正なエントリが 25 件すべてを台無しにします。存在しないテーブル、スキーマと一致しないキー、400 KB 超のアイテム、合計 16 MB 超、2048 バイトを超えるパーティションキー、1024 バイトを超えるソートキー — いずれも問題のエントリだけでなくバッチ全体を拒否します。

このコマンドが出力するもの、拒否も含めて

上のフェンスに --return-consumed-capacity TOTAL を足すと、DynamoDB Local 3.3.0 はこう答えます。

{
    "UnprocessedItems": {},
    "ConsumedCapacity": [
        {
            "TableName": "Music",
            "CapacityUnits": 3.0
        }
    ]
}

put 2 件と delete 1 件で 3 ユニット。バッチが買ったのは 1 回のラウンドトリップであって、割引ではありません。各エントリは、それが表す個別の PutItem または DeleteItem として、1 KB に切り上げて課金されます。

Ella Fitzgerald / Misty が既に消えた状態で delete をもう一度実行すると、DynamoDB Local はその単一の DeleteRequest に対して 2.0 ユニットを報告します。BatchWriteItem のリファレンス（2026-07-28 取得）は、存在しないアイテムへの delete は書き込みキャパシティユニットを 1 消費すると述べており、同じローカルエンジンに対する単体の delete-item は確かに 1.0 を報告します。ローカルのキャパシティ値は目安として扱いましょう。どちらにせよ残る要点は、何も見つけられなかった delete でも課金される、ということです。

サービスがきっぱり拒否するリクエストが 2 つあります。標準エラー出力に出て、終了ステータスは 254 です。

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Too many items requested for the BatchWriteItem call
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Provided list of item keys contains duplicates

2 つ目はじっと見る価値があります。これは put 2 件ではなく、同じキーに対する PutRequest と DeleteRequest で発生しました。DynamoDB は 1 つのバッチ内で 1 アイテムに対する 2 回目の操作をすべて重複とみなすので、「古い行を消して新しい行を書く」は、2 つのエントリがまるで似ていなくても単一のバッチとしては失敗します。

時間を食うのは、シングルクォートの中でこの値マップを組み立てる作業です。DynamoDB Expression Builder は型付きのマップを生成し、そのまま実行できるコマンドをコピーさせてくれるので、失敗したときそれは少なくとも本物の失敗であり、迷子のバックスラッシュではなくなります。

CSV や JSON から、何もエスケープせずにアイテムを一括投入したり消去したりするには、DynoTable をダウンロードしてください。

参考資料

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

AWS CLI での DynamoDB BatchWriteItem

コード

解説

このコマンドが出力するもの、拒否も含めて

関連する例

参考資料