> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summation.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MongoDB
> Connect Summation to MongoDB Atlas or a self-managed MongoDB deployment.
The MongoDB connector lets Summation query collections as datasets. A connection targets one database, and each collection you select becomes a dataset available to Addison, reports, dashboards, and the modeler.
## What you'll need
* A MongoDB Atlas cluster or self-managed MongoDB deployment reachable from Summation.
* The database name and either a host or a MongoDB connection string.
* If authentication is enabled, a database user that can read the selected collections and run `listCollections`. MongoDB's built-in [`read` role](https://www.mongodb.com/docs/manual/core/security-built-in-roles/#mongodb-authrole-read) is a common starting point.
* For Atlas, an [IP access list](https://www.mongodb.com/docs/atlas/security/ip-access-list/) entry that permits connections from Summation.
For MongoDB Atlas, enter only the SRV hostname, such as `cluster0.abc123.mongodb.net`. Do not include `mongodb+srv://` in the **Host** field. Summation detects Atlas hostnames and uses SRV discovery automatically.
## Form fields
These fields are available in the connection wizard.
| Field | Config key | Required | Stored as | Notes |
| --------------------------- | ---------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| **Host** | `mongodb_host` | Yes | Config | MongoDB hostname or IP address. Enter a host only, without a scheme, credentials, path, or query string. |
| **Port** | `mongodb_port` | Yes | Config | MongoDB port. Default `27017`. Ignored when SRV discovery is enabled. |
| **Database** | `mongodb_db` | Yes | Config | Database containing the collections you want to query. |
| **Username** | `mongodb_user` | Optional | Config | MongoDB user. If set, **Password** is also required. |
| **Password** | `mongodb_pass` | Optional | Secret | MongoDB password. If set, **Username** is also required. |
| **Authentication database** | `mongodb_auth_source` | Optional | Config | Database that stores the user's credentials, commonly `admin`. Leave blank to use the target database. |
| **TLS mode** | `mongodb_sslmode` | Yes | Config | **required** (default) validates the server certificate and hostname. **disabled** uses plaintext. |
| **Flatten nested objects** | `mongodb_unnest_depth` | Optional | Config | Off by default. When enabled, flattens one level of embedded documents into columns. Arrays remain unchanged. |
Use **TLS mode: disabled** only for a trusted development network. It sends database traffic without TLS. Summation does not expose MongoDB's insecure `preferred` mode because that mode skips certificate and hostname validation.
## Connect to MongoDB Atlas
Add Summation's egress addresses to the Atlas project's IP access list.
Create a user with read access to the database and collections you want to expose.
Copy the hostname from the Atlas connection string. For `mongodb+srv://cluster0.abc123.mongodb.net/`, enter `cluster0.abc123.mongodb.net` as **Host**. Keep **TLS mode** set to **required**.
Click **Test connection**, then select the collections Summation should add as datasets.
## Advanced configuration
The connector API accepts these additional configuration fields. They are not currently shown in the connection wizard.
| Config key | Stored as | Default | Notes |
| ---------------------------------- | --------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mongodb_connection_string` | Secret | — | Alternative to discrete connection settings. Must start with `mongodb://` or `mongodb+srv://`. When authentication is required, include the credentials in the URI instead of also providing `mongodb_user` or `mongodb_pass`. See [MongoDB connection strings](https://www.mongodb.com/docs/manual/reference/connection-string/). |
| `mongodb_srv` | Config | Auto for `*.mongodb.net`; otherwise `false` | Uses DNS SRV discovery. When `true`, `mongodb_port` is ignored. |
| `mongodb_sslrootcert` | Config | — | Path to a custom PEM CA certificate available to the connector runtime. |
| `mongodb_direct_connection` | Config | `false` | Connects directly to one host instead of discovering the replica-set or sharded topology. |
| `mongodb_pool_min` | Config | `1` | Minimum connection-pool size. Must be `0` or greater and cannot exceed `mongodb_pool_max`. |
| `mongodb_pool_max` | Config | `5` | Maximum connection-pool size. Must be `1` or greater. |
| `mongodb_num_docs_to_infer_schema` | Config | `400` | Number of documents sampled when inferring collection schema. Must be `1` or greater. |
`mongodb_connection_string` and `mongodb_pass` are secrets. Send them in the connector's secrets payload, never in its non-secret config. Saved secret values are write-only and are not returned by the API.
## Schema inference and nested documents
MongoDB collections can contain documents with different fields and types. Summation samples `mongodb_num_docs_to_infer_schema` documents to establish the dataset schema.
Increase the sample count when fields are sparse or appear only in later documents. Larger samples improve coverage but make initial schema discovery slower.
Enable **Flatten nested objects** to expose the first level of embedded documents as columns. For example, `customer.region` becomes a column while deeper objects remain JSON strings. Arrays remain array values rather than being expanded into multiple rows. Leave the setting off to keep embedded documents as JSON values.
## Adding datasets
The connection wizard lists collections from the configured database. Source references use:
```text theme={null}
mongodb:orders
```
Collection names that require quoting use double quotes:
```text theme={null}
mongodb:"DailyOrders"
```
The wizard creates the correct source reference automatically.
## Common problems
| Error or symptom | Likely cause |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `MongoDB host is required` | Neither a host nor a secret connection string was provided. |
| `MongoDB username and password must be provided together` | Only one credential field is set. Provide both or clear both. |
| `MongoDB authentication failed: invalid credentials` | The username, password, or authentication database is wrong. Atlas users commonly authenticate against `admin`. |
| `MongoDB permission denied: insufficient privileges` | The user cannot list or read the selected database's collections. |
| TLS or certificate error | Keep **TLS mode** set to **required** and verify the server certificate. For a private CA, configure `mongodb_sslrootcert`. |
| Atlas connection times out | The Atlas IP access list does not permit Summation, DNS SRV lookup is blocked, or the hostname is incorrect. |
| A field is missing from the dataset | Increase `mongodb_num_docs_to_infer_schema`, then re-sync the dataset schema. |
| Nested fields appear as JSON strings | Edit the connector and enable **Flatten nested objects**. |