DynamoDB ReturnValues: Obtenha o item antigo ou novo

Por padrão, uma gravação DynamoDB retorna apenas sucesso. Mas muitas vezes você precisa dos dados em torno da gravação - o valor antes de você alterá-lo ou o novo valor depois. O A solução ingênua é um segundo GetItem, que é uma viagem extra de ida e volta e uma corrida: alguém caso contrário, você pode escrever no meio. DynamoDB evita ambos com o parâmetro ReturnValues, que devolve o item antigo ou novo atomicamente como parte da própria gravação.

O que ReturnValues faz no DynamoDB?

ReturnValues diz a um DynamoDB para devolver o item como parte da mesma chamada, então você pula um segundo GetItem e a corrida que ele cria. PutItem e DeleteItem aceitam NONE ou ALL_OLD; UpdateItem aceita todos os cinco (NONE, ALL_OLD, UPDATED_OLD, ALL_NEW, UPDATED_NEW), retornando valores antigos ou novos atomicamente.

ReturnValues retorna o item como parte da gravação — sem segunda leitura, sem corrida.
NONE (padrão) — não retorna nada.
ALL_OLD — o item inteiro como estava antes da gravação.
UPDATED_OLD — apenas os atributos que a atualização alterou, valores antes.
ALL_NEW — o item inteiro após a gravação.
UPDATED_NEW — apenas os atributos alterados, após os valores.
PutItem/DeleteItem aceita apenas NONE ou ALL_OLD; UpdateItem aceita todos cinco.

O problema: você precisa do valor que acabou de sobrescrever

Digamos que você administre uma central de suporte e um agente altere o status de um ticket de open para pending. Seu log de auditoria precisa registrar qual era o status antes da alteração. Sem o ReturnValues você:

GetItem para ler o status atual,
UpdateItem para definir o novo.

Entre as etapas 1 e 2, outro agente pode alterar o status — agora seu log de auditoria registra um valor "antes" obsoleto. Pior ainda, são duas chamadas para uma operação lógica. ReturnValues o recolhe em um único UpdateItem atômico que retorna o status antigo, pois na verdade, estava na hora da gravação.

As cinco opções e quando usar cada uma

UpdateItem suporta o conjunto completo; a escolha é que fatia do item e qual lado do write você precisa:

`ReturnValues`	Devoluções	Use quando
`NONE`	nada	você não precisa do item de volta (padrão)
`ALL_OLD`	item inteiro, pré-escrever	auditoria / "o que acabei de substituir?"
`UPDATED_OLD`	atributos alterados, pré-gravação	você só se preocupa com os campos que tocou
`ALL_NEW`	item inteiro, pós-gravação	você precisa do novo item completo para retornar a um chamador
`UPDATED_NEW`	atributos alterados, pós-gravação	lendo um contador/value que você acabou de incrementar

UPDATED_NEW é o herói do dia a dia: incremente um contador com um expressão de atualização e leia o novo total novamente a mesma chamada, sem corrida. Para a auditoria de tickets de suporte, ALL_OLD (ou UPDATED_OLD se você registra apenas o campo de status) captura o estado pré-alteração atomicamente.

Observe a assimetria: PutItem e DeleteItem suportam apenas NONE e ALL_OLD — não há nenhum valor "novo" para retornar para uma exclusão, e o novo valor de uma put é exatamente o que você enviado. Apenas o UpdateItem, que sofre mutação, oferece todos os cinco. Documentos AWS a matriz exata.

Escrevendo a atualização no DynoTable

Monte o UpdateItem e sua expressão de atualização visualmente com o Construtor de expressão DynamoDB — emite o Cláusula SET/ADD mais o nome do atributo e mapas de valor. No aplicativo, DynoTable mostra o item resultante após a confirmação de uma gravação preparada, para que você veja o novo estado diretamente.

Revisando a mudança gradual de um item no DynoTable — os valores antigos e novos antes da atualização ser confirmada.

Armadilhas + próximos passos

Não escreva GetItem para ler sobre uma mudança - é uma viagem de ida e volta e uma corrida; use ReturnValues.
UPDATED_* retorna apenas atributos tocados — se você precisar do item inteiro, use ALL_*.
PutItem/DeleteItem não pode retornar novos valores — apenas NONE/ALL_OLD.
ReturnValues não substitui uma condição — para proteger uma gravação, adicione um expressão de condição; para ler novamente seu efeito, use ReturnValues. Eles compõem.
Relacionado: expressões de atualização, contadores atômicos.

Quer fazer edições e ver o before/after sem fazer script de duas chamadas? Baixe DynoTable e edite seus itens diretamente.

Contador atômico com `UPDATED_NEW`

Os sistemas de inventário incrementam um campo version ou stock em cada gravação. O padrão é um UpdateItem com ADD stock :inc e ReturnValues: ATUALIZADO_NEW:

UpdateItem  PK=SKU#8842
  UpdateExpression: ADD stock :one
  ExpressionAttributeValues: {":one": {"N": "1"}}
  ReturnValues: UPDATED_NEW
→ Attributes.stock.N == "41"   (was 40)

Você recebe apenas o mapa de atributos alterado, não o item completo — ideal quando o o item é grande, mas o chamador precisa do novo contador. Para trilhas de auditoria que devem capture todos os campos antes da alteração, mude para ALL_OLD.

A gravação ainda é cobrada como UpdateItem no tamanho do item; ReturnValues faz não adicione uma cobrança de leitura separada – DynamoDB já carregou o item para aplicar o atualizar.

Nota sobre capacidade

O retorno de atributos não duplica o custo WCU da gravação em si. Você paga para gravação com base no tamanho do item antes e depois da atualização por AWS regras, independentemente de quantos atributos aparecem na carga útil da resposta.

Se você ficou tentado a usar GetItem e depois UpdateItem para registrar o valor antigo, você pago por uma leitura mais uma gravação. ReturnValues: ALL_OLD na atualização remove o leia inteiramente - em um item de 2 KB com 500 atualizações por segundo, o que economiza aproximadamente 250 RCU eventualmente consistentes por segundo.

Componha com expressões de condição

ReturnValuese expressões de condição compostas no mesma chamada. Exemplo: incrementarretryCount apenas enquanto estiver abaixo de um limite e retornar o nova contagem:

ConditionExpression: retryCount < :max
UpdateExpression: ADD retryCount :one
ReturnValues: UPDATED_NEW

Se a condição falhar, DynamoDB retornará ConditionalCheckFailedException e sem carga útil de atributo - diferente de uma atualização bem-sucedida com um vazio UPDATED_NEW quando nada mudou.

Use o construtor de expressão para gerar o UpdateExpression, condição e mapas de valor organizados juntos.

Guia de decisão

Você precisa…	Configuração	Funciona em
Nada de volta	`NONE`	Colocar, atualizar, excluir
Item completo antes de substituir/delete	`ALL_OLD`	Colocar, atualizar, excluir
Apenas campos alterados, antes	`UPDATED_OLD`	Atualização
Item completo após patch	`ALL_NEW`	Atualização
Apenas campos alterados, após	`UPDATED_NEW`	Atualização

Exclui e coloca

DeleteItem com ReturnValues: ALL_OLD é como você implementa "pop and return" semântica em um item da fila — a linha excluída volta em Attributes. Há não há ALL_NEW na exclusão porque o item não existe mais.

PutItem com ALL_OLD retorna o item anterior quando você substitui um item existente key — útil para fluxos de trabalho de troca. Quando a chave não existia, a resposta omite Attributes.

Verifique em DynoTable

Preparar uma alteração de atributo no editor de itens: o painel de revisão mostra o antigo e o novo valores lado a lado antes do commit - as mesmas informações UPDATED_OLD e UPDATED_NEW retornaria sem escrever um script. Após o commit, copie a linha como JSON para dispositivos de teste através das ações de exportação da rede.