Gravação condicional no DynamoDB com a AWS CLI

Uma gravação condicional anexa uma --condition-expression a put-item, update-item ou delete-item: o DynamoDB a avalia contra o item atual e aplica a gravação apenas se ela for verdadeira — atomicamente, sem race de read-modify-write. É o primitivo de optimistic locking do DynamoDB. Este exemplo protege uma atualização com uma verificação de versão.

Code

aws dynamodb update-item \
  --table-name 'Music' \
  --key '{"Artist":{"S":"Arturo Sandoval"},"SongTitle":{"S":"Cubano Chant"}}' \
  --update-expression 'SET #upd0 = :updValue0, #version = :newVersion' \
  --condition-expression 'attribute_exists(#cond0) AND #version = :expectedVersion' \
  --expression-attribute-names '{"#upd0":"Genre","#version":"Version","#cond0":"Artist"}' \
  --expression-attribute-values '{":updValue0":{"S":"Latin Jazz"},":expectedVersion":{"N":"7"},":newVersion":{"N":"8"}}'

Em caso de sucesso o comando não imprime nada e sai com 0. Se outro gravador chegou lá primeiro, a condição falha:

An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation:
The conditional request failed

Explicação

--condition-expression — verificada contra o item armazenado atomicamente com a gravação. Funções disponíveis: attribute_exists, attribute_not_exists, attribute_type, contains, begins_with, size, mais comparadores (=, <>, <, >, <=, >=, BETWEEN, IN) e AND/OR/NOT.
Os dois idiomas de trabalho:
- attribute_exists(#key) em uma atualização = "somente-atualizar, nunca criar". Sem ele, update-item em uma chave ausente cria o item silenciosamente (o bug de upsert acidental).
- attribute_not_exists(#key) em um put = "somente-criar, nunca sobrescrever" — mostrado na página do PutItem.
Optimistic locking — leia o item (versão 7), depois grave com #version = :expectedVersion ao passar para 8. Dois gravadores concorrentes não podem ambos vencer; o perdedor sai com código diferente de zero com ConditionalCheckFailedException, relê e tenta de novo na nova versão.
--return-values-on-condition-check-failure ALL_OLD — pede ao DynamoDB para anexar o item atual à falha (valores válidos ALL_OLD | NONE; nenhuma capacidade de leitura consumida). Os SDKs expõem esse item na exceção; a saída de erro padrão da CLI imprime apenas a mensagem, então os scripts geralmente releem com get-item após uma falha.
Uma gravação condicional falha ainda cobra a tentativa de gravação — não use condições como uma sondagem de existência gratuita.

Faça visualmente

Condition expressions são exatamente o que o DynamoDB Expression Builder constrói — escolha a função, obtenha a expressão + mapas de nome/valor como um comando de CLI pronto para executar.

Para editar itens com expressões geradas e revisáveis em vez de placeholders entre aspas do shell — baixe o DynoTable.

Exemplos relacionados

Gravação condicional no DynamoDB em Node.js — o mesmo optimistic lock com o AWS SDK v3.
Gravação condicional no DynamoDB em Python — o mesmo optimistic lock com boto3.
DynamoDB PutItem com a AWS CLI — o put somente-criação com attribute_not_exists.
Condition expressions do DynamoDB — cada função, com padrões.
Entendendo ReturnValues — o que cada opção de retorno fornece.
DynamoDB ConditionalCheckFailedException — quando a verificação falha é esperada, e como tratá-la de forma barata.

References

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