Écriture conditionnelle DynamoDB en Node.js (AWS SDK v3)

Une écriture conditionnelle attache un ConditionExpression à un PutItem, UpdateItem ou DeleteItem : DynamoDB l'évalue par rapport à l'élément actuel et n'applique l'écriture que si elle est vérifiée — de façon atomique, sans course lecture-modification-écriture. C'est la primitive de verrouillage optimiste de DynamoDB. Cet exemple protège une mise à jour avec une vérification de version.

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;
  }
}

Explication

ConditionExpression — vérifié par rapport à l'élément stocké de façon atomique avec l'écriture. Fonctions disponibles : attribute_exists, attribute_not_exists, attribute_type, contains, begins_with, size, plus les comparateurs (=, <>, <, >, <=, >=, BETWEEN, IN) et AND/OR/NOT.
Les deux idiomes de base :
- attribute_exists(#key) sur une mise à jour = « mettre à jour uniquement, ne jamais créer ». Sans lui, UpdateItem sur une clé manquante crée silencieusement l'élément (le bug d'upsert accidentel).
- attribute_not_exists(#key) sur une insertion = « créer uniquement, ne jamais écraser » — montré sur la page PutItem.
Verrouillage optimiste — lis l'élément (version 7), puis écris avec #version = :expectedVersion tout en passant à 8. Deux écrivains concurrents ne peuvent pas gagner tous les deux ; le perdant obtient ConditionalCheckFailedException, relit, et réessaie sur la nouvelle version.
ReturnValuesOnConditionCheckFailure: 'ALL_OLD' — place l'élément actuel sur l'exception (err.Item, marshalé), évitant le GetItem de suivi après une vérification échouée. Il ne consomme aucune capacité de lecture ; une écriture conditionnelle échouée facture quand même sa tentative d'écriture.
Tout ici est aliasé (#version → Version) via ExpressionAttributeNames, donc les mots réservés ne posent jamais problème.

À faire visuellement

Les expressions de condition sont exactement ce que construit le DynamoDB Expression Builder — choisis la fonction, obtiens l'expression + les cartes de noms/valeurs sous forme de code exécutable.

Pour éditer des éléments avec des expressions générées et vérifiables au lieu de placeholders tapés à la main — télécharge DynoTable.

Exemples liés

Écriture conditionnelle DynamoDB en Python — le même verrou optimiste avec boto3.
Écriture conditionnelle DynamoDB avec l'AWS CLI — le même verrou optimiste depuis le shell.
DynamoDB PutItem en Node.js — l'insertion attribute_not_exists de création uniquement.
Expressions de condition DynamoDB — chaque fonction, avec des motifs.
Imposer l'unicité sur plusieurs attributs — conditions + transactions combinées.
DynamoDB ConditionalCheckFailedException — quand la vérification échouée est attendue, et comment la gérer à moindre coût.

References

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.