Add a MongoDB Datastore with a New Connection¶

This page walks you through adding a MongoDB source datastore while creating its connection: every field the form asks for, section by section, followed by the steps to test and finish.

Once the datastore is created, run a Sync to discover the collections in the selected database. The Sync samples each collection's documents to work out its fields; see How fields are worked out.

Already have a connection?

To add a MongoDB datastore on a connection that already exists, go to Add with an Existing Connection.

Before you start, review the MongoDB Permissions and the Authentication page. The database user needs read access to the databases you want to monitor, and your MongoDB deployment has to accept connections from Qualytics.

Warning

MongoDB cannot be used as an enrichment datastore. After you add it as a source, link a separate enrichment datastore as its destination to store anomalies and metadata: either during creation or afterwards.

Field reference¶

After you choose New Connection, the form shows three sections. Connection Properties holds everything that belongs to the connection, including the Secrets Management group inside it. Location holds the database to monitor, and General holds the datastore's own settings.

Connection Properties¶

These fields define the MongoDB deployment Qualytics connects to and how it signs in. They belong to the connection, so they can be reused by other datastores later. Secrets Management, described next, sits inside this section.

Field	Type	Description
Connection Name	Text	A label for the saved connection (e.g., `acme_mongodb`), so other datastores can reuse it later.
Host	Text	A hostname, or a comma-separated `host:port` list for a replica set, for example `mongo-1.internal:27017,mongo-2.internal:27017`. With SRV, a single hostname without a port, such as `cluster0.abcde.mongodb.net`. Host names and ports only: credentials and options are not accepted here.
Port	Number	The port of a single host entered without one. Leave it empty for MongoDB's default, 27017. Not used with SRV, nor when Host already includes a port or lists several hosts, which carry their own ports.
DNS Seed List (SRV)	Option	No (the default) to connect to the hosts as entered, or Yes (mongodb+srv, e.g. Atlas) to look up the cluster's members through DNS. Use Yes for MongoDB Atlas.
SSL Connection	Checkbox	Encrypt the connection with TLS. Always on with SRV.
User	Text	The MongoDB database user Qualytics signs in as. Required when Password is filled in. Leave both empty only for a server without access control.
Password	Text	That user's password. Required when User is filled in. Stored encrypted and never displayed back.
Auth Source	Text	The database the user is defined in. Defaults to `admin`, which is where Atlas defines its database users. See The user and the Auth Source.

No connection string or Catalog field

The form takes the host, the port, and the options as separate fields instead of a mongodb:// connection string, so a password never has to be written into an address. MongoDB has no level above the database, so there is no Catalog field either.

Secrets Management¶

Also inside Connection Properties, and optional. Use it only if you want Qualytics to pull credentials from a secrets manager instead of typing them into the form. Turn on HashiCorp Vault to show the fields below. Despite the label, any secrets manager that exposes a compatible REST API works; see HashiCorp Vault.

Field	Type	Description
Login URL	Text	The full URL of the login endpoint (e.g., `https://vault.example.com/v1/auth/approle/login`). With Vault namespaces, add the namespace after `/v1/`, as in `/v1/<namespace>/auth/approle/login`.
Credentials Payload	Text	A JSON body containing the credentials Vault expects (e.g., `{"role_id":"...","secret_id":"..."}`).
Token JSONPath	Text	The JSONPath that extracts the client token from Vault's response. Defaults to `$.auth.client_token`.
Secret URL	Text	The full URL of the secret, including `https://` and the host (e.g., `https://vault.example.com/v1/secret/data/mongodb`). With Vault namespaces, add the namespace after `/v1/`.
Token Header Name	Text	The HTTP header name used to send the token. Defaults to `X-Vault-Token`.
Data JSONPath	Text	The JSONPath that extracts the key/value pairs from Vault's response. Use `$.data.data` for a KV version 2 secret (its API path contains `/data/`) and `$.data` for KV version 1 or the database secrets engine. The form pre-fills `$.data`.

Note

Reference a key from the secret in any Connection Properties field with ${key}, for example ${password}. Write it with braces (${key}, never $.key) and match the key name's case. Qualytics resolves it each time the connection is opened, so a changed value takes effect on the next connection. Setup steps, the namespace rule, and a troubleshooting page are on the HashiCorp Vault pages.

Location¶

Pick the MongoDB database Qualytics should read from. Unlike Connection Properties, this section belongs to the datastore rather than to the connection, so it is filled in on both flows.

Field	Required	Type	Description
Database		Option	One or more MongoDB databases to monitor. The dropdown is filled in once Qualytics connects to the deployment, and lists the databases the user can see, except MongoDB's own `admin`, `config`, and `local`. Each database you pick becomes its own Qualytics datastore.

General¶

The datastore's own settings.

Field	Type	Description
Name	Text	The datastore name in Qualytics. Comes suggested from the connection name and the database, so you can leave it blank to accept that suggestion.
Group	Option	Organizes your datastores under a shared group in the navigation tree. Select an existing group, or turn on Add New Group to create one.
Teams	Option	Select one or more teams to associate with this source datastore.
Initiate Sync	Checkbox	Ask Qualytics to run the first Sync for you once the datastore is created. You can always run a Sync yourself from the datastore afterwards.

Selecting more than one database

When you pick several databases in Location, each one becomes its own datastore and Name is replaced by Name Template, a naming pattern applied to all of them. Use {{schema}} as the placeholder for the database name: mongo_{{schema}} becomes mongo_sales, mongo_support, and so on. Left empty, each datastore is named from the connection name and its database.

Below the form, an information banner lists the Public addresses and Private addresses your datastore connections originate from. Allow the ones that match your network setup through your firewall rules or, on Atlas, the project's IP access list; see Permissions for the ports involved.

Steps¶

Step 1: Navigate to the Datastores page.

Step 2: Click the Add button at the top-right corner and choose Source from its menu.

Step 3: The Datastore step opens, the first of two.

Step 4: Select New Connection next to the Search field.

Step 5: Select MongoDB from the connector grid. Use the search field to filter connectors by name.

Step 6: Fill in the fields of Connection Properties, Location, and General, as described in the Field reference.

Step 7: Click Test connection. A success message confirms that the connection has been verified.

Info

The Finish and Next buttons stay disabled until the connection test passes on the current values. If you change a connection field after a successful test, test again. If the test fails, see Troubleshooting.

Step 8: Click Finish to create the datastore.

Tip

To link an enrichment destination so Qualytics can store anomalies and metadata from the first operation, click Next instead of Finish. See Link Enrichment on Datastore Creation.

Step 9: A success dialog confirms that your datastore has been added. Click Go to your datastore to open its page.