- Reference >
- MongoDB Package Components >
mongoimport
mongoimport
¶
On this page
Synopsis¶
The mongoimport
tool imports content from an
Extended JSON, CSV, or TSV export
created by mongoexport
, or potentially, another third-party export
tool. See the Import and Export MongoDB Data document for a more in depth
usage overview, and the mongoexport document for more
information regarding mongoexport
, which
provides the inverse “exporting” capability.
Considerations¶
Do not use mongoimport
and mongoexport
for
full instance, production backups because they will not reliably capture data type
information. Use mongodump
and mongorestore
as
described in MongoDB Backup Methods for this kind of
functionality.
mongoimport
is single-threaded and inserts one document at
a time into MongoDB. Custom import tools for data ingestion may have
better performance for specific workloads.
Options¶
-
mongoimport
¶
-
--help
¶
Returns information on the options and use of mongoimport.
-
--verbose
,
-v
¶
Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the
-v
form by including the option multiple times, (e.g.-vvvvv
.)
-
--quiet
¶
Runs the mongoimport in a quiet mode that attempts to limit the amount of output.
This option suppresses:
- output from database commands
- replication activity
- connection accepted events
- connection closed events
-
--version
¶
Returns the mongoimport release number.
-
--host
<hostname><:port>
,
-h
<hostname><:port>
¶ Default: localhost:27017
Specifies a resolvable hostname for the
mongod
to which to connect. By default, the mongoimport attempts to connect to a MongoDB instance running on the localhost on port number27017
.To connect to a replica set, specify the
replica set name
and a seed list of set members. Use the following form:You can always connect directly to a single MongoDB instance by specifying the host and port number directly.
-
--port
<port>
¶ Default: 27017
Specifies the TCP port on which the MongoDB instance listens for client connections.
-
--ipv6
¶
Enables IPv6 support and allows the mongoimport to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.
-
--ssl
¶
New in version 2.6.
Enables connection to a
mongod
ormongos
that has TLS/SSL support enabled.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslCAFile
<filename>
¶ New in version 2.6.
Specifies the
.pem
file that contains the root certificate chain from the Certificate Authority. Specify the file name of the.pem
file using relative or absolute paths.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
Warning
If the
mongo
shell or any other tool that connects tomongos
ormongod
is run without--sslCAFile
, it will not attempt to validate server certificates. This results in vulnerability to expiredmongod
andmongos
certificates as well as to foreign processes posing as validmongod
ormongos
instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.
-
--sslPEMKeyFile
<filename>
¶ New in version 2.6.
Specifies the
.pem
file that contains both the TLS/SSL certificate and key. Specify the file name of the.pem
file using relative or absolute paths.This option is required when using the
--ssl
option to connect to amongod
ormongos
that hasCAFile
enabled withoutweakCertificateValidation
.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslPEMKeyPassword
<value>
¶ New in version 2.6.
Specifies the password to de-crypt the certificate-key file (i.e.
--sslPEMKeyFile
). Use the--sslPEMKeyPassword
option only if the certificate-key file is encrypted. In all cases, the mongoimport will redact the password from all logging and reporting output.If the private key in the PEM file is encrypted and you do not specify the
--sslPEMKeyPassword
option, the mongoimport will prompt for a passphrase. See SSL Certificate Passphrase.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslCRLFile
<filename>
¶ New in version 2.6.
Specifies the
.pem
file that contains the Certificate Revocation List. Specify the file name of the.pem
file using relative or absolute paths.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslAllowInvalidCertificates
¶
New in version 2.6.
Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the
allowInvalidCertificates
setting, MongoDB logs as a warning the use of the invalid certificate.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslFIPSMode
¶
New in version 2.6.
Directs the mongoimport to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the
--sslFIPSMode
option.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--username
<username>
,
-u
<username>
¶ Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the
--password
and--authenticationDatabase
options.
-
--password
<password>
,
-p
<password>
¶ Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the
--username
and--authenticationDatabase
options.If you do not specify an argument for
--password
, mongoimport will prompt interactively for a password on the console.
-
--authenticationDatabase
<dbname>
¶ New in version 2.4.
Specifies the database that holds the user’s credentials.
-
--authenticationMechanism
<name>
¶ Default: MONGODB-CR
New in version 2.4.
Changed in version 2.6: Added support for the
PLAIN
andMONGODB-X509
authentication mechanisms.Specifies the authentication mechanism the mongoimport instance uses to authenticate to the
mongod
ormongos
.Value Description MONGODB-CR MongoDB challenge/response authentication. MONGODB-X509 MongoDB TLS/SSL certificate authentication. PLAIN External authentication using LDAP. You can also use PLAIN
for authenticating in-database users.PLAIN
transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise.GSSAPI External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise.
-
--gssapiServiceName
¶
New in version 2.6.
Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of
mongodb
.This option is available only in MongoDB Enterprise.
-
--gssapiHostName
¶
New in version 2.6.
Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.
This option is available only in MongoDB Enterprise.
-
--dbpath
<path>
¶ Specifies the directory of the MongoDB data files. The
--dbpath
option lets the mongoimport attach directly to the local data files without going through a runningmongod
. When run with--dbpath
, the mongoimport locks access to the data files. Nomongod
can access the files while the mongoimport process runs.
-
--directoryperdb
¶
When used in conjunction with the corresponding option in
mongod
, allows the mongoimport to access data from MongoDB instances that use an on-disk format where every database has a distinct directory. This option is only relevant when specifying the--dbpath
option.
-
--journal
¶
Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the . The mongoimport enables journaling by default on 64-bit builds of versions after 2.0.
-
--db
<database>
,
-d
<database>
¶ Specifies the name of the database on which to run the mongoimport.
-
--collection
<collection>
,
-c
<collection>
¶ Specifies the collection to import.
New in version 2.6: If you do not specify
--collection
,mongoimport
takes the collection name from the input filename. MongoDB omits the extension of the file from the collection name, if the input file has an extension.
-
--fields
<field1[,field2]>
,
-f
<field1[,field2]>
¶ Specify a comma separated list of field names when importing csv or tsv files that do not have field names in the first (i.e. header) line of the file.
-
--fieldFile
<filename>
¶ As an alternative to
--fields
, the--fieldFile
option allows you to specify a file that holds a list of field names if your csv or tsv file does not include field names in the first line of the file (i.e. header). Place one field per line.
-
--ignoreBlanks
¶
Ignores empty fields in csv and tsv exports. If not specified,
mongoimport
creates fields without values in imported documents.
-
--type
<json|csv|tsv>
¶ Specifies the file type to import. The default format is JSON, but it’s possible to import csv and tsv files.
The
csv
parser accepts that data that complies with RFC RFC 4180. As a result, backslashes are not a valid escape character. If you use double-quotes to enclose fields in the CSV data, you must escape internal double-quote marks by prepending another double-quote.
-
--file
<filename>
¶ Specifies the location and name of a file containing the data to import. If you do not specify a file,
mongoimport
reads data from standard input (e.g. “stdin”).
-
--drop
¶
Modifies the import process so that the target instance drops the collection before importing the data from the input.
-
--headerline
¶
If using
--type csv
or--type tsv
, uses the first line as field names. Otherwise,mongoimport
will import the first line as a distinct document.
-
--upsert
¶
Modifies the import process to update existing objects in the database if they match an imported object, while inserting all other objects.
If you do not specify a field or fields using the
--upsertFields
mongoimport
will upsert on the basis of the_id
field.
-
--upsertFields
<field1[,field2]>
¶ Specifies a list of fields for the query portion of the upsert. Use this option if the
_id
fields in the existing documents don’t match the field in the document, but another field or field combination can uniquely identify documents as a basis for performing upsert operations.To ensure adequate performance, indexes should exist for this field or fields.
-
--stopOnError
¶
New in version 2.2.
Forces
mongoimport
to halt the import operation at the first error rather than continuing the operation despite errors.
-
--jsonArray
¶
Accepts the import of data expressed with multiple MongoDB documents within a single JSON array. Limited to imports of 16 MB or smaller.
Use
--jsonArray
in conjunction withmongoexport --jsonArray
.
Use¶
In this example, mongoimport
imports the csv
formatted data in the /opt/backups/contacts.csv
into the
collection contacts
in the users
database on the MongoDB
instance running on the localhost port numbered
27017
. mongoimport
determines the name of files using
the first line in the CSV file, because of the --headerline
:
Since mongoimport
uses the input file name, without the
extension, as the collection name if -c
or --collection
is
unspecified. The following example is equivalent:
In the following example, mongoimport
imports the data in
the JSON formatted file contacts.json
into the collection
contacts
on the MongoDB instance running on the localhost port
number 27017.
In the next example, mongoimport
takes data passed to it on
standard input (i.e. with a |
pipe.) and imports it into the
MongoDB datafiles located at /srv/mongodb/
. if the import process
encounters an error, the mongoimport
will halt because of
the --stopOnError
option.
In the final example, mongoimport
imports data from the
file /opt/backups/mdb1-examplenet.json
into the collection
contacts
within the database marketing
on a remote MongoDB
database. This mongoimport
accesses the mongod
instance running on the host mongodb1.example.net
over port
37017
, which requires the username user
and the password
pass
.
Type Fidelity¶
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.
JSON can only represent a subset of the types supported by BSON. To
preserve type information, mongoimport
accepts strict
mode representation for certain
types.
For example, to preserve type information for BSON types
data_date
and data_numberlong
during
mongoimport
, the data should be in strict mode
representation, as in the following:
For the data_numberlong
type, mongoimport
converts into a float during the import.
See MongoDB Extended JSON for a complete list of these types and the representations used.