DuplicateItemException: primary key duplikat

TL;DR — PartiQL INSERT adalah create yang ketat: jika item dengan primary key yang sama sudah ada, DynamoDB melempar DuplicateItemException alih-alih menimpanya. Untuk memodifikasi item yang ada gunakan PartiQL UPDATE; untuk mendapatkan semantik replace-if-exists PutItem, gunakan PutItem sendiri — PartiQL INSERT sengaja tidak pernah mengganti.

Apa artinya

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

Data-plane PartiQL (ExecuteStatement / ExecuteTransaction / BatchExecuteStatement) memetakan INSERT ke conditional create — ia berhasil hanya ketika tidak ada item dengan primary key itu. Itu default yang berlawanan dari PutItem native, yang diam-diam mengganti item yang ada. Jika Anda datang dari SQL mengharapkan INSERT gagal pada kunci duplikat, ini persis perilaku itu; jika Anda mengharapkan semantik upsert, kesalahan ini adalah kejutan.

Mengapa terjadi

• Item memang sudah ada — retry, replay, atau dua penulis berlomba pada kunci yang sama keduanya mengeluarkan INSERT.
• Anda menginginkan update, bukan create — memindahkan kode gaya PutItem ke PartiQL dan mengasumsikan INSERT mengganti.
• Loop retry yang tidak idempoten — upaya pertama berhasil tetapi responsnya hilang (timeout), dan retry menyisipkan ulang kunci yang sama.
• Kunci sintetis yang tidak unik — partition/sort key yang Anda susun bertabrakan lebih sering daripada yang Anda kira (mis. timestamp pada presisi detik).

Cara memperbaikinya

1. Memperbarui item yang ada? Gunakan UPDATE:

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

2. Ingin replace-if-exists (semantik PutItem)? Panggil PutItem — PartiQL tidak punya statement upsert, dan default API native persis penimpaan yang Anda inginkan:

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

3. Perlakukan sebagai sukses ketika create-nya idempoten — jika retry mengenai DuplicateItemException untuk item yang sudah ditulis upaya pertama Anda, menangkap dan mengabaikannya sering kali penanganan yang benar.

4. Pertahankan INSERT ketika Anda mengandalkan keunikan — exception adalah penjaga create-only Anda, padanan PartiQL dari attribute_not_exists() pada kondisi PutItem.

Mencoba statement terhadap data nyata adalah cara tercepat untuk menginternalisasi pemisahan INSERT/UPDATE — aplikasi desktop DynoTable menjalankan PartiQL di workbench SQL terhadap tabel live Anda, dan DynamoDB Expression Builder mengeluarkan permintaan API-native setara ketika Anda butuh semantik PutItem sebagai gantinya.

Kesalahan terkait

• ConditionalCheckFailedException — kembaran API-native: penjaga attribute_not_exists() gagal pada PutItem.
• ValidationException: Unexpected from source — penolakan PartiQL umum lainnya.
• Pelajari: 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

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.