Escritura condicional en DynamoDB en Node.js (AWS SDK v3)

Una escritura condicional adjunta una ConditionExpression a un PutItem, UpdateItem o DeleteItem: DynamoDB la evalúa contra el item actual y aplica la escritura solo si se cumple — atómicamente, sin una carrera de lectura-modificación-escritura. Es la primitiva de bloqueo optimista de DynamoDB. Este ejemplo protege una actualización con una comprobación de versión.

Code

import {DynamoDBClient, UpdateItemCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

// Update the item only if nobody changed it since we read version 7.
const command = new UpdateItemCommand({
  TableName: 'Music',
  Key: {
    Artist: {S: 'Arturo Sandoval'},
    SongTitle: {S: 'Cubano Chant'}
  },
  UpdateExpression: 'SET #upd0 = :updValue0, #version = :newVersion',
  ConditionExpression: 'attribute_exists(#cond0) AND #version = :expectedVersion',
  ExpressionAttributeNames: {
    '#upd0': 'Genre',
    '#version': 'Version',
    '#cond0': 'Artist'
  },
  ExpressionAttributeValues: {
    ':updValue0': {S: 'Latin Jazz'},
    ':expectedVersion': {N: '7'},
    ':newVersion': {N: '8'}
  },
  ReturnValuesOnConditionCheckFailure: 'ALL_OLD'
});

try {
  await client.send(command);
  console.log('Updated to version 8');
} catch (err) {
  if (err.name === 'ConditionalCheckFailedException') {
    // With ReturnValuesOnConditionCheckFailure: 'ALL_OLD', the current item
    // rides back on the exception — no extra read to see what beat you.
    console.log('Lost the race — item is now:', err.Item);
  } else {
    throw err;
  }
}

Explicación

ConditionExpression — comprobada contra el item almacenado atómicamente con la escritura. Funciones disponibles: attribute_exists, attribute_not_exists, attribute_type, contains, begins_with, size, más comparadores (=, <>, <, >, <=, >=, BETWEEN, IN) y AND/OR/NOT.
Los dos idiomas de caballo de batalla:
- attribute_exists(#key) en una actualización = "solo actualizar, nunca crear". Sin ella, UpdateItem sobre una clave inexistente crea silenciosamente el item (el bug del upsert accidental).
- attribute_not_exists(#key) en una inserción = "solo crear, nunca sobrescribir" — mostrado en la página de PutItem.
Bloqueo optimista — lee el item (versión 7), luego escribe con #version = :expectedVersion mientras lo subes a 8. Dos escritores concurrentes no pueden ganar ambos; el perdedor recibe ConditionalCheckFailedException, vuelve a leer y reintenta sobre la nueva versión.
ReturnValuesOnConditionCheckFailure: 'ALL_OLD' — pone el item actual en la excepción (err.Item, con marshalling), ahorrando el GetItem posterior tras una comprobación fallida. No consume capacidad de lectura; una escritura condicional fallida sigue facturando su intento de escritura.
Todo aquí lleva alias (#version → Version) mediante ExpressionAttributeNames, así que las palabras reservadas nunca muerden.

Hazlo visualmente

Las expresiones de condición son exactamente lo que construye el DynamoDB Expression Builder — elige la función, obtén la expresión + los mapas de nombre/valor como código ejecutable.

Para editar items con expresiones generadas y revisables en lugar de marcadores de posición escritos a mano — descarga DynoTable.

Ejemplos relacionados

Escritura condicional en DynamoDB en Python — el mismo bloqueo optimista con boto3.
Escritura condicional en DynamoDB con la AWS CLI — el mismo bloqueo optimista desde el shell.
DynamoDB PutItem en Node.js — la inserción de solo crear con attribute_not_exists.
Expresiones de condición de DynamoDB — cada función, con patrones.
Imponer unicidad en varios atributos — condiciones + transacciones combinadas.
DynamoDB ConditionalCheckFailedException — cuándo la comprobación fallida es esperada y cómo manejarla de forma barata.

References

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.