When you use mongoimport to import files into MongoDB, you have the option of merging existing documents with the ones that you’re importing.

In this case, if an imported document has the same _id value as an existing one in the collection that you’re importing into, the existing document will be merged with the one being imported.

You can also specify another field (other than the _id field) to be the matching field if required.

When you merge documents, the resulting document will combine existing data with any new data that’s in the imported file. Any data that’s the same will remain the same. Any conflicting data will result in the imported file’s data overwriting the existing data. If an imported document doesn’t contain a field that’s in the corresponding document in the MongoDB collection, then that field will remain unchanged in the collection (i.e. it won’t be removed or changed).

The way to merge documents with mongoimport is to use merge mode.

Example

Suppose we have a collection called pets that contain the following documents:

db.pets.find()

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog" }
{ "_id" : 2, "name" : "Bark", "type" : "Dog" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }

And we have the following JSON file called pets.json:

{"_id":2.0,"name":"Fetch","type":"Dog","weight":40.0}
{"_id":3.0,"weight":10.0}
{"_id":4.0,"name":"Hop","type":"Kangaroo","weight":60.0}

The following command imports the JSON file into the collection:

mongoimport --db=PetHotel --collection=pets --mode=merge --file=data/pets.json

This uses merge mode to merge matching documents with the imported ones.

Check the Results

Let’s take a look at the collection now.

db.pets.find()

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog" }
{ "_id" : 2, "name" : "Fetch", "type" : "Dog", "weight" : 40 }
{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 10 }
{ "_id" : 4, "name" : "Hop", "type" : "Kangaroo", "weight" : 60 }

We can see that document 1 is unchanged, document 2 has had its name field changed to Fetch, and it has also had a weight field added.. Document 3 has also had a weight field added, and document 4 has been inserted.

Change the Upsert Field/s

You can use the --upsertFields parameter to specify a field other than _id to match against. When using this parameter, pass the fields as a comma separated list.

Suppose we have another JSON file called pets2.json that we want to import, and it looks like this:

{"name":"Wag","type":"Dog","weight":20.0,"gooddog":true}
{"name":"Bubbles","type":"Fish"}

This document doesn’t include the _id field, so we would need to match against other fields that uniquely identify each document. In this case we could use the name and type fields.

We can therefore use the following mongoimport command:

mongoimport --db=PetHotel --collection=pets --mode=merge --upsertFields=name,type --file=data/pets2.json

Now let’s check the collection again:

db.pets.find()

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog", "gooddog" : true, "weight" : 20 }
{ "_id" : 2, "name" : "Fetch", "type" : "Dog", "weight" : 40 }
{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 10 }
{ "_id" : 4, "name" : "Hop", "type" : "Kangaroo", "weight" : 60 }
{ "_id" : ObjectId("5ff0548dd991410169412300"), "name" : "Bubbles", "type" : "Fish" }

We can see that Wag has been updated (but the _id value remains the same).

Bubbles on the other hand, had no match for the upsert fields and was therefore inserted.

Check for mongoimport

mongoimport is part of the MongoDB Database Tools package. The MongoDB Database Tools are a suite of command-line utilities for working with MongoDB.

If you’re not sure whether you have the MongoDB Database Tools/mongoimport installed, try running the following command in your Terminal or Command Prompt to check:

mongoimport --version

If you have it, you should see version information, etc. If you don’t have it, you can use the installation instructions over at the MongoDB website to install it on to your system.

Where to Run the Commands?

Don’t forget, you need to run mongoimport commands from your system’s command line (e.g. a new Terminal or Command Prompt window).

Don’t run them from the mongo shell.