Python (boto3) での DynamoDB BatchGetItem

batch_get_item は、1回のリクエストでプライマリキーによって最大100個のアイテムを取得します（最大16 MB）。boto3 の低レベルクライアントでは、テーブル → キーの RequestItems マップを渡します。そして UnprocessedKeys を必ずループ処理する必要があります。バッチは、要求した内容の一部だけを正当に返すことがあるからです。

Code

import time

import boto3

client = boto3.client("dynamodb")

request_items = {
    "Music": {
        "Keys": [
            {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
            {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}},
            {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}},
        ]
    }
}

items = []
attempt = 0

while request_items:
    response = client.batch_get_item(RequestItems=request_items)
    items.extend(response["Responses"].get("Music", []))

    # A partial result is NOT an error: throttling, a >16 MB response, or an
    # internal failure returns the leftovers in UnprocessedKeys. Retry them
    # with exponential backoff.
    request_items = response["UnprocessedKeys"]
    if request_items:
        attempt += 1
        time.sleep(min(0.1 * 2**attempt, 5))

print(f"Fetched {len(items)} items")

Explanation

RequestItems — テーブル名 → {"Keys": [...]} のマップ。1回のリクエストが複数のテーブルにまたがることもできます。各キーは完全なプライマリキー（複合キーならパーティション + ソート）を DynamoDB JSON（{"S": ...}、{"N": ...}）で指定する必要があります。100個を超えるキー、または同じキーが2回あると ValidationException を発生させます。
Responses — テーブル名 → 見つかったアイテムのマップ。アイテムは特定の順序なしで返り、存在しないキーは単に現れません。結果はキー属性でリクエストと突き合わせてください。
UnprocessedKeys — 上記のリトライループは任意ではありません。レスポンスが16 MB を超えたり、スループットが尽きたり、パーティション読み取りが1 MB を超えると、DynamoDB は残りをここに RequestItems 形式で返し、そのまま再投入できるようになっています（空のマップは完了を意味します。Python では偽値であり、これが while を終わらせます）。AWS はリトライの合間に指数バックオフを強く推奨しています。
整合性 — バッチ読み取りはデフォルトで結果整合性です。強い整合性のある読み取りにはテーブルごとに "ConsistentRead": True を設定します。
テーブルごとに ProjectionExpression（ExpressionAttributeNames とともに）を渡して、一部の属性だけを取得することもできます。
DynamoDB JSON ではなくネイティブな Python 型がほしいですか？リソースAPI は dynamodb.batch_get_item(...) をプレーンな値で提供しますが、リトライの契約は同じです。UnprocessedKeys はいずれにせよ自分で処理する必要があります。

Do it visually

DynamoDB JSON のキーマップを手作業で組み立てたくないですか？DynamoDB Expression Builder は型付きのキー/値マップを構築して実行可能なコードをコピーし、item size calculator はバッチが16 MB の上限にどれだけ近づくかを示します。

複数のテーブルにまたがってアイテムを GUI で取得・確認するには（書くべきリトライループなし）、DynoTable をダウンロードしてください。

DynamoDB BatchGetItem in Node.js — AWS SDK v3 での同じバッチ読み取り。
DynamoDB BatchGetItem with the AWS CLI — シェルからの同じバッチ読み取り。
DynamoDB GetItem in Python — これがバッチ化する単一アイテムの読み取り。
Batch operations in DynamoDB — 制限、部分的な失敗、そしてバッチ化が割に合うのはいつか。
"Too many items requested for the BatchGetItem call" — 1つのリクエストに100個を超えるキー。
"Provided list of item keys contains duplicates" — 1つのバッチに同じキーが2回。

References

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

Python (boto3) での DynamoDB BatchGetItem

Code

Explanation

Do it visually

Related examples

References