Ações baseadas em itens DynamoDB

O API do DynamoDB se divide em três famílias: ações baseadas em itens que funcionam em um único item por sua chave primária, Query que lê um intervalo dentro de uma partição, e Scan que lê tudo. Este guia é a primeira família — as quatro operações você mais usa: GetItem, PutItem, UpdateItem, DeleteItem. Eles são os mais baratos, chamadas mais rápidas que o DynamoDB oferece e acertar suas distinções (especialmente Put vs Update) evita uma classe de bugs de perda acidental de dados.

Quais são as operações baseadas em itens do DynamoDB?

As operações baseadas em item do DynamoDB são as quatro chamadas que atuam em um único item por sua chave primária completa: GetItem o lê, PutItem o cria ou substitui completamente, UpdateItem modifica atributos específicos no local e DeleteItem o remove. Cada um aborda exatamente um item, tornando-as as chamadas mais rápidas e baratas — ao contrário de Query and Scan, que lê muitos.

• GetItem — lê um item por sua chave primária completa.
• PutItem — crie ou substitua completamente um item.
• UpdateItem — cria ou modifica atributos específicos de um item no local.
• DeleteItem — remove um item pela sua chave primária completa.
• Todos os quatro exigem a chave primária completa (chave de partição, mais chave de classificação se o tabela tem um) — eles abordam exatamente um item.
• PutItem substitui todo o item; UpdateItem é cirúrgico - confundi-los é como os atributos desaparecem silenciosamente.

A característica definidora: um item, chave completa

Cada ação baseada em item tem como alvo um único item por sua chave primária completa. Isso é o que os torna rápidos e baratos - DynamoDB faz hash da chave de partição, vai direto para o item, pronto. Sem filtragem, sem digitalização. Se você não conhece a chave completa, estas não são as ferramenta certa; é para isso que serve Query and Scan.

Digamos que você execute contas de usuário codificadas por USER#<id>:

PK: USER#204   email, displayName, plan, createdAt

• GetItem em USER#204 → aquele usuário, diretamente.
• DeleteItem em USER#204 → remove esse usuário.

Ambos precisam da chave exata. Nenhuma chave, nenhuma ação baseada em itens.

PutItem vs UpdateItem — aquele que morde

Esta é a distinção que vale a pena internalizar:

• PutItem grava o item inteiro. Se USER#204 já existir e você PutItem com apenas {email, displayName}, os atributos plan e createdAt existentes são gone — um put substitui o item inteiro, ele não mescla.
• UpdateItem altera apenas o que você nomeia. UpdateItem com um SET email = … deixa todos os outros atributos intocado e cria o item se ele não existisse (um upsert).

Regra prática: pegue UpdateItem para alterar um item existente e use PutItem somente quando você realmente quer dizer "escreva este item como o novo estado completo". Ambos PutItem e UpdateItem aceitam um expressão de condição para que você possa fazer a gravação condicional ("somente se ainda não existir").

Ações baseadas em itens no DynoTable

Quer as chamadas API brutas por trás dessas ações? Monte as expressões e o valor digitado mapas no construtor de expressão DynamoDB e converta um item JSON simples no formato digitado do API com o Conversor DynamoDB JSON.

No DynoTable, esse mesmo trabalho é visual: abrir um item da grade para lê-lo (um GetItem), editar atributos e confirmar (um UpdateItem), adicionar ou substituir uma linha (um PutItem) ou exclua um — um item de cada vez.

Armadilhas + próximos passos

• PutItem substitui o item inteiro — para alterar alguns campos sem perder o descanse, use UpdateItem.
• Você deve conhecer a chave primária completa — nenhuma chave significa Consulta/Verificação, não uma ação de item.
• Muitos itens ao mesmo tempo? Não faça um loop entre eles um por um — operações em lote as agrupam em menos viagens de ida e volta.
• Precisa do valor antigo do /new de volta? Defina ReturnValues em vez de um GetItem de acompanhamento.
• Relacionado: consulta vs varredura cobre o lado de muitas leituras.

Quer ler, escrever e excluir itens sem escrever uma linha de código API? Baixe DynoTable e trabalhe diretamente com suas tabelas.

Custo: um item, um salto

As leituras baseadas em itens são o acesso endereçável mais barato no DynamoDB. Um GetItem ligado uma linha de 2 KB consome 1 RCU eventualmente consistente (um bloco de 4 KB, arredondado para cima). Um Query que retorna a mesma linha porque você conhecia a chave de partição e a chave de classificação custa a mesma capacidade - mas se você souber apenas a chave de partição e filtrar no código do aplicativo, você paga por cada item na partição.

Cole um item representativo no calculadora de tamanho de item e multiplique por solicitações por segundo no calculadora de preços quando um caminho ativo usa GetItem em loop versus um Query bem codificado.

Expressões de condição em escritas

Tanto PutItem quanto UpdateItem aceitam opcionais expressões de condição. Padrões típicos:

• attribute_not_exists(pk) na colocação — inserção somente de criação sem corrida.
• attribute_exists(pk) na atualização — recuse-se a criar um stub acidentalmente.
• plan = :old em atualização — simultaneidade otimista; tente novamente se outro escritor mudou o plano primeiro.

DeleteItem também suporta condições - exclua apenas se status = :closed, por exemplo. As condições não adicionam uma cobrança de leitura separada; DynamoDB os avalia contra o item armazenado durante a tentativa de gravação.

Crie condições visualmente no Construtor de expressão DynamoDB; copie o ConditionExpression mais ExpressionAttributeNames e ExpressionAttributeValues em sua chamada SDK.

Idempotência e segurança de substituição

PutItem sem condição é o último vencedor em todo o item. Para webhook manipuladores ou consumidores SQS, pares de opções com attribute_not_exists em um processado atributo de marcador ou use UpdateItem com SET processed = :true protegido por attribute_not_exists(processed).

Quando você precisar dos valores de atributos anteriores para um log de auditoria, adicium ReturnValues no mesmo UpdateItem de um GetItem anterior – uma viagem de ida e volta, sem corrida read/write.

Escolhendo a ação correta do item

Preparação de escritas em DynoTableDynoTable prepara UpdateItem e PutItem localmente antes do commit. Você revisa

comparações de atributos, execute verificações PartiQL opcionais e, em seguida, confirme - que mapeia para o chamadas API reais acima. Linha em massa exclui lote em BatchWriteItem sob o capô com nova tentativa em itens não processados.

Para geração de código SDK, monte cláusulas de atualização no arquivo construtor de expressão e cole o emitido Snippet do SDK v3 próximo aos testes do manipulador.