- Reference >
- MongoDB Package Components >
mongoexport
mongoexport
¶
On this page
Mac OSX Sierra and Go 1.6 Incompatibility
Users running on Mac OSX Sierra require the 3.2.10 or newer version of mongoexport.
Synopsis¶
mongoexport
is a utility that produces a JSON or CSV export
of data stored in a MongoDB instance.
See the mongoimport document for more
information regarding the mongoimport
utility, which
provides the inverse “importing” capability.
Considerations¶
Warning
Avoid using mongoimport
and mongoexport
for
full instance production backups. They do not reliably preserve all rich
BSON data types, because JSON can only represent a subset
of the types supported by BSON. Use mongodump
and mongorestore
as described in MongoDB Backup Methods for this
kind of functionality.
To preserve type information, mongoexport
and mongoimport
uses the strict mode representation
for certain types.
For example, the following insert operation in the mongo
shell uses the shell mode representation for the BSON types
data_date
and data_numberlong
:
The argument to data_numberlong
must be quoted to avoid potential
loss of accuracy.
Use mongoexport
to export the data:
The exported data is in strict mode representation to preserve type information:
See MongoDB Extended JSON for a complete list of these types and the representations used.
Required Access¶
mongoexport
requires read access on the target database.
Ensure that the connecting user posseses, at a minimum, the read
role on the target database.
When connecting to a mongod
or mongos
that enforces
Authentication, ensure you use the required security
parameters based on the configured
authentication mechanism.
Read Preference¶
mongoexport
defaults to primary
read
preference when connected to a mongos
or a replica set.
You can override the default read preference using the
--readPreference
option.
Important
Using a non-primary read preference on a mongos
may
produce inconsistencies in data, including duplicates or missing
documents.
Options¶
Changed in version 3.0.0: mongoexport
removed the --dbpath
as well as related
--directoryperdb
and --journal
options. To use
mongoexport
, you must run mongoexport
against a running
mongod
or mongos
instance as appropriate.
Changed in version 3.0.0: mongoexport
removed the --csv
option. Use the
--type=csv
option to specify CSV format
for the output.
-
mongoexport
¶
-
--help
¶
Returns information on the options and use of mongoexport.
-
--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 mongoexport 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 mongoexport 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 mongoexport attempts to connect to a MongoDB instance running on the localhost on port number27017
.To connect to a replica set, specify the
replSetName
and a seed list of set members, as in the following:You can always connect directly to a single MongoDB instance by specifying the host and port number directly.
Changed in version 3.0.0: If you use IPv6 and use the
<address>:<port>
format, you must enclose the portion of an address and port combination in brackets (e.g.[<address>]
).
-
--port
<port>
¶ Default: 27017
Specifies the TCP port on which the MongoDB instance listens for client connections.
-
--ipv6
¶
Removed in version 3.0.
Enables IPv6 support and allows mongoexport to connect to the MongoDB instance using an IPv6 network. Prior to MongoDB 3.0, you had to specify
--ipv6
to use IPv6. In MongoDB 3.0 and later, IPv6 is always enabled.
-
--ssl
¶
New in version 2.6.
Enables connection to a
mongod
ormongos
that has TLS/SSL support enabled.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--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.Warning
For TLS/SSL connections (
--ssl
) tomongod
andmongos
, if the mongoexport runs without the--sslCAFile
, mongoexport will not attempt to validate the server certificates. This creates a vulnerability to expiredmongod
andmongos
certificates as well as to foreign processes posing as validmongod
ormongos
instances. Ensure that you always specify the CA file to validate the server certificates in cases where intrusion is a possibility.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--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 withoutallowConnectionsWithoutCertificates
.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--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 mongoexport 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 mongoexport will prompt for a passphrase. See TLS/SSL Certificate Passphrase.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--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.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--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.Starting in MongoDB 3.2.21, if you specify
--sslAllowInvalidCertificates
orssl.allowInvalidCertificates: true
when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS/SSL connection but is insufficient for authentication.Warning
For TLS/SSL connections to
mongod
andmongos
, avoid using--sslAllowInvalidCertificates
if possible and only use--sslAllowInvalidCertificates
on systems where intrusion is not possible.If the
mongo
shell (and other MongoDB Tools) runs with the--sslAllowInvalidCertificates
option, themongo
shell (and other MongoDB Tools) will not attempt to validate the server certificates. This creates a vulnerability to expiredmongod
andmongos
certificates as well as to foreign processes posing as validmongod
ormongos
instances.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslAllowInvalidHostnames
¶
New in version 3.0.
Disables the validation of the hostnames in TLS/SSL certificates. Allows mongoexport to connect to MongoDB instances even if the hostname in their certificates do not match the specified hostname.
For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslFIPSMode
¶
New in version 2.6.
Directs the mongoexport to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the
--sslFIPSMode
option.Note
FIPS-compatible TLS/SSL is available only in MongoDB Enterprise. See Configure MongoDB for FIPS for more information.
-
--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.Changed in version 3.0.0: If you do not specify an argument for
--password
, mongoexport returns an error.Changed in version 3.0.2: If you wish mongoexport to prompt the user for the password, pass the
--username
option without--password
or specify an empty string as the--password
value, as in--password ""
.
-
--authenticationDatabase
<dbname>
¶ If you do not specify an authentication database, mongoexport assumes that the database specified to export holds the user’s credentials.
-
--authenticationMechanism
<name>
¶ Default: SCRAM-SHA-1
Changed in version 2.6: Added support for the
PLAIN
andMONGODB-X509
authentication mechanisms.Changed in version 3.0: Added support for the
SCRAM-SHA-1
authentication mechanism. Changed default mechanism toSCRAM-SHA-1
.Specifies the authentication mechanism the mongoexport instance uses to authenticate to the
mongod
ormongos
.Value Description SCRAM-SHA-1 RFC 5802 standard Salted Challenge Response Authentication Mechanism using the SHA1 hash function. MONGODB-CR MongoDB challenge/response authentication. MONGODB-X509 MongoDB TLS/SSL certificate authentication. GSSAPI (Kerberos) External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise. PLAIN (LDAP SASL) 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.
-
--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.
-
--db
<database>
,
-d
<database>
¶ Specifies the name of the database on which to run the mongoexport.
-
--collection
<collection>
,
-c
<collection>
¶ Specifies the collection to export.
-
--fields
<field1[,field2]>
,
-f
<field1[,field2]>
¶ Specifies a field or fields to include in the export. Use a comma separated list of fields to specify multiple fields.
If any of your field names include white space, use quotation marks to enclose the field list. For example, if you wished to export two fields,
phone
anduser number
, you would specify--fields "phone,user number"
.For
csv
output formats,mongoexport
includes only the specified field(s), and the specified field(s) can be a field within a sub-document.For JSON output formats,
mongoexport
includes only the specified field(s) and the_id
field, and if the specified field(s) is a field within a sub-document, themongoexport
includes the sub-document with all its fields, not just the specified field within the document.
-
--fieldFile
<filename>
¶ An alternative to
--fields
. The--fieldFile
option allows you to specify in a file the field or fields to include in the export and is only valid with the--type
option with valuecsv
. The file must have only one field per line, and the line(s) must end with the LF character (0x0A
).mongoexport
includes only the specified field(s). The specified field(s) can be a field within a sub-document.
-
--query
<JSON>
,
-q
<JSON>
¶ Provides a query as a JSON document (enclosed in quotes) to return matching documents in the export. Specify JSON in strict format.
You must enclose the query document in single quotes (
'{ ... }'
) to ensure that it does not interact with your shell environment.For example, given a collection named
records
in the databasetest
with the following documents:{ "_id" : ObjectId("51f0188846a64a1ed98fde7c"), "a" : 1, "date" : ISODate("1960-05-01T00:00:00Z") } { "_id" : ObjectId("520e61b0c6646578e3661b59"), "a" : 1, "b" : 2, "date" : ISODate("1970-05-01T00:00:00Z") } { "_id" : ObjectId("520e642bb7fa4ea22d6b1871"), "a" : 2, "b" : 3, "c" : 5, "date" : ISODate("2010-05-01T00:00:00Z") } { "_id" : ObjectId("520e6431b7fa4ea22d6b1872"), "a" : 3, "b" : 3, "c" : 6, "date" : ISODate("2015-05-02T00:00:00Z") } { "_id" : ObjectId("520e6445b7fa4ea22d6b1873"), "a" : 5, "b" : 6, "c" : 8, "date" : ISODate("2018-03-01T00:00:00Z") } { "_id" : ObjectId("5cd0de910dbce4346295ae28"), "a" : 15, "b" : 5, "date" : ISODate("2015-03-01T00:00:00Z") }
The following
mongoexport
uses the-q
option to export only the documents with the fielda
greater than or equal to ($gte
) to3
and the fielddate
less thanISODate("2016-01-01T00:00:00Z")
(using the strict format for dates { “$date”: “YYYY-MM-DDTHH:mm:ss.mmm<offset>”}):mongoexport -d test -c records -q '{ a: { $gte: 3 }, date: { $lt: { "$date": "2016-01-01T00:00:00.000Z" } } }' --out exportdir/myRecords.json
The resulting file contains the following documents:
{"_id":{"$oid":"520e6431b7fa4ea22d6b1872"},"a":3.0,"b":3.0,"c":6.0,"date":{"$date":"2015-05-02T00:00:00Z"}} {"_id":{"$oid":"5cd0de910dbce4346295ae28"},"a":15.0,"b":5.0,"date":{"$date":"2015-03-01T00:00:00Z"}}
You can sort the results with the
--sort
option tomongoexport
.
-
--type
<string>
¶ Default: json
New in version 3.0.0.
Specifies the file type to export. Specify
csv
for CSV format orjson
for JSON format.If you specify
csv
, then you must also use either the--fields
or the--fieldFile
option to declare the fields to export from the collection.
-
--out
<file>
,
-o
<file>
¶ Specifies a file to write the export to. If you do not specify a file name, the
mongoexport
writes data to standard output (e.g.stdout
).
-
--jsonArray
¶
Modifies the output of
mongoexport
to write the entire contents of the export as a single JSON array. By defaultmongoexport
writes data using one JSON document for every MongoDB document.
-
--pretty
¶
New in version 3.0.0.
Outputs documents in a pretty-printed format JSON.
-
--slaveOk
,
-k
¶
Deprecated since version 3.2.
Sets the Read Preference to
nearest
, allowingmongoexport
to read data from secondary replica set members.--readPreference
replaces--slaveOk
in MongoDB 3.2. You cannot specify--slaveOk
when--readPreference
is specified.Warning
Using a read preference other than
primary
with a connection to amongos
may produce inconsistencies, duplicates, or result in missed documents.
-
--readPreference
<string>
¶ Specify the read preference for mongoexport.
mongoexport defaults to
primary
read preference when connected to amongos
or a replica set.Otherwise, mongoexport defaults to
nearest
.Warning
Using a read preference other than
primary
with a connection to amongos
may produce inconsistencies, duplicates, or result in missed documents.
-
--forceTableScan
¶
Forces
mongoexport
to scan the data store directly instead of traversing the_id
field index. Use--forceTableScan
to skip the index. Typically there are two cases where this behavior is preferable to the default:- If you have key sizes over 800 bytes that would not be present
in the
_id
index. - Your database uses a custom
_id
field.
When you run with
--forceTableScan
,mongoexport
may return a document more than once if a write operation interleaves with the operation to cause the document to move.Warning
Use
--forceTableScan
with extreme caution and consideration.- If you have key sizes over 800 bytes that would not be present
in the
-
--skip
<number>
¶ Use
--skip
to control wheremongoexport
begins exporting documents. Seeskip()
for information about the underlying operation.
-
--limit
<number>
¶ Specifies a maximum number of documents to include in the export. See
limit()
for information about the underlying operation.
-
--sort
<JSON>
¶ Specifies an ordering for exported results. If an index does not exist that can support the sort operation, the results must be less than 32 megabytes.
Use
--sort
conjunction with--skip
and--limit
to limit number of exported documents.See
sort()
for information about the underlying operation.
Use¶
Export in CSV Format¶
Changed in version 3.0.0: mongoexport
removed the --csv
option. Use the
--type=csv
option to specify CSV format
for the output.
In the following example, mongoexport
exports data from the
collection contacts
collection in the users
database in CSV
format to the file /opt/backups/contacts.csv
.
The mongod
instance that mongoexport
connects to is
running on the localhost port number 27017
.
When you export in CSV format, you must specify the fields in the documents
to export. The operation specifies the name
and address
fields
to export.
For CSV exports only, you can also specify the fields in a file containing the line-separated list of fields to export. The file must have only one field per line.
For example, you can specify the name
and address
fields in a
file fields.txt
:
Then, using the --fieldFile
option, specify the fields to export with
the file:
Changed in version 3.0.0: mongoexport
removed the --csv
option and replaced with
the --type
option.
Export in JSON Format¶
This example creates an export of the contacts
collection from the
MongoDB instance running on the localhost port number 27017
. This
writes the export to the contacts.json
file in JSON format.
Export from Remote Host Running with Authentication¶
The following example exports the contacts
collection in the
marketing
database from a remote MongoDB instance that requires
authentication.
Specify the:
Tip
Omit the --password
option to
have mongoexport
prompt for the password:
Export Query Results¶
You can export only the results of a query by supplying a query filter with
the --query
option, and limit the results to a single
database using the “--db
” option.
For instance, this command returns all documents in the sales
database’s contacts
collection that contain a field named dept
equal to "ABC"
and the field date
greater than or equal to
ISODate(“2018-01-01”) (using the strict format for dates
{ “$date”: “YYYY-MM-DDTHH:mm:ss.mmm<offset>”} )
You must enclose the query document in single quotes ('{ ... }'
) to ensure that it does
not interact with your shell environment.