Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

file 194 lines (146 sloc) 8.151 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
==============================
Import and Export MongoDB Data
==============================

.. default-domain:: mongodb

.. TODO incorporate review/feedback from audit of page after 2.6 to do
   a bit of rewrite on this page.

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 :term:`driver` to interact
with the database itself. For disaster recovery protection and routine
database backup operation, use full :doc:`database instance backups
</core/backups>`.

.. warning::

   Because these tools primarily operate by interacting with a running
   :program:`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.

.. seealso:: :doc:`/core/backups` or :mms:`MMS Backup Manual </backup>`
   for more information on backing up MongoDB instances. Additionally,
   consider the following references for the MongoDB import/export
   tools:

   - :doc:`/reference/program/mongoimport`
   - :doc:`/reference/program/mongoexport`
   - :doc:`/reference/program/mongorestore`
   - :doc:`/reference/program/mongodump`

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 :doc:`/core/backups` 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.

.. include:: /includes/warning-type-fidelity-loss.rst

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 :term:`JSON` or :term:`CSV` format.

The examples in this section use the MongoDB tools
:doc:`/reference/program/mongoimport` and
:doc:`/reference/program/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 :dbcommand:`copydb`, :dbcommand:`clone`,
or :dbcommand:`cloneCollection` commands, which may be more suited to
this task. The :program:`mongo` shell provides the
:method:`db.copyDatabase()` method.

Collection Export with :program:`mongoexport`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/warning-type-fidelity-loss.rst

With the :program:`mongoexport` utility you can create a backup
file. In the most simple invocation, the command takes the following
form:

.. code-block:: sh

   mongoexport --collection collection --out collection.json

This will export all documents in the collection named
``collection`` into the file ``collection.json``. Without the
output specification (i.e. ":option:`--out collection.json
<mongoexport --out>`"), :program:`mongoexport` writes output to
standard output (i.e. "stdout"). You can further narrow the results by
supplying a query filter using the ":option:`--query <mongoexport --query>`"
and limit results to a single database using the
":option:`--db <mongoexport --db>`" option. For instance:

.. code-block:: sh

   mongoexport --db sales --collection contacts --query '{"field": 1}'

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, :program:`mongoexport` returns one :term:`JSON document`
per MongoDB document. Specify the
":option:`--jsonArray <mongoexport --jsonArray>`" argument to return
the export as a single :term:`JSON` array. Use the ":option:`--csv
<mongoexport --csv>`" file to return the result in CSV (comma
separated values) format.

If your :program:`mongod` instance is not running, you can use the
":option:`--dbpath <mongoexport --dbpath>`" option to specify the
location to your MongoDB instance's database files. See the following
example:

.. code-block:: sh

   mongoexport --db sales --collection contacts --dbpath /srv/MongoDB/

This reads the data files directly. This locks the data directory to
prevent conflicting writes. The :program:`mongod` process must *not* be
running or attached to these data files when you run :program:`mongoexport`
in this configuration.

The ":option:`--host <mongoexport --host>`" and ":option:`--port
<mongoexport --port>`" options allow you to specify a non-local host
to connect to capture the export. Consider the following example:

.. code-block:: sh

   mongoexport --host mongodb1.example.net --port 37017 --username user --password pass --collection contacts --out mdb1-examplenet.json

On any :program:`mongoexport` command you may, as above specify username and
password credentials as above.

Collection Import with :program:`mongoimport`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/warning-type-fidelity-loss.rst

To restore a backup taken with :program:`mongoexport`. Most of the
arguments to :program:`mongoexport` also exist for
:program:`mongoimport`. Consider the following command:

.. code-block:: sh

   mongoimport --collection collection --file collection.json

This imports the contents of the file ``collection.json`` into the
collection named ``collection``. If you do not specify a file with
the ":option:`--file <mongoimport --file>`" option,
:program:`mongoimport` accepts input over standard input
(e.g. "stdin.")

If you specify the ":option:`--upsert <mongoimport --upsert>`" option,
all of :program:`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 :option:`--db <mongoimport --db>`
to import these documents to a particular database. If your
MongoDB instance is not running, use the ":option:`--dbpath
<mongoimport --dbpath>`" option to specify the location of your
MongoDB instance's database files. Consider using the
":option:`--journal <mongoimport --journal>`" option to ensure that
:program:`mongoimport` records its operations in the journal. The
``mongod`` process must *not* be running or attached to these data
files when you run :program:`mongoimport` in this configuration.

Use the ":option:`--ignoreBlanks <mongoimport --ignoreBlanks>`" option
to ignore blank fields. For :term:`CSV` and :term:`TSV` imports, this
option provides the desired functionality in most cases: it avoids
inserting blank fields in MongoDB documents.
Something went wrong with that request. Please try again.