DuplicateItemException: chiave primaria duplicata

In breve — Un INSERT PartiQL è una creazione rigorosa: se un Item con la stessa chiave primaria esiste già, DynamoDB lancia DuplicateItemException invece di sovrascriverlo. Per modificare l'Item esistente usa UPDATE PartiQL; per ottenere la semantica replace-if-exists di PutItem, usa PutItem stesso — l'INSERT PartiQL deliberatamente non sostituisce mai.

Cosa significa

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

Il data-plane PartiQL (ExecuteStatement / ExecuteTransaction / BatchExecuteStatement) mappa INSERT a una creazione condizionale — riesce solo quando nessun Item con quella chiave primaria esiste. È il default opposto rispetto al PutItem nativo, che sostituisce silenziosamente un Item esistente. Se vieni da SQL aspettandoti che INSERT fallisca su una chiave duplicata, è esattamente questo comportamento; se ti aspettavi una semantica di upsert, questo errore è la sorpresa.

Perché accade

• L'Item esiste genuinamente già — un retry, un replay, o due writer in race sulla stessa chiave che emettono entrambi INSERT.
• Volevi un aggiornamento, non una creazione — porting di codice in stile PutItem a PartiQL presumendo che INSERT sostituisca.
• Un loop di retry non idempotente — il primo tentativo è riuscito ma la risposta è andata persa (timeout), e il retry reinserisce la stessa chiave.
• Una chiave sintetica non unica — la partition/sort key che componi collide più spesso di quanto pensi (es. un timestamp con precisione al secondo).

Come correggerlo

1. Stai aggiornando un Item esistente? Usa UPDATE:

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

2. Vuoi replace-if-exists (semantica PutItem)? Chiama PutItem — PartiQL non ha uno statement di upsert, e il default dell'API nativa è esattamente la sovrascrittura che cerchi:

   await client.send(new PutItemCommand({TableName: 'orders', Item: item}));

3. Trattalo come un successo quando la creazione è idempotente — se un retry incontra DuplicateItemException per un Item che il tuo primo tentativo ha già scritto, intercettarlo e ignorarlo è spesso la gestione corretta.

4. Mantieni INSERT quando fai affidamento sull'unicità — l'eccezione è il tuo guard create-only, l'equivalente PartiQL di attribute_not_exists() su una condizione PutItem.

Provare gli statement contro dati reali è il modo più rapido per interiorizzare la divisione INSERT/UPDATE — l'app desktop DynoTable esegue PartiQL in un SQL workbench sulle tue tabelle live, e il DynamoDB Expression Builder emette le richieste equivalenti dell'API nativa quando ti serve invece la semantica di PutItem.

Errori correlati

• ConditionalCheckFailedException — il gemello dell'API nativa: guard attribute_not_exists() che fallisce su PutItem.
• ValidationException: Unexpected from source — l'altro rifiuto PartiQL comune.
• Impara: PartiQL examples · PartiQL vs SQL

References

• ExecuteStatement — Amazon DynamoDB API Reference (DuplicateItemException)
• PartiQL insert statements for DynamoDB — Developer Guide
• PartiQL update statements for DynamoDB — Developer Guide

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.