mongoexport, bir MongoDB koleksiyonundaki belgeleri JSON veya CSV dosyası olarak dışa aktarır; mongoimport ise Extended JSON, CSV veya TSV dosyalarındaki verileri bir koleksiyona içe aktarır. Örneğin mongoexport --db=magaza --collection=urunler --out=urunler.json koleksiyonu her satırda bir belge olacak şekilde JSON'a yazar, mongoimport --db=magaza --collection=urunler --file=urunler.json aynı dosyayı geri yükler. İki araç da mongosh içinde değil, sistem komut satırında çalışır.
Belgelerin ısrarla vurguladığı nokta, bu araçların yedekleme için tasarlanmadığıdır. mongoexport ve mongoimport, veriyi yedekleyip geri yüklemek ya da kümedeki veriyi JSON gibi başka bir biçime çevirip tekrar kümeye yüklemek için uygun değildir; bu işler için mongodump ve mongorestore kullanılmalıdır. Bu yazıda iki aracın ne zaman doğru seçim olduğunu, JSON ve CSV ile çalışırken seçeneklerin nasıl davrandığını ve içe aktarmadaki --mode seçeneklerini örneklerle anlatıyoruz. Yedekleme için mongodump ve mongorestore yazısına bakın.
mongoexport ile mongodump arasındaki fark
| Özellik | mongoexport / mongoimport | mongodump / mongorestore |
|---|---|---|
| Biçim | JSON (Extended JSON v2), CSV, TSV | İkili BSON ve metadata dosyaları |
| Kapsam | Tek koleksiyon | Sunucu, veritabanı veya koleksiyon |
| İndeks tanımları | Taşınmaz | Metadata ile taşınır, geri yüklemede oluşturulur |
| Tür doğruluğu | Relaxed modda bazı BSON türleri kaybolabilir | BSON türleri korunur |
| Tipik kullanım | Tablo programı, başka sistemlerle veri alışverişi | Yedek, ortam kopyalama |
| Yedek için uygun mu | Hayır | Küçük dağıtımlar için evet |
Tür doğruluğu satırı önemlidir. JSON, BSON'un tüm veri türlerini doğal olarak taşıyamaz; MongoDB bu yüzden Extended JSON kullanır. mongoexport varsayılan olarak Extended JSON v2.0 Relaxed modunda yazar. Belgeler, zengin BSON türlerinin tamamını korumanız gerekiyorsa --jsonFormat=canonical verilmesini önerir. mongoimport içe aktarırken dosyadaki modu kendiliğinden tanır. Extended JSON ve BSON türleri için BSON veri tipleri yazısına bakabilirsiniz.
mongoexport ile JSON dışa aktarma
mongoexport için koleksiyon belirtmek zorunludur. Çıktı dosyası (--out) vermezseniz veri standart çıktıya yazılır. Yerel 27017 portundaki sunucu için host ve port yazmanıza gerek yoktur; uzak bir sunucu için --uri ya da --host ve --port kullanılır.
mongoexport --db=magaza --collection=urunler --out=urunler.json
mongoexport --uri="mongodb://10.0.0.5:27017/magaza" --collection=urunler --out=urunler.json
mongoexport --db=magaza --collection=urunler --jsonArray --pretty --out=urunler-dizi.json
mongoexport --db=magaza --collection=urunler --jsonFormat=canonical --out=urunler-canonical.jsonVarsayılan çıktıda her MongoDB belgesi için bir JSON belgesi yazılır. --jsonArray tüm çıktıyı tek bir JSON dizisine çevirir, --pretty belgeleri okunaklı biçimde girintiler. Dizi biçimiyle aldığınız dosyayı geri yüklerken mongoimport --jsonArray kullanmanız gerekir ve belgelere göre bu yol 16 MB veya daha küçük içe aktarmalarla sınırlıdır; büyük koleksiyonlar için varsayılan satır başına bir belge biçimi daha uygundur.
Alan seçmek için --fields verilir. JSON çıktısında davranış biraz farklıdır: belirttiğiniz alanlara ek olarak _id her zaman gelir ve alt belge içindeki bir alanı istediyseniz alt belgenin tamamı yazılır. Boşluk içeren alan adlarında listeyi tırnağa alın, örneğin --fields "telefon,kullanici no".
Sorgu, sıralama ve parça parça dışa aktarma
--query (kısaca -q) yalnızca eşleşen belgeleri dışa aktarır. Sorgu Extended JSON v2 biçiminde olmalı, alan adları ve operatörler tırnak içinde yazılmalıdır. Tarihler için $date sarmalayıcısı kullanılır. Kabukta sorguyu tek tırnakla sarmak $ işaretlerinin kabuk tarafından yorumlanmasını önler:
mongoexport -d=magaza -c=siparisler \
-q='{ "toplam": { "$gte": 500 }, "tarih": { "$lt": { "$date": "2026-01-01T00:00:00.000Z" } } }' \
--out=buyuk-siparisler.json--sort, --skip ve --limit imleç yöntemlerinin karşılığıdır ve büyük bir koleksiyonu parçalara bölerek dışa aktarmak için birlikte kullanılabilir. Belgelere göre sıralamayı destekleyen bir indeks yoksa sıralanan sonuç 32 megabayttan küçük olmalıdır; bu yüzden sıralama alanında indeks bulunması önemlidir. İndeksler için MongoDB index oluşturma, imleç yöntemleri için sort, limit ve skip yazılarına bakın.
mongoexport -d=magaza -c=siparisler --sort='{ "_id": 1 }' --limit=100000 --out=siparis.0.json
mongoexport -d=magaza -c=siparisler --sort='{ "_id": 1 }' --limit=100000 --skip=100000 --out=siparis.1.jsonCSV dışa aktarma
CSV için --type=csv verilir ve bu durumda dışa aktarılacak alanları --fields veya --fieldFile ile belirtmek zorunludur. CSV'de yalnızca belirttiğiniz alanlar yazılır ve alt belgedeki bir alanı nokta gösterimiyle seçebilirsiniz. Varsayılan olarak ilk satır alan adlarını içerir; --noHeaderLine bu başlık satırını kaldırır. --fieldFile ise her satırda bir alan adı bulunan, satırları LF karakteriyle biten bir dosya bekler ve yalnızca CSV ile geçerlidir.
mongoexport --db=magaza --collection=urunler --type=csv --fields=ad,fiyat,stok.adet --out=/opt/disa/urunler.csv
mongoexport --db=magaza --collection=urunler --type=csv --fieldFile=alanlar.txt --noHeaderLine --out=/opt/disa/urunler.csvmongoimport ile içe aktarma
mongoimport hedef veritabanını --db veya --uri ile alır; ikisi de verilmezse test veritabanını kullanır ve yoksa oluşturur. --collection verilmezse koleksiyon adı, uzantısı atılarak dosya adından alınır. --file verilmezse veri standart girdiden okunur. Varsayılan biçim JSON'dur; --type ile csv veya tsv seçilir.
mongoimport --db=magaza --collection=urunler --file=urunler.json
mongoimport --db=magaza --collection=urunler --jsonArray --file=urunler-dizi.json
mongoimport --db=magaza --collection=musteriler --type=csv --headerline --file=/opt/disa/musteriler.csvCSV ve TSV için birkaç seçenek yalnızca bu biçimlerde geçerlidir ve JSON ile kullanılırsa araç hata döndürür: --headerline ilk satırı alan adı olarak kullanır (verilmezse ilk satır ayrı bir belge olarak içe aktarılır), --fields ve --fieldFile başlık satırı olmayan dosyalar için alan adlarını verir, --ignoreBlanks boş hücreleri alan olarak oluşturmaz. CSV ayrıştırıcısı RFC 4180'e uyar; bu nedenle ters eğik çizgi geçerli bir kaçış karakteri değildir, çift tırnak içindeki çift tırnaklar başına bir çift tırnak daha eklenerek yazılır. Belgelere göre mongoimport yalnızca UTF-8 kodlanmış dosyaları destekler.
CSV sütunlarına tür vermek: --columnsHaveTypes
CSV'deki her şey metindir; posta kodu gibi bir alanın sayıya dönüşmesini ya da tarihin metin kalmasını istemiyorsanız sütun türünü başlıkta belirtebilirsiniz. --columnsHaveTypes ile alan adları ad.tür(argüman) biçiminde yazılır. Desteklenen türler arasında auto(), binary(base64), boolean(), date(...), date_go(...), date_ms(...), date_oracle(...), decimal(), double(), int32(), int64() ve string() bulunur; date(), Go dilinin time.Parse biçimini kullanan date_go()'nun takma adıdır.
ad.string(),fiyat.decimal(),stok.int32(),eklenme.date(2006-01-02 15:04:05),aktif.boolean()
Kalem,12.50,140,2026-03-01 09:30:00,truemongoimport --db=magaza --collection=urunler --type=csv --headerline --columnsHaveTypes \
--parseGrace=skipRow --file=urunler-turlu.csvBir hücre beklenen türe dönüştürülemezse ne olacağını --parseGrace belirler. Varsayılan stop hata verip içe aktarmayı sonlandırır; autoCast değere göre tür seçer, skipField o satırda yalnızca uyumsuz alanı atlar, skipRow uyumsuz değer içeren satırı hiç içe aktarmaz. Bu seçeneğin JSON içe aktarmasında etkisi yoktur.
Var olan belgelerle ne olur? --mode seçenekleri
Varsayılan mod insert'tür: dosyadaki belgeler eklenir ve _id gibi benzersiz indeksli bir alanda yinelenen değer varsa araç hata döndürür. Ancak belgelere göre mongoimport varsayılan olarak yinelenen anahtar ve belge doğrulama hatalarında işlemi sürdürür; ilk hatada durmasını istiyorsanız --stopOnError eklemelisiniz. Yinelenen anahtar hatasının kendisi için E11000 duplicate key hatası yazısına bakabilirsiniz.
| --mode | Eşleşen belge varsa | Eşleşme yoksa |
|---|---|---|
| insert (varsayılan) | Benzersiz indeks çakışmasında hata | Ekler |
| upsert | Mevcut belgeyi dosyadaki belgeyle tamamen değiştirir | Ekler |
| merge | Alanları birleştirir; dosyadaki değerler mevcutların üzerine yazar | Ekler |
| delete | Eşleşen tek bir belgeyi siler | Hiçbir şey yapmaz |
Eşleştirme varsayılan olarak _id alanıyla yapılır. Dosyadaki belgelerin _id değeri veritabanındakilerle aynı değilse ama başka bir alan belgeyi benzersiz olarak tanımlıyorsa --upsertFields ile eşleştirme alanlarını verirsiniz; belgeler performans için bu alanlarda indeks bulunmasını önerir. upsert ile merge arasındaki fark sık karıştırılır: upsert sonrası belgede yalnızca dosyadaki alanlar kalır, merge ise mevcut alanları korur, yeni alanları ekler ve ortak alanları dosyadaki değerle günceller.
mongoimport -d=magaza -c=urunler --mode=merge --upsertFields=sku --file=fiyat-guncelleme.json
mongoimport -d=magaza -c=urunler --mode=delete --upsertFields=sku --file=kaldirilacaklar.jsondelete modunda belgeler, dosyadaki her kayıt için yalnızca bir mevcut belge silindiğini belirtir; bu yüzden dosyadaki kayıtların veritabanında tek bir belgeyle eşleştiğinden emin olun. --drop seçeneği ise içe aktarmadan önce koleksiyonu ve indekslerini tamamen düşürür; bunu canlı bir koleksiyonda kullanmadan önce yedek alın.
Performans, sıra ve yazma onayı
mongoimport toplu ekleme ve güncellemeleri en fazla 100.000 belgelik gruplar halinde yapar. Varsayılan olarak tek bir ekleme işçisi (--numInsertionWorkers=1) kullanılır; belgeler büyük içe aktarmalarda işçi sayısını artırmanın hızı artırabileceğini söyler. Belge sırası varsayılan olarak garanti değildir; --maintainInsertionOrder sırayı korur, bunu yaparken --stopOnError'u açar ve işçi sayısını 1'e çeker. Yazma onayı (--writeConcern) varsayılan olarak majority'dir; bu seçenek bağlantı dizesindeki değerin önüne geçer. Yazma onayı kavramı için write concern ve read concern yazısına bakın.
Şema doğrulaması tanımlı bir koleksiyona doğrulamaya uymayan veriyi yüklemek için --bypassDocumentValidation vardır; bunu yalnızca bilerek kullanın (schema validation yazısı). Time series verisi içe aktaracaksanız koleksiyonu önce db.createCollection() ile oluşturmanız gerekir, çünkü mongoimport time series koleksiyonunu kendiliğinden oluşturmaz. Araç yarıda çökerse verinin yalnızca bir kısmı yüklenmiş olabilir; belgeler bu durumda yüklenen veriyi silip işlemi baştan çalıştırmanızı önerir.
Kimlik doğrulama ve gereken roller
Erişim denetimi açık sunucularda iki araç da --username, --authenticationDatabase ve isteğe bağlı --password ile ya da kullanıcı bilgisini içeren bir --uri ile bağlanır. Parolayı vermezseniz sorulur. mongoexport için kullanıcının hedef veritabanında en az read rolü, mongoimport için en az readWrite rolü olmalıdır.
mongoexport --host=10.0.0.5 --port=27017 --username=raporcu --authenticationDatabase=admin \
--db=magaza --collection=siparisler --out=siparisler.json
mongoimport --uri="mongodb://aktarici@10.0.0.5:27017/magaza?authSource=admin" \
--collection=urunler --file=urunler.jsonBu kullanıcıların nasıl oluşturulacağı kullanıcı ve rol yönetimi yazısında anlatılıyor. Araçlar, mongodump gibi --config ile parolayı bir YAML dosyasından da okuyabilir.
Uygulamalı örnek: fiyat listesini tabloda düzenleyip geri yüklemek
Senaryo: ürünlerin fiyatlarını bir tablo programında topluca düzenlemek istiyorsunuz. Önce yalnızca gerekli alanları CSV olarak dışa aktarırsınız. CSV çıktısına yalnızca listelediğiniz alanlar girdiği için, geri yüklerken eşleştirmede kullanacağınız benzersiz alanı (burada sku) listeye mutlaka ekleyin:
mongoexport --db=magaza --collection=urunler --type=csv --fields=sku,ad,fiyat --out=fiyatlar.csvDosyayı düzenledikten sonra başlık satırını tür bilgisiyle güncelleyip (sku.string(),ad.string(),fiyat.decimal()) merge moduyla geri yüklersiniz. --upsertFields=sku sayesinde belgeler sku alanına göre eşleşir, yalnızca dosyadaki alanlar güncellenir ve stok gibi diğer alanlar korunur:
mongoimport --db=magaza --collection=urunler --type=csv --headerline --columnsHaveTypes \
--mode=merge --upsertFields=sku --stopOnError --file=fiyatlar.csvBu akışta upsert kullansaydınız belgeler yalnızca sku, ad ve fiyat alanlarından oluşacak, diğer tüm alanlar silinecekti. Canlı veride böyle bir işlemden önce mongodump ile koleksiyonun yedeğini almak iyi bir alışkanlıktır.
Sık yapılan hatalar
- mongoexport çıktısını yedek olarak saklamak: İndeksler ve bazı tür bilgileri taşınmaz; yedek için
mongodumpkullanın. - CSV dışa aktarmada --fields vermemek:
--type=csvalan listesi olmadan çalışmaz. - Başlıklı CSV'yi --headerline olmadan içe aktarmak: Başlık satırı ayrı bir belge olarak eklenir.
- Hataların sessizce geçtiğini fark etmemek: Varsayılan olarak yinelenen anahtar ve doğrulama hatalarında devam edilir; kritik işlerde
--stopOnErrorekleyin. - upsert ile merge'ü karıştırmak:
upsertbelgeyi tamamen değiştirir. - UTF-8 olmayan dosya yüklemek: Diğer kodlamalar hata üretir; dosyayı önce UTF-8'e çevirin.
Sık Sorulan Sorular
mongoexport tüm veritabanını tek seferde dışa aktarabilir mi?
Hayır, mongoexport her çalıştırmada tek bir koleksiyonla çalışır ve koleksiyon belirtmek zorunludur. Birden çok koleksiyon için komutu her biri için ayrı çalıştırmanız gerekir; tüm veritabanının taşınması için mongodump daha uygundur.
JSON dosyasını uygulamamda nasıl okurum?
Varsayılan çıktı satır başına bir JSON belgesidir; tek bir dizi bekleyen bir okuyucu için --jsonArray kullanın. Tarih ve ObjectId gibi değerler Extended JSON sarmalayıcılarıyla ($date, $oid) gelir. JavaScript tarafında JSON ayrıştırma için JSON.parse ve JSON.stringify yazısına bakabilirsiniz.
mongoimport mevcut koleksiyonun indekslerini bozar mı?
Hayır; araç yalnızca belge ekler, günceller veya siler. İstisna --drop seçeneğidir: koleksiyonu indeksleriyle birlikte düşürür, sonra veriyi yükler. Bu durumda indeksleri yeniden oluşturmanız gerekir.
mongoexport ve mongoimport sürümleri farklı olabilir mi?
Belgeler genel olarak iki aracın sürümlerinin eşleşmesini, yani mongoexport ile üretilen veriyi karşılık gelen mongoimport sürümüyle yüklemenizi önerir. Eski Extended JSON v1 biçimindeki dosyalar için --legacy seçeneği vardır.
Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.
İlgili içerikler: MongoDB öğrenme rehberi · mongodump ve mongorestore · MongoDB BSON veri tipleri · insertOne ve insertMany · E11000 duplicate key hatası · JSON.parse ve JSON.stringify