DuplicateItemException: duplicate primary key

En bref — Un INSERT PartiQL est une création stricte : si un élément avec la même clé primaire existe déjà, DynamoDB lève DuplicateItemException au lieu de l'écraser. Pour modifier l'élément existant, utilise UPDATE PartiQL ; pour obtenir la sémantique remplacer-si-existe de PutItem, utilise PutItem lui-même — l'INSERT PartiQL ne remplace délibérément jamais.

Ce que ça signifie

DuplicateItemException: There was an attempt to insert an item with the
same primary key as an item that already exists in the DynamoDB table.

Le plan de données PartiQL (ExecuteStatement / ExecuteTransaction / BatchExecuteStatement) mappe INSERT vers une création conditionnelle — il ne réussit que quand aucun élément avec cette clé primaire n'existe. C'est l'inverse du défaut du PutItem natif, qui remplace silencieusement un élément existant. Si tu viens du SQL en t'attendant à ce qu'INSERT échoue sur une clé dupliquée, c'est exactement ce comportement ; si tu attendais une sémantique d'upsert, cette erreur est la surprise.

Pourquoi ça arrive

L'élément existe réellement déjà — un réessai, un replay, ou deux écrivains qui se font la course sur la même clé en émettant tous deux INSERT.
Tu voulais une mise à jour, pas une création — porter du code façon PutItem vers PartiQL en supposant qu'INSERT remplace.
Une boucle de réessai non idempotente — la première tentative a réussi mais la réponse a été perdue (timeout), et le réessai réinsère la même clé.
Une clé synthétique qui n'est pas unique — la clé partition/tri que tu composes entre en collision plus souvent que tu ne le penses (p. ex. un horodatage à la précision de la seconde).

Comment corriger

Tu mets à jour un élément existant ? Utilise UPDATE :

UPDATE "orders" SET status = 'shipped' WHERE pk = 'ORDER#123' AND sk = 'META'

Tu veux remplacer-si-existe (sémantique PutItem) ? Appelle PutItem — PartiQL n'a aucune instruction d'upsert, et le défaut de l'API native est exactement l'écrasement que tu cherches :
```
await client.send(new PutItemCommand({TableName: 'orders', Item: item}));
```
Traite-la comme un succès quand la création est idempotente — si un réessai rencontre DuplicateItemException pour un élément que ta première tentative a déjà écrit, l'attraper et l'ignorer est souvent le bon traitement.
Garde INSERT quand tu comptes sur l'unicité — l'exception est ton garde création-seule, l'équivalent PartiQL d'attribute_not_exists() sur une condition PutItem.

Essayer des instructions contre des données réelles est le moyen le plus rapide d'intérioriser la distinction INSERT/UPDATE — l'application de bureau DynoTable exécute PartiQL dans un workbench SQL contre tes tables actives, et le DynamoDB Expression Builder émet les requêtes équivalentes de l'API native quand tu as plutôt besoin de la sémantique PutItem.

Erreurs liées

ConditionalCheckFailedException — le jumeau de l'API native : garde attribute_not_exists() échouant sur PutItem.
ValidationException: Unexpected from source — l'autre rejet PartiQL courant.
Apprends : PartiQL examples · PartiQL vs SQL

Références

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