# MongoDB Introduction to the MongoDB Connector

Source: https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/deep-dive/introduction/

MongoDB is a document database. Instead of tables with fixed columns, it stores JSON-like documents in collections, and two documents in the same collection can hold different fields, nested sub-documents, and arrays. A MongoDB deployment can be a single server, a replica set, or a cluster hosted on MongoDB Atlas.

The Qualytics MongoDB connector reads the collections of a MongoDB database directly from the server. A Sync turns each collection into a container and works out its fields from a sample of its documents, so Qualytics can profile collections, run scheduled scans, and surface record- and schema-level anomalies on document data the same way it does on tables.

---

> **Note: Source datastores only**
>
> MongoDB is read-only, so it cannot be used as an enrichment datastore. Link a separate enrichment datastore as its destination to store the anomalies and metadata Qualytics produces, either [during creation](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-during-creation/) or [afterwards](https://userguide.qualytics.io/source-datastore/enrichment-datastore/how-tos/link-enrichment/).

## Notes

**What becomes a container.** Each collection in the selected database becomes a container, including time-series collections. Views and the `system.` collections are not listed. Each database you select in the form becomes its own datastore. The server's own `admin`, `config`, and `local` databases are never offered.

**How fields are worked out.** MongoDB has no fixed schema to read, so each Sync samples up to 10,000 documents per collection and builds the container's fields from what it finds. A collection with 10,000 documents or fewer is read in full. The fields are then kept as they are until the next Sync, so a profile or a scan always reads the same fields, even when new documents add a field the sample did not see. Run a Sync again to pick up fields that appeared since.

**Repeatable samples.** When a collection's `_id` values are ObjectIds, numbers, or dates, the sample is drawn through the `_id` index from the same points every time, so the same documents give the same fields on every Sync. When `_id` values are text, mixed, or compound, or the collection is a time-series collection, the sample is random and can differ between Syncs.

**Nested documents and arrays.** Sub-documents become nested fields and arrays become array fields, profiled and checked as described in [Complex Data Types](https://userguide.qualytics.io/container/complex-data-types/). A sub-document with more than 20 different keys across the sample is read as a map, whose frequent keys are promoted to fields of their own. Field names that contain a dot at the top level, such as a key named `a.b`, are kept apart from a nested `a.b`.

**Values of an unexpected type.** A document can hold a value whose type differs from the one the sample settled on for that field. Where the value converts, it is read as the field's type: the text `"12"` in a number field reads as `12`. Where it does not, only that field reads as empty for that document, and the rest of the document is read normally. The read does not stop.

**How MongoDB types are read.**

| MongoDB type | Read as |
| --- | --- |
| ObjectId | Text, as its hexadecimal value |
| Date | Timestamp |
| Decimal128 | Decimal. A value beyond 38 digits, NaN, or infinity is read as text |
| Timestamp | Its seconds; the increment is dropped |
| Binary data | Binary, keeping the bytes but not the subtype |
| Regular expression, JavaScript code, DBPointer, MinKey, MaxKey | Text, in MongoDB's extended JSON form |

**What the form does not ask for.** There is no connection string field. You give the host, the port, and the options as separate fields, and Qualytics builds the connection from them, so a password never has to be written into an address. There is no **Catalog** field either, because MongoDB has no level above the database; Qualytics works it out from the connection settings. The connector signs in with a user and password. Other MongoDB sign-in methods, such as X.509 certificates, LDAP, or Kerberos, are not offered.

---

## Deep Dive

- **Authentication**

  User and password sign-in, the Auth Source database, and when to leave both credentials empty.

  [Authentication](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/deep-dive/authentication/)
- **Examples**

  Worked scenarios: a MongoDB Atlas cluster, a self-hosted replica set, collections whose documents vary, and several databases at once.

  [Examples](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/deep-dive/examples/)
- **Best Practices**

  Recommendations for planning the connection, getting stable fields from the sample, and keeping operations fast.

  [Best Practices](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/deep-dive/best-practices/)
- **Permissions**

  The access your MongoDB deployment must grant, plus the Qualytics user role and team permission needed to manage the datastore.

  [Permissions](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/deep-dive/permissions/)

---

## How-tos

- **Add with New Connection**

  Add MongoDB as a source datastore and create its connection at the same time, field by field.

  [Add with New Connection](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/how-tos/add-new-connection/)
- **Add with Existing Connection**

  Add another database from a deployment you already connected, reusing a saved MongoDB connection.

  [Add with Existing Connection](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/how-tos/add-existing-connection/)

---

## Reference

- **Troubleshooting**

  Known problems and how to resolve them, grouped by the step that failed: reaching the server, signing in, or reading a collection.

  [Troubleshooting](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/troubleshooting/)
- **API**

  Create, test, read, update, and delete MongoDB datastores over the API, including bulk creation from several databases.

  [API](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/api/)
- **FAQ**

  Short answers to the questions that come up most often about Atlas, replica sets, sampling, and document fields.

  [FAQ](https://userguide.qualytics.io/source-datastore/datastore/native/mongodb/faq/)

*Last updated: November 3, 2026.*
