MongoDB “E11000 duplicate key error” hatasını çözmek için önce mesajda adı geçen indeks ile çakışan değeri belirle, ardından aynı değerin tekrar yazılmasının gerçekten engellenmesi gerekip gerekmediğini kontrol et. Hata, eklemek ya da güncellemek istediğin belge bir unique indeksin benzersizlik kuralını ihlal ettiğinde oluşur; sorunu gidermek için veriyi veya yazma işlemini bu kurala uygun hâle getirmelisin.
E11000 duplicate key error ne anlama gelir?
E11000, MongoDB’nin bir belgeyi kaydederken benzersiz olması gereken indeks değerinde çakışma bulduğunu bildirir. Belge, koleksiyonda saklanan bir kayıttır; koleksiyon ise benzer belgelerin bir arada tutulduğu yapıdır. İndeks, alanlar üzerinden kayıt bulmayı destekleyen bir yapıdır ve unique ayarı, indekslenen değerin birden fazla belgede yer almasını engeller.
Örneğin email alanında unique indeks varsa, aynı e-posta değerini taşıyan ikinci bir belge eklenemez. Bu kural yalnızca e-posta gibi kullanıcı alanları için geçerli değildir: MongoDB koleksiyonlarında _id alanı da benzersiz olmalıdır. Dolayısıyla mevcut bir belgenin _id değerini yeniden eklemeye çalışmak da aynı hataya yol açabilir. MongoDB’nin unique indeks açıklaması bu kuralı ve örneklerini gösterir.
Hata mesajındaki koleksiyon, indeks ve değer nasıl okunur?
Hata mesajında önce koleksiyon adını, ardından index: bölümünden indeks adını ve dup key: bölümünden çakışan değeri bul. Örneğin mesaj şu biçimde olabilir:
E11000 duplicate key error collection: app.users index: email_1 dup key: { email: "[email protected]" }Burada app.users, app veritabanındaki users koleksiyonunu belirtir. email_1, e-posta alanı için oluşturulmuş indeksin adıdır; dup key içindeki e-posta ise çakışmaya neden olan değeri gösterir. İndeks adı _id_ ise sorun _id değerinde olabilir. MongoDB belgelerindeki örnekler de hata mesajında koleksiyon, indeks ve yinelenen anahtar bölümlerini bu sırayla gösterir. insertOne belgesinde örnek bir _id çakışma mesajı bulunur.
Mesajı okuduktan sonra, hangi belgeyi yazmaya çalıştığını ve belirtilen değerin koleksiyonda zaten bulunup bulunmadığını kontrol et. Böylece bir sonraki adımda yeni belge eklemenin mi, var olan belgeyi güncellemenin mi uygun olduğunu belirleyebilirsin.
_id, eposta ve eksik alanlar neden çakışma oluşturur?
Çakışma, yeni bir belgenin değerleri koleksiyondaki bir indeksin benzersizlik kuralını ihlal ettiğinde oluşur. İndeks, bir alanın değerlerine göre kayıt bulmayı destekleyen yapıdır; unique indeks ise aynı indeks değerinin birden fazla belgede bulunmasını engeller.
Standart koleksiyonlarda MongoDB, her belge için benzersiz bir _id değeri kullanır. Aynı _id ile aynı belgeyi yeniden insertOne() ile eklemeye çalışmak, belgenin içeriği değişmemiş olsa bile çakışma yaratır. Yeni kayıt eklemek yerine mevcut kaydı güncellemek gerekiyorsa ekleme ve güncelleme yöntemini doğru seçmek gerekir.
Eposta adreslerinde de benzer kuralı uygulamak için eposta alanına unique indeks eklenebilir. Böylece aynı eposta değerini taşıyan ikinci bir belge eklenemez. Bu kural, uygulamanın aynı kullanıcı için tekrar tekrar kayıt oluşturmasını önlemeye yardımcı olur.
Tek alanlı unique indekste alanı olmayan belge ile değeri null olan belge, indeks açısından null değeriyle temsil edilir. Bu nedenle normal bir tek alanlı unique indekste bu tür değerlerden yalnızca bir indeks kaydı bulunabilir; birden fazla belgenin alanı eksikse veya null ise ekleme çakışabilir.
sparse unique indeks, alanı hiç bulunmayan belgeleri indeks dışında bırakır, fakat alanı açıkça null olan belgeleri indeksler. partial indeks ise benzersizlik kuralını yalnızca tanımlanan filtreye uyan belgelere uygular. Hangi seçeneğin uygun olduğu, alanı olmayan veya null değerli belgelerin uygulamadaki anlamına bağlıdır. MongoDB’nin unique indeks açıklaması bu davranışları örneklerle gösterir.
mongosh ile E11000 hatası nasıl yeniden oluşturulur?
Aşağıdaki komutlar, yalnızca deneme için ayrılmış yeni bir veritabanında eposta alanına unique indeks ekler ve aynı eposta değerini ikinci kez kaydetmeyi dener. Koleksiyon, belgelerin birlikte saklandığı yapıdır. Komutları üretim veritabanında değil, test veritabanında çalıştır.
use e11000_demo
db.kullanicilar.createIndex(
{ eposta: 1 },
{ unique: true }
)
db.kullanicilar.insertOne({
eposta: "[email protected]",
ad: "Ayşe"
})
db.kullanicilar.insertOne({
eposta: "[email protected]",
ad: "Ayşe Yılmaz"
})İlk ekleme başarılı olur. İkinci komut E11000 hatası verir; hata metninde collection: e11000_demo.kullanicilar koleksiyonu, index: eposta_1 indeksi ve dup key: { eposta: "[email protected]" } çakışan değeri gösterir. Bu örnekte hiçbir belgeyi silmek gerekmez. Üretim verisinde indeksi yalnızca hata mesajını ortadan kaldırmak için silmek, benzersizlik kuralını da kaldırabilir. Unique indeks oluşturma sözdizimi MongoDB belgelerinde açıklanır.
Çakışan kaydı upsert ile nasıl güvenli yönetebilirsin?
Çakışan kaydı yönetmek için önce belgeyi arayıp ardından ekleme veya güncelleme yapabilirsin. Diğer yaklaşımda ise upsert kullanılır. Upsert, filtreyle eşleşen belge varsa onu günceller, eşleşen belge yoksa yeni bir belge oluşturur. MongoDB’de bu davranış, updateOne() içine { upsert: true } seçeneği verilerek etkinleştirilir.
Önce arama yapan akış, kararın açıkça görülmesini sağlar. Kod önce findOne() ile epostayı arar, kayıt varsa updateOne() çalıştırır, yoksa insertOne() çağırır. Ancak bu işlem iki ayrı adımdan oluştuğu için her iki durumun ve arada oluşabilecek veri değişikliklerinin ayrıca yönetilmesi gerekir.
Eposta alanında unique indeks varsa aynı eposta değerinin birden fazla belgede bulunması engellenir. Bu alanı kaydın kimliği gibi kullanarak güncelleme ve ekleme kararını tek bir işlemde birleştirebilirsin:
db.kullanicilar.updateOne(
{ eposta: "[email protected]" },
{ $set: { ad: "Ada", aktif: true } },
{ upsert: true }
)[email protected] ile eşleşen belge mevcutsa işlem o belgeyi günceller ve sonuçta matchedCount: 1 görülür. Eşleşen belge yoksa filtredeki eposta ve $set içindeki alanlar kullanılarak yeni bir belge oluşturulur; bu durumda sonuçta matchedCount: 0 ve upsertedCount: 1 gibi alanlar yer alabilir.
Bu akışın aynı isteği tekrar çalıştırıldığında ikinci bir kullanıcı oluşturmak yerine mevcut kaydı güncellemesi, onu idempotent bir güncelleme akışına dönüştürür. Bunun için filtreyi değişmeyen ve benzersiz bir kimlik alanına dayandırmalısın. Eposta yerine kullanıcının adı, şehir bilgisi veya değişebilen bir durum alanı filtreye eklenirse mevcut belge eşleşmeyebilir ve upsert yeni belge oluşturmayı deneyebilir.
Eski indeks ve tekrar çalışan döngü nasıl teşhis edilir?
Eski veya unutulmuş bir unique indeksin çakışmaya neden olup olmadığını mongosh içinde getIndexes() ile inceleyebilirsin. Bu komut, koleksiyondaki mevcut indeksleri ve onları tanımlayan ayarları dizi biçiminde döndürür.
db.kullanicilar.getIndexes()Örnek bir çıktı şu yapıya sahip olabilir:
[
{ v: 2, key: { _id: 1 }, name: "_id_" },
{ v: 2, key: { eposta: 1 }, name: "eposta_1", unique: true }
]Burada key indeksin hangi alanı veya alanları izlediğini, name indeksin adını, unique: true ise benzersizlik kuralı uygulandığını gösterir. _id_ indeksini de listede görmen normaldir; MongoDB koleksiyon oluşturulduğunda _id alanı için benzersiz indeks oluşturur.
- Hata mesajındaki koleksiyon adını, uygulamanın gerçekten yazdığı koleksiyonla karşılaştır.
getIndexes()çıktısında hata mesajında görünen indeks adını veuniqueseçeneğini kontrol et.- Çakışan değerin eposta,
_idveya başka bir indeks alanında daha önce bulunup bulunmadığını ara. - Ekleme kodunun her çalışmada yeni
_idveya aynı eposta ile yeni belge üretip üretmediğini incele. - Seed, içe aktarma, kuyruğa alınmış iş veya başarısız işlem sonrası tekrar çalışan döngülerin aynı kaydı yeniden gönderip göndermediğini kontrol et.
İndeksi silmek, aynı kaydı tekrar oluşturan kodu düzeltmez ve veri modelinde gerekli olan benzersizlik kuralını kaldırabilir. Önce indeksin gerçekten gerekli olup olmadığını, mevcut verilerin bu kurala uyup uymadığını ve ekleme akışının neden tekrarlandığını değerlendir. Üretim verisinde indeks silme işlemini yalnızca hatayı ortadan kaldıran geçici bir çözüm gibi kullanma.
Sık Sorulan Sorular
E11000 duplicate key error her zaman _id alanındaki çakışmadan mı kaynaklanır?
E11000 hatası, _id alanının yanı sıra eposta gibi unique indeks uygulanmış başka bir alandaki veya alan birleşimindeki çakışmadan da kaynaklanabilir. Hangi alanın çakıştığını anlamak için hata mesajındaki indeks adını ve dup key bölümünü birlikte incelemelisin.
Unique indeks bulunan bir alan belgeye eklenmezse neden null çakışması oluşabilir?
Tek alanlı unique indekste alanı eksik olan belge, indeks açısından null değer taşıyor gibi değerlendirilir. Bu nedenle aynı alanı eksik olan ikinci belge, ilk belgeyle aynı indeks anahtarına sahip olur ve duplicate key hatası oluşturabilir.
E11000 hatasını gidermek için unique indeksi silmek doğru bir çözüm müdür?
Unique indeksi silmek genellikle doğru ilk çözüm değildir; çünkü tekrar eden kayıtların oluşmasına izin verebilir. Önce çakışan veriyi, indeksin iş kuralındaki amacını ve ekleme kodunu incelemeli, indeks kaldırılacaksa bunun bilinçli bir veri modeli değişikliği olduğundan emin olmalısın.
updateOne ile upsert kullanmak hangi durumlarda ikinci belgeyi oluşturmak yerine mevcut belgeyi günceller?
updateOne() filtresi mevcut belgeyle eşleştiğinde, upsert: true yeni belge oluşturmaz ve eşleşen belgeyi günceller. Filtreyi unique eposta gibi sabit ve benzersiz bir alana kurmak, aynı işlemin tekrarında doğru belgenin bulunmasına yardımcı olur.
E11000 hatasını kalıcı biçimde çözmek için hata mesajındaki indeksi, çakışan değeri ve kaydı oluşturan akışı birlikte değerlendir. Böylece yalnızca tek bir ekleme denemesini düzeltmek yerine veri modelini ve uygulama davranışını uyumlu hâle getirebilirsin.
