DynamoDB BatchWriteItem com a AWS CLI

aws dynamodb batch-write-item grava ou exclui até 25 itens em um único comando (16 MB no total, 400 KB por item). As gravações vão em --request-items como um mapa de tabela → entradas PutRequest/DeleteRequest em DynamoDB JSON — e você precisa verificar UnprocessedItems na saída, porque o batch como um todo não é atômico.

Code

aws dynamodb batch-write-item \
  --request-items '{
    "Music": [
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"DeleteRequest": {"Key": {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}}}
    ]
  }'

Quando tudo é gravado, o mapa de restantes da saída fica vazio:

{
    "UnprocessedItems": {}
}

Explicação

--request-items — um mapa de nome de tabela → um array de até 25 entradas PutRequest/DeleteRequest (um comando pode abranger múltiplas tabelas). Cada PutRequest.Item precisa da chave primária completa; cada DeleteRequest.Key é apenas a chave. Os valores são DynamoDB JSON — números são strings sob N.
Não é uma transação — cada put/delete é atômico individualmente, mas o batch como um todo não é. Precisa de tudo-ou-nada? Use transact-write-items.
UnprocessedItems — a CLI não faz retry automático de um batch parcial. Se o mapa estiver não vazio (throttling é a causa habitual), reexecute o comando com aquele mapa exato como --request-items — ele já está no formato certo — aplicando backoff entre as tentativas.
Sem updates, sem condições — batch-write-item não consegue expressar update-item, --condition-expression nem --return-values; um put em uma chave existente substitui o item inteiro silenciosamente. Chaves duplicadas, put+delete no mesmo item, >25 requisições, um item de >400 KB, ou >16 MB no total fazem o DynamoDB rejeitar o batch inteiro.
Dica: mantenha o mapa em um arquivo e passe --request-items file://writes.json — fazer escape de aspas de shell para 25 itens inline é um sofrimento.

Faça visualmente

Escrever DynamoDB JSON aninhado dentro de aspas do shell à mão é propenso a erros. O DynamoDB Expression Builder constrói mapas tipados de valor e copia comandos de CLI prontos para executar, e a calculadora de tamanho de item verifica cada item contra o limite de 400 KB.

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

Exemplos relacionados

DynamoDB BatchWriteItem em Node.js — a mesma escrita em batch com o AWS SDK v3.
Escrita em batch no DynamoDB em Python — o batch_writer() do boto3 faz o loop de retry por você.
DynamoDB PutItem com a AWS CLI — 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.