DynamoDB BatchGetItem em Python (boto3)

batch_get_item busca até 100 itens por chave primária em uma única requisição (16 MB no máximo). Com o client de baixo nível do boto3 você passa um mapa RequestItems de tabela → chaves — e você precisa fazer loop sobre UnprocessedKeys, porque um batch pode legitimamente retornar apenas parte do que você pediu.

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

Explicação

RequestItems — um mapa de nome de tabela → {"Keys": [...]}; uma requisição pode abranger múltiplas tabelas. Cada chave deve ser a chave primária completa (partição + classificação para uma chave composta), em DynamoDB JSON ({"S": ...}, {"N": ...}). Mais de 100 chaves, ou a mesma chave duas vezes, gera uma ValidationException.
Responses — um mapa de nome de tabela → os itens encontrados. Os itens voltam em nenhuma ordem específica, e chaves que não existem simplesmente não aparecem — associe os resultados às requisições pelos atributos de chave.
UnprocessedKeys — o loop de retry acima não é opcional. Se a resposta passar de 16 MB, a capacidade se esgotar, ou a leitura de uma partição passar de 1 MB, o DynamoDB retorna o restante aqui no formato de RequestItems, pronto para ser realimentado diretamente (um mapa vazio significa concluído — falsy em Python, que é o que encerra o while). A AWS recomenda fortemente backoff exponencial entre as tentativas.
Consistência — leituras em batch têm consistência eventual por padrão; defina "ConsistentRead": True por tabela para leituras com consistência forte.
Por tabela você também pode passar ProjectionExpression (com ExpressionAttributeNames) para buscar apenas alguns atributos.
Prefere tipos nativos do Python em vez de DynamoDB JSON? A API resource oferece dynamodb.batch_get_item(...) com valores simples, mas o contrato de retry é o mesmo — UnprocessedKeys é sua para drenar de qualquer forma.

Faça visualmente

Prefere não montar à mão os mapas de chave em DynamoDB JSON? O DynamoDB Expression Builder constrói mapas tipados de chave/valor e copia código executável, e a calculadora de tamanho de item mostra o quão perto um batch chega do teto de 16 MB.

Para buscar e inspecionar itens entre tabelas numa GUI — sem loops de retry para escrever — baixe o DynoTable.

Exemplos relacionados

DynamoDB BatchGetItem em Node.js — a mesma leitura em batch com o AWS SDK v3.
DynamoDB BatchGetItem com a AWS CLI — a mesma leitura em batch a partir do shell.
DynamoDB GetItem em Python — a leitura de item único que isto agrupa.
Operações em batch no DynamoDB — limites, falha parcial e quando o batching compensa.
"Too many items requested for the BatchGetItem call" — mais de 100 chaves em uma requisição.
"Provided list of item keys contains duplicates" — a mesma chave duas vezes em um batch.

References

Última verificação em 2026-07-13 contra a documentação oficial da AWS vinculada acima.