DynamoDB BatchWriteItem com a AWS CLI

aws dynamodb batch-write-item grava ou exclui até 25 itens em um único comando. A partir do shell ele tem duas arestas afiadas que os SDKs suavizam: todo valor é JSON do DynamoDB que você precisa citar corretamente, e a CLI não tem mecanismo nenhum para esvaziar UnprocessedItems. Os limites e o modelo de falha parcial estão em operações em lote no DynamoDB.

Código

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"}}}}
    ]
  }'

Executado contra o DynamoDB Local 3.3.0, isso imprime, na íntegra:

{
    "UnprocessedItems": {}
}

Explicação

Um mapa de sobras vazio é o único sinal de sucesso que você recebe. O comando imprime UnprocessedItems e nada mais, então um script que verifica só o status de saída vai chamar de sucesso um lote gravado pela metade. Parseie o mapa; jq -e '.UnprocessedItems | length == 0' é toda a verificação.
Não existe flag para esvaziá-lo. aws dynamodb query help oferece --starting-token, --max-items e --page-size. aws dynamodb batch-write-item help não oferece nenhum deles, porque UnprocessedItems não é um cursor de paginação. Realimentá-lo é um loop de shell com um sleep, e ele já vem no formato de --request-items.
--condition-expression e --return-values não são aceitos aqui, e isso é da API, não da CLI: condições não podem ser anexadas a requisições individuais de put e delete. Todo PutRequest substitui o item armazenado inteiro, então um lote montado a partir de um payload parcial exclui os atributos que ele deixou de fora.
Uma entrada ruim custa as 25. Uma tabela inexistente, uma chave que não corresponde ao schema, um item acima de 400 KB, mais de 16 MB no total, uma chave de partição acima de 2048 bytes ou uma chave de ordenação acima de 1024 bytes rejeitam cada uma o lote inteiro, e não a entrada culpada.

O que o comando imprime, incluindo as rejeições

Acrescente --return-consumed-capacity TOTAL ao bloco acima e o DynamoDB Local 3.3.0 responde:

{
    "UnprocessedItems": {},
    "ConsumedCapacity": [
        {
            "TableName": "Music",
            "CapacityUnits": 3.0
        }
    ]
}

Três unidades para dois puts e um delete: o lote comprou uma ida e volta, não um desconto. Cada entrada é cobrada como o PutItem ou DeleteItem individual que ela representa, arredondado para cima para 1 KB.

Execute o delete uma segunda vez, quando Ella Fitzgerald / Misty já sumiu, e o DynamoDB Local reporta 2.0 unidades para aquele único DeleteRequest. A referência de BatchWriteItem (consultada em 2026-07-28) diz que um delete em um item inexistente consome uma unidade de capacidade de escrita, e um delete-item isolado contra o mesmo motor local de fato reporta 1.0. Trate os números de capacidade locais como direcionais. O ponto que sobrevive de qualquer forma é que um delete que não encontra nada ainda é cobrado.

Duas requisições o serviço recusa de imediato, em stderr, com status de saída 254:

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Too many items requested for the BatchWriteItem call
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchWriteItem operation: Provided list of item keys contains duplicates

A segunda merece uma boa olhada. Ela foi produzida por um PutRequest e um DeleteRequest na mesma chave, não por dois puts. O DynamoDB conta qualquer segunda operação sobre um item no mesmo lote como duplicata, então "excluir a linha antiga e gravar a nova" falha como lote único, mesmo com as duas entradas não se parecendo em nada.

Montar aqueles mapas de valores dentro de aspas simples é onde o tempo vai. O DynamoDB Expression Builder produz mapas tipados e copia um comando pronto para executar, de modo que uma falha seja pelo menos uma falha real, e não uma barra invertida perdida.

Para carregar em massa ou limpar itens a partir de CSV ou JSON sem escapar nada disso, baixe o DynoTable.

Exemplos relacionados

DynamoDB BatchWriteItem em Node.js — a mesma escrita em lote com o AWS SDK v3.
Escrita em lote no DynamoDB em Python — o batch_writer() do boto3 faz o loop de retry por você.
DynamoDB PutItem com a AWS CLI — a escrita de item único que isto agrupa em lote.
Operações em lote no DynamoDB — limites, falha parcial e quando o lote compensa.
"Too many items requested for the BatchWriteItem call" — mais de 25 requisições de put/delete em um lote.
"Provided list of item keys contains duplicates" — duas requisições tocando a mesma chave em um lote.

Referências

Verificado pela última vez em 2026-07-28 contra a documentação oficial da AWS vinculada acima.