mongoimport: Loading JSON and CSV Files

mongoimport is a command-line tool bundled with the MongoDB Database Tools package. It loads data from JSON, JSONL (JSON Lines / newline-delimited JSON), and CSV files directly into a MongoDB collection. It is the standard way to seed a collection with initial data, migrate from another database, or bulk-load a data export from a third-party system.

The simplest mongoimport command specifies the connection string, database, collection, and input file. By default it expects a JSON array of objects ([{...},{...}]). The --jsonArray flag is required when importing a file that contains a JSON array; omit it for JSONL (one document per line) format.

JSONL (also called ndjson) stores one JSON document per line with no outer array wrapper. This format is preferred for large files because it can be streamed and processed line-by-line without loading the entire file into memory. mongoimport handles JSONL by default when you omit --jsonArray.

For CSV imports, specify --type csv and provide column headers. If the CSV file has a header row, use --headerline to read column names from the first row. If the file has no header row, list the column names with --fields. All CSV values are imported as strings by default—use --columnsHaveTypes to declare types.

When the CSV file lacks a header row, list the field names with the --fields flag. The order of names in --fields must match the column order in the CSV. This approach is common when importing exports from legacy systems that don't include headers.

mongoimport supports three write modes controlled by --mode:

• insert (default): insert all documents; fails on duplicate _id
• upsert: insert if not exists, replace if exists (matching on --upsertFields)
• merge: insert if not exists, merge fields if exists without replacing the whole document

The --drop flag drops the target collection before importing. This gives you a clean slate on each import, useful for seeding a development environment where you want to reset data to a known state. Do not use --drop in production if the collection holds data that should not be wiped.

To import into a MongoDB Atlas cluster, use the full Atlas connection string (SRV format) in the --uri flag. Atlas requires TLS—the SRV URI automatically enables it. You will need your Atlas username and password in the URI or passed via environment variables to avoid storing credentials in shell history.

mongoimport continues on non-fatal errors (like duplicate key violations on individual documents) by default and logs a count of failed documents at the end. Use --stopOnError to halt the import on the first error—useful when you need all-or-nothing import semantics. Check the exit code and error count in scripts to detect partial imports.

mongoimport is part of the MongoDB Database Tools package, which is installed separately from mongod. Verify it is installed with mongoimport --version. On Atlas clusters you can also use the Atlas UI's Data Import feature for small files, or Atlas Data Federation for larger data lake imports. Always match the tools version to your server version to avoid compatibility issues.

For large imports (millions of documents), these settings significantly improve throughput: (1) Use --numInsertionWorkers to parallelise insertions (default 1, try 4 for bulk loads); (2) Drop indexes before import and rebuild them after—index maintenance during bulk insert is expensive; (3) Use JSONL format instead of a large JSON array to enable streaming; (4) Import from a host close to the MongoDB server to minimise network latency.

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

In this lesson you learned: mongoimport loads JSON, JSONL, and CSV files into a collection via the command line, --mode upsert makes imports idempotent using a specified match field, and --numInsertionWorkers and dropping indexes before bulk imports improve performance. Next up we explore mongoexport for dumping collection data to files.