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

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

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

2. 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}));

3. 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.

4. 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 masaüstü uygulaması PartiQL'i canlı tablolarınıza karşı bir SQL çalışma tezgahında ç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.

İ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

References

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

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