TransactWriteItems DynamoDB en Node.js (AWS SDK v3)

TransactWriteItems regroupe jusqu'à 100 écritures en une seule opération tout-ou-rien — soit chaque action est validée, soit aucune ne l'est. Dans AWS SDK v3, tu envoies une TransactWriteItemsCommand dont le tableau TransactItems mêle des actions Put, Update, Delete et ConditionCheck, chacune avec une condition optionnelle.

Code

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

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

// Move one award between two songs — atomically. If the first song has no
// award to give, NEITHER update happens.
const command = new TransactWriteItemsCommand({
  TransactItems: [
    {
      Update: {
        TableName: 'Music',
        Key: {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'Cubano Chant'}},
        UpdateExpression: 'SET #upd0 = #upd0 - :one',
        ConditionExpression: '#upd0 >= :one',
        ExpressionAttributeNames: {'#upd0': 'Awards'},
        ExpressionAttributeValues: {':one': {N: '1'}}
      }
    },
    {
      Update: {
        TableName: 'Music',
        Key: {Artist: {S: 'Arturo Sandoval'}, SongTitle: {S: 'A Mis Abuelos'}},
        UpdateExpression: 'SET #upd0 = if_not_exists(#upd0, :zero) + :one',
        ExpressionAttributeNames: {'#upd0': 'Awards'},
        ExpressionAttributeValues: {':one': {N: '1'}, ':zero': {N: '0'}}
      }
    }
  ]
});

try {
  await client.send(command);
  console.log('Transaction committed');
} catch (err) {
  if (err.name === 'TransactionCanceledException') {
    // One reason per action, in TransactItems order. 'None' means that action
    // was fine — some OTHER action sank the transaction.
    const codes = (err.CancellationReasons ?? []).map((r) => r.Code);
    console.log('Transaction canceled:', codes); // e.g. ['ConditionalCheckFailed', 'None']
  } else {
    throw err;
  }
}

Explication

• TransactItems — jusqu'à 100 actions Put / Update / Delete / ConditionCheck, 4 Mo au total. Les actions peuvent s'étendre sur plusieurs tables (même compte + même Region), mais deux actions ne peuvent pas cibler le même élément — cela seul annule la transaction.
• ConditionCheck — affirme une condition sur un élément que la transaction ne modifie pas (par ex. « le compte existe toujours ») et met son veto sur toute la transaction si elle échoue.
• TransactionCanceledException — la seule erreur à gérer. err.CancellationReasons liste un {Code, Message} par action dans l'ordre — les codes incluent ConditionalCheckFailed, TransactionConflict (une autre transaction a touché un élément en cours de route — sûr à réessayer avec backoff), ProvisionedThroughputExceeded et ValidationError ; None marque les actions innocentes. Fixe ReturnValuesOnConditionCheckFailure: 'ALL_OLD' sur une action pour obtenir les attributs de l'élément perdant dans sa raison.
• ClientRequestToken — passes-en un pour rendre l'appel idempotent pendant 10 minutes ; une réexécution du SDK après un timeout réseau ne peut alors pas appliquer les écritures deux fois.
• Coût — les écritures transactionnelles consomment deux écritures sous-jacentes par élément (préparation + validation), donc elles facturent environ 2× les WCU d'une écriture simple. Ne te tourne pas vers les transactions quand une écriture conditionnelle sur un seul élément te donne déjà l'atomicité sur cet élément.

À faire visuellement

Les expressions de condition et de mise à jour à l'intérieur de chaque action sont la partie délicate — le DynamoDB Expression Builder les assemble avec les maps de noms/valeurs et copie du code exécutable.

Pour éditer des éléments et examiner les expressions générées dans une interface graphique — télécharge DynoTable.

Exemples liés

• TransactWriteItems DynamoDB en Python — la même transaction avec boto3.
• TransactWriteItems DynamoDB avec l'AWS CLI — la même transaction depuis le shell.
• Écriture conditionnelle DynamoDB en Node.js — l'atomicité sur un seul élément sans le coût 2×.
• Transactions DynamoDB — isolation, idempotence, et quand les transactions valent le coup.
• DynamoDB TransactionCanceledException — chaque code de raison d'annulation, décodé.
• "Too many actions in a TransactWriteItems call" — les limites de 100 actions et 4 Mo par transaction.
• "Transaction request cannot include multiple operations on one item" — une action par élément, par transaction.

References

• TransactWriteItems — Amazon DynamoDB API Reference
• Amazon DynamoDB transactions: how it works — Amazon DynamoDB Developer Guide
• DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide

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