Actions par item dans DynamoDB

L'API de DynamoDB se divise en trois familles : les actions par item qui agissent sur un seul item via sa clé primaire, Query qui lit une plage à l'intérieur d'une partition, et Scan qui lit tout. Ce guide couvre la première famille — les quatre opérations que tu utilises le plus : GetItem, PutItem, UpdateItem, DeleteItem. Ce sont les appels les moins chers et les plus rapides qu'offre DynamoDB, et bien saisir leurs distinctions (surtout Put vs Update) évite toute une classe de bugs de perte de données accidentelle.

Quelles sont les actions par item de DynamoDB ?

Les actions par item de DynamoDB sont les quatre opérations qui agissent sur un seul item via sa clé primaire complète : GetItem le lit, PutItem le crée ou le remplace entièrement, UpdateItem modifie des attributs précis sur place, et DeleteItem le supprime. Chacune adresse exactement un item, ce qui en fait les appels les plus rapides et les moins chers — contrairement à Query et Scan, qui en lisent plusieurs.

• GetItem — lit un seul item par sa clé primaire complète.
• PutItem — crée ou remplace entièrement un item.
• UpdateItem — crée ou modifie des attributs précis d'un item sur place.
• DeleteItem — supprime un item par sa clé primaire complète.
• Les quatre exigent la clé primaire complète (clé de partition, plus clé de tri si la table en a une) — elles adressent exactement un item.
• PutItem écrase l'item entier ; UpdateItem est chirurgical — les confondre, c'est ainsi que des attributs disparaissent silencieusement.

Le trait déterminant : un item, clé complète

Chaque action par item vise un seul item via sa clé primaire complète. C'est ce qui les rend rapides et économiques — DynamoDB hache la clé de partition, va droit à l'item, terminé. Aucun filtrage, aucun scan. Si tu ne connais pas la clé complète, ce n'est pas le bon outil ; c'est à ça que servent Query et Scan.

Disons que tu gères des comptes utilisateurs indexés par USER#<id> :

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

• GetItem sur USER#204 → cet utilisateur, directement.
• DeleteItem sur USER#204 → supprime cet utilisateur.

Les deux exigent la clé exacte. Pas de clé, pas d'action par item.

PutItem vs UpdateItem — celle qui pique

Voici la distinction qui mérite d'être intégrée :

• PutItem écrit l'item entier. Si USER#204 existe déjà et que tu fais un PutItem avec seulement {email, displayName}, les attributs plan et createdAt existants ont disparu — un put remplace l'item entier, il ne fusionne pas.
• UpdateItem ne change que ce que tu nommes. Un UpdateItem avec un SET email = … laisse tous les autres attributs intacts, et crée l'item s'il n'existait pas (un upsert).

À retenir : opte pour UpdateItem pour changer un item existant, et n'utilise PutItem que lorsque tu veux vraiment dire « écris cet item comme le nouvel état complet ». PutItem et UpdateItem acceptent tous deux une expression de condition pour rendre l'écriture conditionnelle (« uniquement s'il n'existe pas déjà »).

Les actions par item dans DynoTable

Tu veux les appels API bruts derrière ces actions ? Assemble les expressions et les maps de valeurs typées dans le constructeur d'expressions DynamoDB, et convertis un item en JSON simple vers le format typé de l'API avec le convertisseur DynamoDB JSON.

Dans DynoTable, ce même travail est visuel : ouvre un item dans la grille pour le lire (un GetItem), édite des attributs et valide (un UpdateItem), ajoute ou remplace une ligne (un PutItem), ou supprimes-en une — un item à la fois.

Pièges + étapes suivantes

• PutItem remplace l'item entier — pour changer quelques champs sans perdre le reste, utilise UpdateItem.
• Tu dois connaître la clé primaire complète — sans clé, c'est Query/Scan, pas une action par item.
• Beaucoup d'items à la fois ? Ne les boucle pas un par un — les opérations par lots les replient en moins d'allers-retours.
• Besoin de récupérer l'ancienne/nouvelle valeur ? Renseigne ReturnValues plutôt qu'un GetItem de suivi.
• À voir aussi : query vs scan couvre le côté lecture en masse.

Envie de lire, écrire et supprimer des items sans écrire une ligne de code d'API ? Télécharge DynoTable et travaille directement avec tes tables.

Coût : un item, un saut

Les lectures par item sont l'accès adressable le moins cher dans DynamoDB. Un GetItem sur une ligne de 2 Ko consomme 1 RCU à cohérence à terme (un bloc de 4 Ko, arrondi au supérieur). Un Query qui renvoie la même ligne parce que tu connaissais la clé de partition et la clé de tri coûte la même capacité — mais si tu ne connais que la clé de partition et filtres dans le code applicatif, tu paies pour chaque item de la partition.

Colle un item représentatif dans le calculateur de taille d'item, puis multiplie par les requêtes par seconde dans le calculateur de tarifs quand un chemin chaud utilise GetItem en boucle versus un Query bien clé.

Expressions de condition sur les écritures

PutItem et UpdateItem acceptent tous deux des expressions de condition optionnelles. Motifs typiques :

• attribute_not_exists(pk) sur put — insert create-only sans course.
• attribute_exists(pk) sur update — refuse de créer un stub par accident.
• plan = :old sur update — concurrence optimiste ; réessaie si un autre writer a changé le plan d'abord.

DeleteItem prend aussi des conditions — supprimer seulement si status = :closed, par exemple. Les conditions n'ajoutent pas de charge de lecture séparée ; DynamoDB les évalue contre l'item stocké pendant la tentative d'écriture.

Construis les conditions visuellement dans le DynamoDB expression builder ; copie le ConditionExpression plus ExpressionAttributeNames et ExpressionAttributeValues dans ton appel SDK.

Idempotence et sécurité d'écrasement

PutItem sans condition est last-writer-wins sur l'item entier. Pour les handlers de webhook ou les consommateurs SQS, couple les puts avec attribute_not_exists sur un attribut marqueur processed, ou utilise UpdateItem avec SET processed = :true gardé par attribute_not_exists(processed).

Quand tu as besoin des valeurs d'attribut précédentes pour un journal d'audit, ajoute ReturnValues sur le même UpdateItem au lieu d'un GetItem précédent — un aller-retour, pas de course lecture/écriture.

Choisir la bonne action par item

Préparer les écritures dans DynoTable

DynoTable prépare localement UpdateItem et PutItem avant le commit. Tu revois les diffs d'attributs, lances des checks PartiQL optionnels, puis commits — ce qui mappe vers les vrais appels API ci-dessus. Les suppressions de lignes en masse partent en BatchWriteItem sous le capot avec réessai sur les items non traités.

Pour la génération de code SDK, assemble les clauses de mise à jour dans l' expression builder et colle le snippet SDK v3 émis à côté des tests de ton handler.