When using mongoimport to import files into MongoDB, you have the option of specifying a mode to use. These modes determine what happens if there’s already matching documents in the collection that you’re trying to import into.

By default, mongoimport uses insert mode, but there are other modes you can use. The mode you use will depend on what you’re trying to do.

Below is an overview of each mode along with examples.

The Modes

The import modes available in mongoimport are as follows:

Mode	Description
insert	This is the default mode. This mode inserts the documents from the import file. If a matching document already exists in the collection, an error occurs. A matching document is one that has the same unique ID (such as a matching _id field) as a document in the import file.
upsert	Replaces existing documents in the database with matching documents from the import file. All other documents are inserted.
merge	Merges existing documents that match a document in the import file with the new document. All other documents are inserted.
delete	Deletes existing documents in the database that match a document in the import file. Any non-matching documents have no effect.

Examples of how each mode works is below.

Insert Mode

Suppose we have a collection called pets with the following documents:

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

As it turns out, those were imported in a file called pets.json.

Now imagine we have another JSON file called pets2.json, that contains the following JSON documents:

{ "_id" : 1, "weight": 40 }
{ "_id" : 2, "name" : "Bark", "type" : "Dog", "weight": 10 }
{ "_id" : 3, "name" : "Scratch", "type" : "Cat", "weight": 5 }
{ "_id" : 4, "name" : "Bubbles", "type" : "Fish", "weight": 3 }

Here’s what happens if we try to import that into our pets collection while using (the default) insert mode.

mongoimport --db=PetHotel --collection=pets --file=pets2.json

Output:

2021-01-03T10:07:23.421+1000	connected to: mongodb://localhost/
2021-01-03T10:07:23.422+1000	continuing through error: E11000 duplicate key error collection: PetHotel.pets index: _id_ dup key: { _id: 1 }
2021-01-03T10:07:23.422+1000	continuing through error: E11000 duplicate key error collection: PetHotel.pets index: _id_ dup key: { _id: 2 }
2021-01-03T10:07:23.422+1000	continuing through error: E11000 duplicate key error collection: PetHotel.pets index: _id_ dup key: { _id: 3 }
2021-01-03T10:07:23.423+1000	1 document(s) imported successfully. 3 document(s) failed to import.

According to that error message, only one of the four documents was imported. The other three caused an error due to having a duplicate key in the _id field.

Now let’s look at the collection.

db.pets.find()

Result:

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

So we can see that the last document was inserted. This is expected, because we didn’t previously have a document with an _id value of 4.

Upsert Mode

Here’s what happens if we use upsert mode to insert the same document.

mongoimport --db=PetHotel --collection=pets --mode=upsert --file=pets2.json

Output:

2021-01-03T10:19:55.400+1000	connected to: mongodb://localhost/
2021-01-03T10:19:55.444+1000	3 document(s) imported successfully. 0 document(s) failed to import.

The output tells us that 3 of the 4 documents were imported successfully, and that there were no failures.

Let’s check the collection.

db.pets.find()

Result:

{ "_id" : 1, "weight" : 40 }
{ "_id" : 2, "name" : "Bark", "type" : "Dog", "weight" : 10 }
{ "_id" : 3, "name" : "Scratch", "type" : "Cat", "weight" : 5 }
{ "_id" : 4, "name" : "Bubbles", "type" : "Fish", "weight" : 3 }

We can see that the first three documents have been replaced with the documents from the import file. The fourth document remains the same as it was after the previous import.

Notice that the first document has lost its name and type fields. This is because the upsert mode replaces the whole document, and our replacement document only has the weight field (as well as the _id field).

Merge Mode

Let’s modify our pets2.json file so that it looks like this:

{ "_id" : 1, "name": "Wag", "type": "Dog" }
{ "_id" : 2, "name" : "Fetch" }
{ "_id" : 3, "name" : "Scratch" }
{ "_id" : 4, "name" : "Bubbles" }
{ "_id" : 5, "name" : "Hop", "type": "Kangaroo" }

Now let’s run the mongoimport command again, but this time in merge mode:

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

Output:

2021-01-03T10:32:33.596+1000	connected to: mongodb://localhost/
2021-01-03T10:32:33.607+1000	3 document(s) imported successfully. 0 document(s) failed to import.

According to the output, 3 documents were imported.

Let’s take a look at the collection.

db.pets.find()

Result:

{ "_id" : 1, "weight" : 40, "name" : "Wag", "type" : "Dog" }
{ "_id" : 2, "name" : "Fetch", "type" : "Dog", "weight" : 10 }
{ "_id" : 3, "name" : "Scratch", "type" : "Cat", "weight" : 5 }
{ "_id" : 4, "name" : "Bubbles", "type" : "Fish", "weight" : 3 }
{ "_id" : 5, "name" : "Hop", "type" : "Kangaroo" }

We can see that documents 1 and 2 were updated, and document 5 was inserted. Regarding document 1, the weight field remained even though the import document didn’t include that field. This is because we used merge mode. If we’d used upsert mode (like in the previous example), the weight field would have disappeared.

Delete Mode

When you use delete mode, any matching documents are simply deleted. Non-matching documents remain in the collection.

So let’s see what happens when we import the same document, but this time switch over to delete mode.

mongoimport --db=PetHotel --collection=pets --mode=delete --file=pets2.json

Result:

2021-01-03T10:39:38.925+1000	connected to: mongodb://localhost/
2021-01-03T10:39:38.926+1000	5 document(s) deleted successfully. 0 document(s) failed to delete.

All 5 documents in the collection were deleted.

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

Not Sure if you have 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 mongoimport Commands?

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.