Python (boto3 batch_writer) での DynamoDB バッチ書き込み

Python で DynamoDB アイテムを一括書き込みするイディオマティックな方法は、boto3 の batch_writer() コンテキストマネージャーです。プットと削除をバッファリングし、最大25個の BatchWriteItem 呼び出しとして送信し、未処理アイテムを自動で再送信します。他のすべての言語が手作業で書くリトライループです。

Code

import boto3

dynamodb = boto3.resource("dynamodb")
table = dynamodb.Table("Music")

songs = [
    {"Artist": "Arturo Sandoval", "SongTitle": "Cubano Chant", "AlbumTitle": "Danzon", "Year": 1994},
    {"Artist": "Arturo Sandoval", "SongTitle": "A Mis Abuelos", "AlbumTitle": "Danzon", "Year": 1994},
    {"Artist": "Arturo Sandoval", "SongTitle": "Groovin' High", "AlbumTitle": "Swingin'", "Year": 1996},
]

with table.batch_writer() as batch:
    for song in songs:
        batch.put_item(Item=song)
    batch.delete_item(Key={"Artist": "Ella Fitzgerald", "SongTitle": "Misty"})

print(f"Wrote {len(songs)} songs")

Explanation

batch_writer() — boto3 のドキュメントによれば、このハンドルは「バッファリングとアイテムのバッチ送信を自動的に処理」し、「未処理アイテムも自動的に処理して必要に応じて再送信」します。with ブロックを抜けると、まだバッファされているものすべてがフラッシュされます。
プレーンな Python 値 — これはリソースAPI です。DynamoDB JSON はなく、数値は int/Decimal です。各 put_item のアイテムにはテーブルの完全なプライマリキーを含める必要があります。delete_item はキーだけを取ります。
重複キー — 生の BatchWriteItem 呼び出しは、同じキーへの2つの書き込みを拒否します。ソースデータがキーを繰り返す可能性がある場合は、ライターを table.batch_writer(overwrite_by_pkeys=["Artist", "SongTitle"]) として構築してください。バッファを重複排除し、キーごとに最後の書き込みを保持します。
内部では同じサービス制限が適用されます。1リクエストあたり25書き込み、1アイテムあたり400 KB、1リクエストあたり16 MB です。batch_writer はチャンク化を処理しますが、1アイテムあたりの上限を引き上げることはできません。
更新なし、条件なし — BatchWriteItem は UpdateItem や ConditionExpression を表現できません。既存のキーへのプットはアイテムを静かに置き換えます。オール・オア・ナッシングや条件付き書き込みが必要ですか？TransactWriteItems を使いましょう。
代わりに低レベルクライアント（client.batch_write_item）を経由していますか？その場合、UnprocessedItems は自分で処理する必要があります。Node.js の例とまったく同じく、指数バックオフでループしてください。

Do it visually

一括ロードの前にアイテムを確認していますか？item size calculator は各アイテムを400 KB の上限に照らして検証し、DynamoDB Expression Builder は後続の読み書きのために実行可能な boto3 コードをコピーします。

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

DynamoDB BatchWriteItem in Node.js — batch_writer が隠す手動のリトライループ。
DynamoDB BatchWriteItem with the AWS CLI — シェルからの同じバッチ書き込み。
DynamoDB PutItem in Python — これがバッチ化する単一アイテムの書き込み。
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 ドキュメントに照らして確認しました。

Python (boto3 batch_writer) での DynamoDB バッチ書き込み

Code

Explanation

Do it visually

Related examples

References