Ações Baseadas em Item do DynamoDB: GetItem, PutItem, UpdateItem, DeleteItem

A API do DynamoDB se divide em três famílias: ações baseadas em item, que operam sobre um único item pela 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 que você mais usa: GetItem, PutItem, UpdateItem, DeleteItem. São as chamadas mais baratas e 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.

O que são as operações baseadas em item do DynamoDB?

As operações baseadas em item do DynamoDB são as quatro chamadas que atuam sobre um único item pela sua chave primária completa: GetItem lê o item, PutItem cria ou substitui o item por completo, UpdateItem modifica atributos específicos no lugar e DeleteItem remove o item. Cada uma endereça exatamente um item, o que as torna as chamadas mais rápidas e baratas — diferentemente de Query e Scan, que leem muitos.

• GetItem — lê um item pela sua chave primária completa.
• PutItem — cria ou substitui por completo um item.
• UpdateItem — cria ou modifica atributos específicos de um item no lugar.
• DeleteItem — remove um item pela sua chave primária completa.
• Todas as quatro exigem a chave primária completa (chave de partição, mais a chave de ordenação se a tabela tiver uma) — elas endereçam exatamente um item.
• PutItem sobrescreve o item inteiro; UpdateItem é cirúrgico — confundir os dois é como atributos somem silenciosamente.

O traço definidor: um item, chave completa

Toda ação baseada em item mira um único item pela sua chave primária completa. É isso que as torna rápidas e baratas — o DynamoDB faz o hash da chave de partição, vai direto ao item, pronto. Sem filtragem, sem varredura. Se você não conhece a chave completa, essas não são a ferramenta certa; é para isso que servem Query e Scan.

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

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

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

Ambas precisam da chave exata. Sem chave, sem ação baseada em item.

PutItem vs UpdateItem — a distinção que morde

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

• PutItem escreve o item inteiro. Se USER#204 já existe e você faz um PutItem só com {email, displayName}, os atributos plan e createdAt existentes somem — um put substitui o item inteiro, não faz merge.
• UpdateItem muda apenas o que você nomeia. Um UpdateItem com um SET email = … deixa todos os outros atributos intactos e cria o item se ele não existia (um upsert).

Regra prática: use UpdateItem para mudar um item existente, e use PutItem só quando você realmente quer dizer "escreva este item como o novo estado completo". Tanto PutItem quanto UpdateItem aceitam uma condition expression, então você pode tornar a escrita condicional ("só se ele ainda não existir").

Ações baseadas em item no DynoTable

Quer ver as chamadas de API brutas por trás dessas ações? Monte as expressões e os mapas de valores tipados no construtor de expressões do DynamoDB, e converta um item em JSON puro para o formato tipado da API com o conversor de DynamoDB JSON.

No DynoTable, esse mesmo trabalho é visual: abra um item na grade para lê-lo (um GetItem), edite atributos e faça commit (um UpdateItem), adicione ou substitua uma linha (um PutItem), ou apague uma — um item de cada vez.

Armadilhas e próximos passos

• PutItem substitui o item inteiro — para mudar alguns campos sem perder o resto, use UpdateItem.
• Você precisa conhecer a chave primária completa — sem chave, é Query/Scan, não uma ação de item.
• Muitos itens de uma vez? Não faça um loop com elas uma a uma — operações em lote as agrupam em menos idas e vindas.
• Precisa do valor antigo/novo de volta? Defina ReturnValues em vez de um GetItem depois.
• Relacionado: query vs scan cobre o lado de ler-muitos.

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