DynamoDB BatchGetItem in Python (boto3)

batch_get_item recupera fino a 100 Item per chiave primaria in una sola richiesta (max 16 MB). Con il client di basso livello di boto3 passi una mappa RequestItems tabella → chiavi — e devi iterare su UnprocessedKeys, perché un batch può legittimamente restituire solo una parte di ciò che hai richiesto.

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")

Spiegazione

RequestItems — una mappa nome tabella → {"Keys": [...]}; una singola richiesta può interessare più tabelle. Ogni chiave deve essere la chiave primaria completa (partizione + ordinamento per una chiave composita), in DynamoDB JSON ({"S": ...}, {"N": ...}). Più di 100 chiavi, o la stessa chiave due volte, solleva una ValidationException.
Responses — una mappa nome tabella → gli Item trovati. Gli Item tornano in nessun ordine particolare, e le chiavi che non esistono semplicemente non compaiono — abbina i risultati alle richieste tramite i loro attributi chiave.
UnprocessedKeys — il ciclo di retry qui sopra non è opzionale. Se la risposta supera i 16 MB, la capacità si esaurisce, o la lettura di una partizione supera 1 MB, DynamoDB restituisce qui il resto in forma RequestItems, pronto da reinserire direttamente (una mappa vuota significa che è finito — falsy in Python, ed è ciò che termina il while). AWS raccomanda vivamente un backoff esponenziale tra i tentativi.
Coerenza — le letture batch sono a coerenza eventuale per impostazione predefinita; imposta "ConsistentRead": True per tabella per letture a coerenza forte.
Per ogni tabella puoi anche passare ProjectionExpression (con ExpressionAttributeNames) per recuperare solo alcuni attributi.
Preferisci i tipi nativi di Python invece di DynamoDB JSON? L'API resource offre dynamodb.batch_get_item(...) con valori semplici, ma il contratto di retry è lo stesso — UnprocessedKeys sta comunque a te svuotarlo.

Fallo visivamente

Preferisci non assemblare a mano le mappe di chiavi in DynamoDB JSON? Il DynamoDB Expression Builder costruisce mappe tipizzate chiave/valore e copia codice eseguibile, e il calcolatore delle dimensioni degli Item mostra quanto un batch si avvicina al limite di 16 MB.

Per recuperare e ispezionare gli Item tra le tabelle in una GUI — senza cicli di retry da scrivere — scarica DynoTable.

Esempi correlati

DynamoDB BatchGetItem in Node.js — la stessa lettura batch con AWS SDK v3.
DynamoDB BatchGetItem con la AWS CLI — la stessa lettura batch dalla shell.
DynamoDB GetItem in Python — la lettura di un singolo Item che questo raggruppa in batch.
Operazioni batch in DynamoDB — limiti, fallimenti parziali e quando conviene il batching.
"Too many items requested for the BatchGetItem call" — più di 100 chiavi in una sola richiesta.
"Provided list of item keys contains duplicates" — la stessa chiave due volte in un batch.

References

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.