DynamoDB Item-basierte Aktionen

Die API von DynamoDB zerfällt in drei Familien: Item-basierte Aktionen, die über den Primärschlüssel auf einem einzelnen Item arbeiten, Query, das einen Bereich innerhalb einer Partition liest, und Scan, das alles liest. Dieser Guide behandelt die erste Familie — die vier Operationen, die du am häufigsten brauchst: GetItem, PutItem, UpdateItem, DeleteItem. Es sind die günstigsten und schnellsten Aufrufe, die DynamoDB anbietet, und ihre Unterschiede sauber zu kennen (vor allem Put vs. Update) verhindert eine ganze Klasse von Bugs mit versehentlichem Datenverlust.

Was sind die Item-basierten Operationen von DynamoDB?

Die Item-basierten Operationen von DynamoDB sind die vier Aufrufe, die über den vollständigen Primärschlüssel auf einem einzelnen Item arbeiten: GetItem liest es, PutItem legt es an oder ersetzt es vollständig, UpdateItem ändert einzelne Attribute an Ort und Stelle, und DeleteItem entfernt es. Jeder adressiert genau ein Item, was sie zu den schnellsten und günstigsten Aufrufen macht — anders als Query und Scan, die viele lesen.

• GetItem — liest ein Item über seinen vollständigen Primärschlüssel.
• PutItem — legt ein Item an oder ersetzt es vollständig.
• UpdateItem — legt ein Item an oder ändert einzelne Attribute an Ort und Stelle.
• DeleteItem — entfernt ein Item über seinen vollständigen Primärschlüssel.
• Alle vier brauchen den vollständigen Primärschlüssel (Partitionsschlüssel, plus Sortierschlüssel, falls die Tabelle einen hat) — sie adressieren genau ein Item.
• PutItem überschreibt das ganze Item; UpdateItem ist chirurgisch — die beiden zu verwechseln ist der Weg, auf dem Attribute lautlos verschwinden.

Das prägende Merkmal: ein Item, voller Schlüssel

Jede Item-basierte Aktion zielt auf ein einzelnes Item über dessen vollständigen Primärschlüssel. Genau das macht sie schnell und günstig — DynamoDB hasht den Partitionsschlüssel, geht direkt zum Item, fertig. Kein Filtern, kein Scannen. Kennst du den vollständigen Schlüssel nicht, sind das nicht die richtigen Werkzeuge; dafür gibt es Query und Scan.

Sagen wir, du betreibst Benutzerkonten mit dem Schlüssel USER#<id>:

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

• GetItem auf USER#204 → dieser Nutzer, direkt.
• DeleteItem auf USER#204 → entfernt diesen Nutzer.

Beide brauchen den exakten Schlüssel. Kein Schlüssel, keine Item-basierte Aktion.

PutItem vs. UpdateItem — die Verwechslung, die weh tut

Das ist der Unterschied, den es zu verinnerlichen lohnt:

• PutItem schreibt das gesamte Item. Existiert USER#204 bereits und du machst ein PutItem mit nur {email, displayName}, sind die vorhandenen Attribute plan und createdAt weg — ein Put ersetzt das ganze Item, es merged nicht.
• UpdateItem ändert nur, was du benennst. Ein UpdateItem mit SET email = … lässt jedes andere Attribut unberührt und legt das Item an, falls es nicht existierte (ein Upsert).

Faustregel: Nimm UpdateItem, um ein bestehendes Item zu ändern, und PutItem nur dann, wenn du wirklich meinst „schreib dieses Item als vollständigen neuen Zustand". Sowohl PutItem als auch UpdateItem akzeptieren eine Condition Expression, du kannst den Write also bedingt machen („nur wenn es noch nicht existiert").

Item-basierte Aktionen in DynoTable

Du willst die rohen API-Aufrufe hinter diesen Aktionen? Setz die Expressions und die typisierten Wert-Maps im DynamoDB Expression Builder zusammen und wandle ein Plain-JSON-Item mit dem DynamoDB-JSON-Konverter ins typisierte API-Format.

In DynoTable ist dieselbe Arbeit visuell: Öffne ein Item im Grid, um es zu lesen (ein GetItem), bearbeite Attribute und committe (ein UpdateItem), füge eine Zeile hinzu oder ersetze sie (ein PutItem), oder lösche eine — immer ein Item auf einmal.

Fallstricke + nächste Schritte

• PutItem ersetzt das ganze Item — um ein paar Felder zu ändern, ohne den Rest zu verlieren, nimm UpdateItem.
• Du musst den vollständigen Primärschlüssel kennen — kein Schlüssel heißt Query/Scan, keine Item-Aktion.
• Viele Items auf einmal? Ruf sie nicht in einer Schleife einzeln auf — Batch-Operationen falten sie in weniger Roundtrips.
• Du brauchst den alten/neuen Wert zurück? Setz ReturnValues statt eines nachgelagerten GetItem.
• Verwandt: Query vs. Scan deckt die Lies-viele-Seite ab.

Du willst Items lesen, schreiben und löschen, ohne eine Zeile API-Code zu schreiben? Lade DynoTable herunter und arbeite direkt mit deinen Tabellen.

Kosten: ein Item, ein Hop

Item-basierte Reads sind der günstigste adressierbare Zugriff in DynamoDB. Ein GetItem auf eine 2 KB große Zeile verbraucht 1 letztendlich konsistente RCU (ein 4-KB-Block, aufgerundet). Ein Query, das dieselbe Zeile zurückgibt, weil du Partitions- und Sortierschlüssel kanntest, kostet dieselbe Kapazität — kennst du aber nur den Partitionsschlüssel und filterst im Anwendungscode, zahlst du für jedes Item in der Partition.

Füg ein repräsentatives Item in den Item-Size-Rechner ein und multiplizier im Preisrechner mit den Requests pro Sekunde, wenn ein heißer Pfad GetItem in einer Schleife statt eines gut gekeyten Query nutzt.

Condition Expressions bei Writes

Sowohl PutItem als auch UpdateItem akzeptieren optionale Condition Expressions. Typische Muster:

• attribute_not_exists(pk) beim Put — Insert nur bei Nichtexistenz, ohne Race.
• attribute_exists(pk) beim Update — verhindert, dass versehentlich ein Stub angelegt wird.
• plan = :old beim Update — optimistische Nebenläufigkeit; erneut versuchen, wenn ein anderer Writer den Plan zuerst geändert hat.

Auch DeleteItem unterstützt Bedingungen — etwa nur löschen, wenn status = :closed. Bedingungen kosten keinen separaten Read; DynamoDB wertet sie während des Schreibversuchs gegen das gespeicherte Item aus.

Bau Bedingungen visuell im DynamoDB Expression Builder; kopier die ConditionExpression samt ExpressionAttributeNames und ExpressionAttributeValues in deinen SDK-Aufruf.

Idempotenz und Überschreibsicherheit

PutItem ohne Bedingung ist Last-Writer-wins auf dem gesamten Item. Bei Webhook-Handlern oder SQS-Consumern koppelst du Puts mit attribute_not_exists auf einem Verarbeitet-Marker-Attribut, oder du nimmst UpdateItem mit SET processed = :true, abgesichert durch attribute_not_exists(processed).

Wenn du die vorherigen Attributwerte für ein Audit-Log brauchst, ergänz ReturnValues auf demselben UpdateItem, statt ein vorgelagertes GetItem zu machen — ein Roundtrip, kein Read/Write-Race.

Die richtige Item-Aktion wählen

Writes in DynoTable stagen

DynoTable staged UpdateItem und PutItem lokal, bevor du committest. Du prüfst die Attribut-Diffs, lässt optional PartiQL-Checks laufen und committest dann — was auf die echten API-Aufrufe oben abbildet. Massenlöschungen von Zeilen bündelt es intern zu BatchWriteItem mit Wiederholung für nicht verarbeitete Items.

Für die SDK-Codegenerierung setzt du die Update-Klauseln im Expression Builder zusammen und legst das ausgegebene SDK-v3-Snippet neben deine Handler-Tests.