mongoexport-examples.txt

.. _mongoexport-examples:

=====================
mongoexport Examples
=====================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. facet::
   :name: genre
   :values: reference

.. facet::
   :name: programming_language
   :values: shell

.. |arrow| unicode:: U+27A4
.. |tool-binary| replace:: ``mongoexport``

This page shows examples for |tool-binary|.

Run |tool-binary| from the system command line, not the 
:binary:`~bin.mongo` shell.

Export in CSV Format
--------------------

.. _mongoexport-fields-example:

Export Data in CSV Format using ``--fields`` option
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the following example, ``mongoexport`` exports data from the
collection ``contacts`` collection in the ``users`` database in :term:`CSV`
format to the file ``/opt/backups/contacts.csv``.

The :binary:`~bin.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.

.. code-block:: sh

   mongoexport --db=users --collection=contacts --type=csv --fields=name,address --out=/opt/backups/contacts.csv

The output would then resemble:

.. code-block:: none

   name, address
   Sophie Monroe, 123 Example Road
   Charles Yu, 345 Sample Street

.. _mongoexport-fieldFile-example:

Use a File to Specify the Fields to Export in CSV Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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``:

.. code-block:: none

   name
   address

Then, using the :option:`--fieldFile <mongoexport --fieldFile>` option, specify the fields to export with
the file:

.. code-block:: sh

   mongoexport --db=users --collection=contacts --type=csv --fieldFile=fields.txt --out=/opt/backups/contacts.csv

.. _mongoexport-noHeaderLine-example:

Exclude Field Names from CSV Output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :option:`--noHeaderLine <mongoexport --noHeaderLine>` option can be
used to exclude field names in a CSV export. The following example
exports the ``name`` and ``address`` fields in the ``contacts``
collection in the ``users`` database and uses
:option:`--noHeaderLine <mongoexport --noHeaderLine>` to suppress the
output of the field names as the first line:

.. code-block:: sh

   mongoexport --db=users --collection=contacts --type=csv --fields=name,address --noHeaderLine --out=/opt/backups/contacts.csv

The CSV output would then resemble:

.. code-block:: none

   Sophie Monroe, 123 Example Road
   Charles Yu, 345 Sample Street

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

.. code-block:: sh

   mongoexport --db=sales --collection=contacts --out=contacts.json

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:

- :option:`--host <mongoexport --host>`

- :option:`--port <mongoexport --port>`

- :option:`--username <mongoexport --username>`

- :option:`--authenticationDatabase <mongoexport --authenticationDatabase>`

- :option:`--collection <mongoexport --collection>`

- :option:`--db <mongoexport --db>`

- :option:`--out <mongoexport --out>`

.. tip::

   Omit the :option:`--password <mongoexport --password>` option to
   have ``mongoexport`` prompt for the password:

.. code-block:: sh

   mongoexport --host=mongodb1.example.net --port=27017 --username=someUser --authenticationDatabase=admin --collection=contacts --db=marketing --out=mdb1-examplenet.json


Alternatively, you use the :option:`--uri <mongoexport --uri>` option to specify the host, port, username, authentication database, and db.

.. tip::

   Omit the password in the URI string to have ``mongoexport`` prompt
   for the password:

.. code-block:: sh

   mongoexport --uri='mongodb://someUser@mongodb0.example.com:27017/marketing?authsource=admin' --collection=contacts --out=mdb1-examplenet.json

Export Query Results
--------------------
You can export only the results of a query by supplying a query filter with
the :option:`--query <mongoexport --query>` option, and limit the results to a single
database using the ":option:`--db <mongoexport --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 :ref:`canonical format for dates
{ "$date": "YYYY-MM-DDTHH:mm:ss.mmm\<offset\>"} <extended-json-date>` )

.. code-block:: sh

   mongoexport --db=sales --collection=contacts --query='{"dept": "ABC", date: { $gte: { "$date": "2018-01-01T00:00:00.000Z" } }}'

.. include:: /includes/fact-quote-command-line-query.rst

.. _mongoexport-example-connect-using-aws-iam:

Connect to a MongoDB Atlas Cluster using AWS IAM Credentials
------------------------------------------------------------

.. versionadded:: 100.1.0

To connect to a :atlas:`MongoDB Atlas <?tck=docs_server>` cluster which has been 
configured to support authentication via `AWS IAM credentials 
<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html>`__,
provide a :option:`connection string <mongoexport --uri>` to
|tool-binary| similar to the following:

.. code-block:: none

   mongoexport 'mongodb+srv://<aws access key id>:<aws secret access key>@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' <other options>

Connecting to Atlas using AWS IAM credentials in this manner uses the
``MONGODB-AWS`` :urioption:`authentication mechanism <authMechanism>`
and the ``$external`` :urioption:`authSource`, as shown in this example.

If using an `AWS session token
<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html>`__,
as well, provide it with the ``AWS_SESSION_TOKEN``
:urioption:`authMechanismProperties` value, as follows:

.. code-block:: none

   mongoexport 'mongodb+srv://<aws access key id>:<aws secret access key>@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<aws session token>' <other options>

.. include:: /includes/fact-pct-encode-uri.rst

Alternatively, the AWS access key ID, secret access key, and optionally
session token can each be provided outside of the connection string
using the :option:`--username <mongoexport --username>`, :option:`--password <mongoexport --password>`, and
:option:`--awsSessionToken <mongoexport --awsSessionToken>` options instead, like so:

.. code-block:: none

   mongoexport 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS' --username <aws access key id> --password <aws secret access key> --awsSessionToken <aws session token> <other options>

When provided as command line parameters, these three options do not
require percent encoding.

You may also set these credentials on your platform using standard
`AWS IAM environment variables
<https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html#envvars-list>`__.
|tool-binary| checks for the following environment variables when you
use the ``MONGODB-AWS``
:urioption:`authentication mechanism <authMechanism>`:

- ``AWS_ACCESS_KEY_ID``
- ``AWS_SECRET_ACCESS_KEY``
- ``AWS_SESSION_TOKEN``

If set, these credentials do not need to be specified in the connection
string or via their explicit options.

.. note::

   If you chose to use the AWS environment variables to specify these
   values, you cannot mix and match with the corresponding explicit or 
   connection string options for these credentials. Either use the
   environment variables for access key ID *and* secret access key
   (*and* session token if used), **or** specify each of these using the
   explicit or connection string options instead.

The following example sets these environment variables in the ``bash``
shell:

.. code-block:: none

   export AWS_ACCESS_KEY_ID='<aws access key id>'
   export AWS_SECRET_ACCESS_KEY='<aws secret access key>'
   export AWS_SESSION_TOKEN='<aws session token>'

Syntax for setting environment variables in other shells will be
different. Consult the documentation for your platform for more
information.

You can verify that these environment variables have been set with the
following command:

.. code-block:: none

   env | grep AWS

Once set, the following example connects to a MongoDB Atlas cluster
using these environment variables:

.. code-block:: none

   mongoexport 'mongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB-AWS'  <other options>

Learn More
----------

- :ref:`mongoexport`
- :ref:`mongoexport-compatibility-and-installation`
- :ref:`mongoexport Behavior <mongoexport-behavior>`