> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

> Sync Document data from MongoDB to marketing, sales and other business applications

## Overview

Hightouch lets you query data from collections and views stored in MongoDB and push it to downstream destinations. Most of the setup occurs in the Hightouch UI, but you need access to your MongoDB instance for information like your host, port, protocol, and credentials.

> [!NOTE]
>
> Make sure to allowlist Hightouch IP addresses so Hightouch can reach your cluster. Refer to our
> [IP address docs](https://docs.hightouch.com/security/networking#ip-addresses) to find the relevant IP addresses for your Hightouch region. If you are using Atlas, you can add allowlist IP addresses from **Security > Network Access**.

## Retrieve MongoDB credentials

The user whose credentials you use must have [`readAnyDatabase`](https://www.mongodb.com/docs/manual/reference/built-in-roles/#mongodb-authrole-readAnyDatabase) permission for Hightouch to correctly query your MongoDB collections. To create a user in MongoDB, use [`db.createUser()`](https://www.mongodb.com/docs/manual/reference/method/db.createUser/).

### Atlas

If you are using MongoDB Atlas, follow these instructions to retrieve your credentials:

1. Go to your cluster dashboard and click **Connect**.

   ![MongoDB Connect](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-mongo-connect-button.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=7a00c619b7325df9e782f39dbfa06065)

2. Choose **Connect your application**.

   ![MongoDB Connect Options](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-mongo-connect-app.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f4eb5f82ab9793b3a38b40a3aa2578e9)

3. Copy the hostname, username and connection options.

   ![MongoDB Connect URL](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/sources/source-mongo-credentials.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=f697d30248f72aec4983118262e8c699)

### Community and Enterprise versions

Use the hostname, username and password you use to connect to your MongoDB cluster. For more information, refer to the [MongoDB documentation](https://www.mongodb.com/docs/mongodb-shell/connect/#connect-to-a-deployment).

## Connection configuration

To get started in Higtouch, go to the [**Sources** overview page](https://app.hightouch.com/sources?from=docs) and click the **Add source** button. Select **MongoDB** and follow the steps below.

### Choose connection type

Hightouch can connect directly to MongoDB over the public internet or via an SSH tunnel. Since data is encrypted in transit via TLS, a direct connection is suitable for most use cases. You may need to set up a tunnel if your MongoDB instance is on a private network or virtual private cloud (VPC).

![Direct connection vs. SSH tunnel](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/get-started/connection-types-comparison.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=2300535707894b1f08608939cac812b2)

Hightouch supports both standard and reverse SSH tunnels. To learn more about SSH tunneling, refer to Hightouch's [tunneling documentation](https://docs.hightouch.com/security/ssh-tunneling.md).

### Configure your source

Enter the following required fields into Hightouch:

* **Host**: The hostname or IP address of your MongoDB server.
* **Protocol**: Hightouch supports [standard](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-standard-connection-string-format) or [SRV](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-dns-seedlist) protocol to connect to your cluster. If you are using MongoDB Atlas and the connection string begins with protocol
  `mongodb+srv`, choose the SRV protocol to connect.
* **Port**: The port number of your PostgreSQL server. The default port number is 27017, but yours may be different. You don't need to specify the port if you are using SRV protocol, as Hightouch uses the SRV record to look up hostname and port.
* **Username**: This can be your personal MongoDB login or a dedicated user for Hightouch.
* **Password**: This is the password for the user specified above.
* (Optional)**Connection options**: You can specify [connection options](https://www.mongodb.com/docs/manual/reference/connection-string/#connection-string-options) when connecting to your cluster. Use the format `name=value`, with each parameter separated by an ampersand `&`. For example, `retryWrites=true&connectTimeoutMS=30000`. See [MongoDB's docs](https://www.mongodb.com/docs/drivers/node/current/fundamentals/connection/connection-options/) for a list of parameters.

## Test your connection

When setting up MongoDB as a source for the first time, Hightouch checks that you have the correct permissions. Once the test passes, click **Continue** to finish setup.

## Create models

Once your source configuration has passed the necessary validation, your source setup is complete. Next, you can set up [models](https://docs.hightouch.com/getting-started/concepts.md#models) to define which data you want to pull from MongoDB.

### Model setup

1. In Hightouch, go to the [**Models** overview page](https://app.hightouch.com/models?from=docs).
2. Click **Add model.**
3. Select the MongoDB source you previously created.
4. Select the **Database** that contains the table you want to sync.
5. Select the **Collection/View** you want to sync.
6. Optionally, enter a **Filter** to apply to your query.
7. Preview your model's query results.
8. Click **Continue**.
9. Name your model and select its [**primary key**](https://docs.hightouch.com/models/creating-models.md#unique-primary-key-requirement). Hightouch uses the primary key to determine which rows have been added, changed, or removed since the last sync.

#### Collections and views

For advanced use cases, like joining data across collections or running aggregation pipelines, you can leverage [views](https://www.mongodb.com/docs/manual/core/views/#views) to pre-define the pipeline.
After [creating a view](https://www.mongodb.com/docs/manual/core/views/#create-and-manage-views), it automatically appears in the dropdown.
If you want to create a view that [only contains certain columns](https://www.mongodb.com/docs/v5.3/reference/method/db.createView/#create-a-view-from-a-single-collection) from your collection, you can use the [project operator](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/).

#### Filters

Refer to the MongoDB [Query documents documentation](https://www.mongodb.com/docs/manual/tutorial/query-documents/) to learn how to use filters.
For example, to query all the documents with an `account_id` equal to `20`, you can set this filter: `{ "account_id": 20 }`.

## Tips and troubleshooting

If you run into an issue this page doesn't cover, [contact support](#pylon-chat).