DynamoDB Conditional Write in Node.js (AWS SDK v3)

Ein bedingter Schreibvorgang hängt eine ConditionExpression an ein PutItem, UpdateItem oder DeleteItem: DynamoDB wertet sie gegen das aktuelle Item aus und wendet den Schreibvorgang nur an, wenn sie zutrifft — atomar, ohne Read-Modify-Write-Race. Es ist DynamoDBs Primitive für optimistisches Locking. Dieses Beispiel sichert ein Update mit einer Versionsprüfung ab.

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

Erklärung

• ConditionExpression — atomar mit dem Schreibvorgang gegen das gespeicherte Item geprüft. Verfügbare Funktionen: attribute_exists, attribute_not_exists, attribute_type, contains, begins_with, size, plus Vergleichsoperatoren (=, <>, <, >, <=, >=, BETWEEN, IN) und AND/OR/NOT.
• Die zwei Standard-Idiome:
  • attribute_exists(#key) bei einem Update = "nur aktualisieren, nie anlegen". Ohne es legt UpdateItem auf einen fehlenden Schlüssel stillschweigend das Item an (der versehentliche Upsert-Bug).
  • attribute_not_exists(#key) bei einem Put = "nur anlegen, nie überschreiben" — gezeigt auf der PutItem-Seite.
• Optimistisches Locking — lies das Item (Version 7), dann schreibe mit #version = :expectedVersion und erhöhe auf 8. Zwei gleichzeitige Writer können nicht beide gewinnen; der Verlierer bekommt ConditionalCheckFailedException, liest neu und wiederholt auf der neuen Version.
• ReturnValuesOnConditionCheckFailure: 'ALL_OLD' — legt das aktuelle Item an die Exception (err.Item, marshalled) und spart das anschließende GetItem nach einer gescheiterten Prüfung. Es verbraucht keine Lesekapazität; ein gescheiterter bedingter Schreibvorgang berechnet trotzdem seinen Schreibversuch.
• Alles hier ist über ExpressionAttributeNames aliasiert (#version → Version), sodass reservierte Wörter nie zubeißen.

Visuell erledigen

Bedingungsausdrücke sind genau das, was der DynamoDB Expression Builder baut — wähle die Funktion, erhalte den Ausdruck + Name-/Wert-Zuordnungen als lauffähigen Code.

Um Items mit generierten, überprüfbaren Ausdrücken zu bearbeiten statt mit handgetippten Platzhaltern — lade DynoTable herunter.

Verwandte Beispiele

• DynamoDB Conditional Write in Python — dasselbe optimistische Lock mit boto3.
• DynamoDB Conditional Write mit der AWS CLI — dasselbe optimistische Lock aus der Shell.
• DynamoDB PutItem in Node.js — der Create-only-attribute_not_exists-Put.
• DynamoDB-Bedingungsausdrücke — jede Funktion, mit Mustern.
• Eindeutigkeit über mehrere Attribute erzwingen — Bedingungen + Transaktionen kombiniert.
• DynamoDB ConditionalCheckFailedException — wann die gescheiterte Prüfung erwartet wird und wie man sie günstig behandelt.

References

• UpdateItem — Amazon DynamoDB API Reference
• Condition expressions — Amazon DynamoDB Developer Guide
• DynamoDB read and write operations (capacity unit consumption) — Amazon DynamoDB Developer Guide

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.