Escrita em batch no DynamoDB em Python (boto3 batch_writer)

A forma idiomática de gravar itens do DynamoDB em massa em Python é o context manager batch_writer() do boto3: ele faz buffer dos seus puts e deletes, envia-os como chamadas BatchWriteItem de até 25, e refaz automaticamente os itens não processados — o loop de retry que toda outra linguagem escreve à mão.

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

Explicação

batch_writer() — segundo a documentação do boto3, o handle "will automatically handle buffering and sending items in batches" e "will also automatically handle any unprocessed items and resend them as needed". Sair do bloco with faz o flush do que ainda estiver em buffer.
Valores simples do Python — esta é a API resource: sem DynamoDB JSON, números como int/Decimal. Cada item de put_item deve incluir a chave primária completa da tabela; delete_item recebe apenas a chave.
Chaves duplicadas — uma chamada BatchWriteItem crua rejeita duas gravações para a mesma chave. Se seus dados de origem podem repetir chaves, construa o writer como table.batch_writer(overwrite_by_pkeys=["Artist", "SongTitle"]) — ele deduplica o buffer, mantendo a última gravação por chave.
Os mesmos limites de serviço se aplicam por baixo: 25 gravações por requisição, 400 KB por item, 16 MB por requisição. O batch_writer cuida do fatiamento; ele não pode elevar o limite por item.
Sem updates, sem condições — BatchWriteItem não consegue expressar UpdateItem nem uma ConditionExpression; um put em uma chave existente substitui o item silenciosamente. Precisa de tudo-ou-nada ou de gravações condicionais? Use TransactWriteItems.
Indo pelo client de baixo nível em vez disso (client.batch_write_item)? Então UnprocessedItems é sua para drenar — faça o loop com backoff exponencial exatamente como no exemplo em Node.js.

Faça visualmente

Verificando seus itens antes de uma carga em massa? A calculadora de tamanho de item valida cada item contra o limite de 400 KB, e o DynamoDB Expression Builder copia código boto3 executável para as leituras e gravações de acompanhamento.

Para adicionar, editar e excluir itens em massa numa GUI — importação de CSV/JSON incluída — baixe o DynoTable.

Exemplos relacionados

DynamoDB BatchWriteItem em Node.js — o loop de retry manual que o batch_writer esconde.
DynamoDB BatchWriteItem com a AWS CLI — a mesma escrita em batch a partir do shell.
DynamoDB PutItem em Python — a gravação 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 BatchWriteItem call" — mais de 25 requisições de put/delete em um batch.
"Provided list of item keys contains duplicates" — duas requisições tocando a mesma chave em um batch.

References

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