Acciones por elemento de DynamoDB: GetItem, PutItem, UpdateItem, DeleteItem

La API de DynamoDB se divide en tres familias: las acciones por elemento que operan sobre un solo elemento por su clave primaria, Query que lee un rango dentro de una partición, y Scan que lo lee todo. Esta guía cubre la primera familia — las cuatro operaciones que más usarás: GetItem, PutItem, UpdateItem, DeleteItem. Son las llamadas más baratas y rápidas que ofrece DynamoDB, y acertar con sus distinciones (sobre todo Put frente a Update) evita toda una clase de bugs de pérdida accidental de datos.

¿Qué son las operaciones por elemento de DynamoDB?

Las operaciones por elemento de DynamoDB son las cuatro llamadas que actúan sobre un solo elemento por su clave primaria completa: GetItem lo lee, PutItem lo crea o lo reemplaza por completo, UpdateItem modifica atributos concretos in situ y DeleteItem lo elimina. Cada una direcciona exactamente un elemento, lo que las convierte en las llamadas más rápidas y baratas — a diferencia de Query y Scan, que leen muchos.

• GetItem — lee un elemento por su clave primaria completa.
• PutItem — crea o reemplaza por completo un elemento.
• UpdateItem — crea o modifica atributos concretos de un elemento in situ.
• DeleteItem — elimina un elemento por su clave primaria completa.
• Las cuatro requieren la clave primaria completa (clave de partición, más la clave de ordenación si la tabla la tiene) — direccionan exactamente un elemento.
• PutItem sobrescribe el elemento entero; UpdateItem es quirúrgico — confundirlas es como los atributos desaparecen en silencio.

El rasgo definitorio: un elemento, clave completa

Toda acción por elemento apunta a un único elemento por su clave primaria completa. Eso es lo que las hace rápidas y baratas — DynamoDB aplica hash a la clave de partición, va directo al elemento, y listo. Sin filtrado, sin escaneo. Si no conoces la clave completa, estas no son la herramienta adecuada; para eso están Query y Scan.

Digamos que gestionas cuentas de usuario con clave USER#<id>:

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

• GetItem sobre USER#204 → ese usuario, directamente.
• DeleteItem sobre USER#204 → elimina ese usuario.

Ambas necesitan la clave exacta. Sin clave, no hay acción por elemento.

PutItem frente a UpdateItem — la que muerde

Esta es la distinción que vale la pena interiorizar:

• PutItem escribe el elemento entero. Si USER#204 ya existe y haces PutItem con solo {email, displayName}, los atributos plan y createdAt existentes desaparecen — un put reemplaza el elemento entero, no lo fusiona.
• UpdateItem cambia solo lo que nombras. Un UpdateItem con un SET email = … deja intactos todos los demás atributos, y crea el elemento si no existía (un upsert).

Regla práctica: recurre a UpdateItem para cambiar un elemento existente, y usa PutItem solo cuando de verdad quieras decir "escribe este elemento como el nuevo estado completo". Tanto PutItem como UpdateItem aceptan una expresión de condición para que puedas condicionar la escritura ("solo si aún no existe").

Las acciones por elemento en DynoTable

¿Quieres las llamadas a la API en bruto detrás de estas acciones? Ensambla las expresiones y los mapas de valores tipados en el constructor de expresiones de DynamoDB, y convierte un elemento en JSON plano al formato tipado de la API con el conversor de JSON de DynamoDB.

En DynoTable, ese mismo trabajo es visual: abre un elemento en la cuadrícula para leerlo (un GetItem), edita atributos y confirma (un UpdateItem), añade o reemplaza una fila (un PutItem), o elimina una — un elemento a la vez.

Trampas y próximos pasos

• PutItem reemplaza el elemento entero — para cambiar unos pocos campos sin perder el resto, usa UpdateItem.
• Debes conocer la clave primaria completa — sin clave es Query/Scan, no una acción por elemento.
• ¿Muchos elementos a la vez? No los recorras de uno en uno — las operaciones por lotes los pliegan en menos viajes de ida y vuelta.
• ¿Necesitas el valor antiguo/nuevo de vuelta? Usa ReturnValues en lugar de un GetItem posterior.
• Relacionado: query vs scan cubre el lado de leer-muchos.

¿Quieres leer, escribir y eliminar elementos sin escribir una línea de código de la API? Descarga DynoTable y trabaja con tus tablas directamente.