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

# How to connect

> How to connect the MongoDB data source to Adriel: allow-list the platform egress IP, create a read-only user, and bind a collection through the connection form.

MongoDB is a NoSQL document database. Connecting it binds a single MongoDB collection to an Adriel data source, sampling documents at setup to discover fields and compiling each widget load into an aggregation pipeline so document data appears in dashboards alongside SQL databases and marketing connectors.

## Before you connect

The following are required:

* A reachable MongoDB deployment (self-hosted, MongoDB Atlas, or a managed service).
* Network access from the platform egress IP `52.79.160.224`, including an Atlas IP access-list entry when applicable.
* A dedicated read-only database user.
* A MongoDB connection string (`mongodb://...` or `mongodb+srv://...`), or equivalent host, port, user, and password values.
* The target database name.
* The authentication source database (typically `admin` for Atlas, or the application database for self-hosted deployments).

## Connect MongoDB

<Steps>
  <Step title="Allow-list the egress IP and create a read-only user">
    Sign in to the MongoDB platform. Open the **Network Access** tab and click **+ ADD IP ADDRESS**, enter `52.79.160.224` in the **Access List Entry** field, and click **Confirm** to allow-list the platform egress IP. Then open the **Database Access** tab, click **Edit** under the **Actions** column, and configure the user: set **Authentication Method** to **Password**, set a **Password** and keep a record of it, and set the **Built-in Role** to **Atlas admin** (or, for self-hosted deployments, a user with the `read` role on the target database). Click **Add User**.
  </Step>

  <Step title="Copy the connection string">
    Open the **Database** tab and click **Connect**, then click **Compass**. Copy the connection string shown under **2. Copy the connection string, then open MongoDB Compass** — this is the database URL needed in the next step.
  </Step>

  <Step title="Enter the connection details">
    On the **Data Sources** page, search for **MongoDB** and select it. Fill in the connection URL copied in the previous step, and use the password set earlier for authentication.
  </Step>

  <Step title="Select the database and collections">
    Choose one **database** and its **collection(s)**. Each data source binds to a single database, and multiple collections are allowed. To connect more than one database, repeat this connection flow.
  </Step>

  <Step title="Set optional fields and submit">
    Optionally fill in the **Alternative Channel Name** to set a display name, and the **File Name to Filter** field to scope the connection to documents matching a name pattern. Click **Submit** to complete the connection. Initial data availability can take up to one business day.
  </Step>
</Steps>

## What gets imported

Each widget load compiles into a MongoDB aggregation pipeline executed against the bound collection. Numeric fields aggregate into metrics, and text, boolean, and date fields surface as breakdowns. Nested sub-documents are flattened using dotted path notation, and arrays are handled through pipeline operators rather than expanded into rows. A default 1,000-document limit applies to every pipeline result.

For the complete metric list, type mapping, and pipeline-stage behavior, see the [MongoDB data reference](/data-sources/g-n/mongodb/data-reference).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    Confirm the user exists in the configured authentication source. Atlas users almost always live in `admin`; self-hosted users typically live in the database where the role was granted. Update the auth-source field to match.
  </Accordion>

  <Accordion title="Connection timeout or refused">
    The deployment is unreachable from the platform egress IP range. Update the Atlas IP access list or firewall rules to include `52.79.160.224`, and confirm the connection string host and port are correct.
  </Accordion>

  <Accordion title="Cell shows a dash instead of a string value">
    Non-numeric fields default to a collected-set aggregation. When a single group contains more than one distinct value, the cell renders as `-` to keep the result scalar. Set an explicit aggregation on the field, or refine the breakdown so each group resolves to one value.
  </Accordion>

  <Accordion title="Some documents return NULL for an expected field">
    Documents in the same collection can have different shapes. Documents missing the field are returned as NULL. Reshape the collection upstream, or use a MongoDB view to enforce a consistent projection.
  </Accordion>

  <Accordion title="Results capped at 1,000 rows">
    A 1,000-document limit is applied to every pipeline. Tighten widget filters or pre-aggregate in MongoDB to keep results within the cap.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="MongoDB data reference" href="/data-sources/g-n/mongodb/data-reference">
    Metrics, type mapping, and pipeline-stage behavior for MongoDB.
  </Card>

  <Card title="MongoDB FAQs" href="/data-sources/g-n/mongodb/faqs">
    Common questions and expected behaviors for the MongoDB data source.
  </Card>

  <Card title="How to connect MySQL" href="/data-sources/g-n/mysql/how-to-connect">
    Connect a MySQL or MariaDB table as a SQL database alternative.
  </Card>

  <Card title="How to connect Postgres" href="/data-sources/o-z/postgres/how-to-connect">
    Connect a PostgreSQL database with richer filter operators.
  </Card>
</CardGroup>