DuplicateItemException: duplicate primary key

TL;DR — Bir PartiQL INSERT katı bir oluşturmadır: aynı birincil anahtara sahip bir öğe zaten varsa, DynamoDB onun üzerine yazmak yerine DuplicateItemException fırlatır. Mevcut öğeyi değiştirmek için PartiQL UPDATE kullanın; PutItem'ın varsa-değiştir semantiğini elde etmek için PutItem'ın kendisini kullanın — PartiQL INSERT bilerek asla değiştirmez.

Ne anlama gelir

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

PartiQL veri düzlemi (ExecuteStatement / ExecuteTransaction / BatchExecuteStatement), INSERT'i koşullu bir oluşturmaya eşler — yalnızca o birincil anahtara sahip hiçbir öğe yoksa başarılı olur. Bu, mevcut bir öğeyi sessizce değiştiren yerel PutItem'ın tam tersi varsayılanıdır. INSERT'in yinelenen bir anahtarda başarısız olmasını bekleyerek SQL'den geldiyseniz, bu tam olarak o davranıştır; upsert semantiği beklediyseniz, bu hata sürprizdir.

Neden olur

Öğe gerçekten zaten var — bir yeniden deneme, bir yeniden oynatma ya da aynı anahtarda yarışan ve her ikisi de INSERT gönderen iki yazıcı.
Bir oluşturma değil, bir güncelleme istediniz — PutItem tarzı kodu PartiQL'e taşımak ve INSERT'in değiştirdiğini varsaymak.
İdempotent olmayan bir yeniden deneme döngüsü — ilk deneme başarılı oldu ama yanıt kayboldu (zaman aşımı) ve yeniden deneme aynı anahtarı tekrar ekler.
Benzersiz olmayan sentetik bir anahtar — oluşturduğunuz bölüm/sıralama anahtarı düşündüğünüzden daha sık çakışır (örneğin saniye hassasiyetinde bir zaman damgası).

Nasıl düzeltilir

Mevcut bir öğeyi mi güncelliyorsunuz? UPDATE kullanın:

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

Varsa-değiştir mi istiyorsunuz (PutItem semantiği)? PutItem çağırın — PartiQL'in upsert ifadesi yoktur ve yerel API'nin varsayılanı tam olarak istediğiniz üzerine yazmadır:
```
await client.send(new PutItemCommand({TableName: 'orders', Item: item}));
```
Oluşturma idempotent olduğunda bunu başarı olarak ele alın — bir yeniden deneme, ilk denemenizin zaten yazdığı bir öğe için DuplicateItemException alırsa, onu yakalayıp yoksaymak genellikle doğru ele alıştır.
Benzersizliğe güvendiğinizde INSERT'i tutun — istisna sizin yalnızca-oluştur korumanızdır, bir PutItem koşulunda attribute_not_exists()'in PartiQL eşdeğeridir.

İfadeleri gerçek veriye karşı denemek, INSERT/UPDATE ayrımını içselleştirmenin en hızlı yoludur — DynoTable'ın PartiQL düzenleyicisi ifadeleri canlı tablolarınıza karşı satır içi tanılar ve hızlı düzeltmelerle çalıştırır ve DynamoDB Expression Builder, bunun yerine PutItem semantiğine ihtiyacınız olduğunda eşdeğer yerel API isteklerini yayar.

Nasıl yeniden oluşturulur

Zaten var olan bir birincil anahtar için bir PartiQL INSERT:

await client.send(
  new PutItemCommand({
    TableName: 'orders',
    Item: {pk: {S: 'ORDER#1'}, sk: {S: 'META'}}
  })
);
await client.send(
  new ExecuteStatementCommand({
    Statement: `INSERT INTO "orders" VALUE {'pk':'ORDER#1','sk':'META'}`
  })
);

Gerçek çıktı:

DuplicateItem: Duplicate primary key exists in table
HTTP 400

Yerelde test ediyorsanız bilmekte fayda var: DynamoDB Local bunu yukarıdaki kısa mesajla DuplicateItem olarak yüzeye çıkarırken, hizmetin API referansı onu daha uzun bir cümleyle DuplicateItemException olarak belgeler. Tam ada ya da ifadeye göre değil, HTTP 400 artı işleme göre eşleştirin; yoksa işleyiciniz Local'e karşı, gerçek tabloya karşı olduğundan farklı davranır.

İlgili hatalar

ConditionalCheckFailedException — yerel API ikizi: PutItem'da başarısız olan attribute_not_exists() koruması.
ValidationException: Unexpected from source — diğer yaygın PartiQL reddi.
Öğrenin: PartiQL examples · PartiQL vs SQL

Kaynaklar

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.

2026-07-26 tarihinde AWS SDK for JavaScript v3.1095.0 ile DynamoDB Local 2.x'e karşı yeniden üretildi — yukarıdaki çıktı birebir alınmıştır.