- Administration >
- Administration Concepts >
- Operational Strategies >
- Import and Export MongoDB Data
Import and Export MongoDB Data¶
This document provides an overview of the import and export programs included in the MongoDB distribution. These tools are useful when you want to backup or export a portion of your data without capturing the state of the entire database, or for simple data ingestion cases. For more complex data migration tasks, you may want to write your own import and export scripts using a client driver to interact with the database itself. For disaster recovery protection and routine database backup operation, use full database instance backups.
Warning
Because these tools primarily operate by interacting with a running
mongod
instance, they can impact the performance of your
running database.
Not only do these processes create traffic for a running database instance, they also force the database to read all data through memory. When MongoDB reads infrequently used data, it can supplant more frequently accessed data, causing a deterioration in performance for the database’s regular workload.
See also
MongoDB Backup Methods or MongoDB Cloud Manager Backup documentation for more information on backing up MongoDB instances. Additionally, consider the following references for the MongoDB import/export tools:
Data Import, Export, and Backup Operations¶
For resilient and non-disruptive backups, use a file system or block-level disk snapshot function, such as the methods described in the MongoDB Backup Methods document. The tools and operations discussed provide functionality that is useful in the context of providing some kinds of backups.
In contrast, use import and export tools to backup a small subset of your data or to move data to or from a third party system. These backups may capture a small crucial set of data or a frequently modified section of data for extra insurance, or for ease of access.
Warning
mongoimport
and mongoexport
do not reliably
preserve all rich BSON data types because JSON can
only represent a subset of the types supported by BSON. As a result,
data exported or imported with these tools may lose some measure of
fidelity. See the Extended JSON
reference for more information.
No matter how you decide to import or export your data, consider the following guidelines:
- Label files so that you can identify the contents of the export or backup as well as the point in time the export/backup reflect.
- Do not create or apply exports if the backup process itself will have an adverse effect on a production system.
- Make sure that they reflect a consistent data state. Export or backup processes can impact data integrity (i.e. type fidelity) and consistency if updates continue during the backup process.
- Test backups and exports by restoring and importing to ensure that the backups are useful.
Human Intelligible Import/Export Formats¶
This section describes a process to import/export a collection to a file in a JSON or CSV format.
The examples in this section use the MongoDB tools
mongoimport
and
mongoexport
. These tools may also be useful
for importing data into a MongoDB database from third party
applications.
If you want to simply copy a database or collection from one instance
to another, consider using the copydb
, clone
,
or cloneCollection
commands, which may be more suited to
this task. The mongo
shell provides the
db.copyDatabase()
method.
Collection Export with mongoexport
¶
You can use the mongoexport
utility you can create a backup
file.
Warning
mongoimport
and mongoexport
do not reliably
preserve all rich BSON data types because JSON can
only represent a subset of the types supported by BSON. As a result,
data exported or imported with these tools may lose some measure of
fidelity. See the Extended JSON
reference for more information.
In the most simple invocation, the command takes the following form:
This will export all documents in the collection named
collection
into the file collection.json
. Without the
output specification (i.e. “--out collection.json
”), mongoexport
writes output to
standard output (i.e. “stdout”). You can further narrow the results by
supplying a query filter using the “--query
”
and limit results to a single database using the
“--db
” option. For instance:
This command returns all documents in the sales
database’s
contacts
collection, with a field named field
with a value
of 1
. Enclose the query in single quotes (e.g. '
) to ensure
that it does not interact with your shell environment. The resulting
documents will return on standard output.
By default, mongoexport
returns one JSON document
per MongoDB document. Specify the
“--jsonArray
” argument to return
the export as a single JSON array. Use the “--csv
” file to return the result in CSV (comma
separated values) format.
If your mongod
instance is not running, you can use the
“--dbpath
” option to specify the
location to your MongoDB instance’s database files. See the following
example:
This reads the data files directly. This locks the data directory to
prevent conflicting writes. The mongod
process must not be
running or attached to these data files when you run mongoexport
in this configuration.
The “--host
” and “--port
” options allow you to specify a non-local host
to connect to capture the export. Consider the following example:
On any mongoexport
command you may, as above specify username and
password credentials as above.
Collection Import with mongoimport
¶
To restore a backup taken with mongoexport
. Most of the
arguments to mongoexport
also exist for
mongoimport
.
Warning
mongoimport
and mongoexport
do not reliably
preserve all rich BSON data types because JSON can
only represent a subset of the types supported by BSON. As a result,
data exported or imported with these tools may lose some measure of
fidelity. See the Extended JSON
reference for more information.
Consider the following command:
This imports the contents of the file collection.json
into the
collection named collection
. If you do not specify a file with
the “--file
” option,
mongoimport
accepts input over standard input
(e.g. “stdin.”)
If you specify the “--upsert
” option,
all of mongoimport
operations will attempt to update
existing documents in the database and insert other documents. This
option will cause some performance impact depending on your
configuration.
You can specify the database option --db
to import these documents to a particular database. If your
MongoDB instance is not running, use the “--dbpath
” option to specify the location of your
MongoDB instance’s database files. Consider using the
“--journal
” option to ensure that
mongoimport
records its operations in the journal. The
mongod
process must not be running or attached to these data
files when you run mongoimport
in this configuration.
Use the “--ignoreBlanks
” option
to ignore blank fields. For CSV and TSV imports, this
option provides the desired functionality in most cases: it avoids
inserting blank fields in MongoDB documents.