MongoDB

Overview

Signals reads customer and event documents straight from a MongoDB database on a schedule and sends the columns you nominate to your ad platforms.

Reading it directly means there is no file job to maintain and nothing to go stale between runs. Signals reads only; nothing is written back.

MongoDB stores documents in collections rather than rows in tables. Where this page says table name, enter the collection holding your records.

You can point it at a collection, or at a query. The query path is what you want when the shape Signals needs does not match anything you already have.

Two documents in the same collection need not carry the same fields. A field nobody wrote is absent rather than null, and the difference surfaces the moment you go looking for the gaps: a filter of { email: null } returns the documents holding an explicit null together with the documents that never had an email at all, because MongoDB counts both as a match. { email: { $exists: false } } isolates the second group and { email: { $type: 10 } } the first. A document with no email field contributes no email to the run, so a collection that looks complete by document count can be short of identifiers on a share of those documents that only a per-field check reveals.

Supported destinations

Destinations supported by MongoDB

Category	Supported
Offline Conversions	Google Offline Conversions API Google Store Sales LinkedIn Offline Conversions API Meta Offline Conversions API OpenAI Offline Conversions API Snapchat Offline Conversions API TikTok Offline Events API
Lead Conversions	Google Enhanced Conversions for Leads LinkedIn Leads Conversions API Meta Conversions API for CRM Snapchat Leads Conversions API TikTok CRM Integrations
Custom Audience	Google Customer Match Meta Custom Audience Snapchat Custom Audience TikTok Custom Audience

Authentication

In Studio, open Sources, find the Database category, and click the MongoDB tile.

Field	What it is	Where to find it
Authentication Name	Your own label for this set of credentials.	You choose it. Name it for the database it belongs to.
Username	The database user Signals connects as.	Created in the database by your administrator.
Password	The password for that user.	Set when the user was created.

Caution

Create a dedicated read-only user for Datahash rather than reusing an application or administrator account. It keeps the connection working when someone rotates a password, and it stops the connection seeing more than it needs. Enter the password on the Datahash connection screen only.

db.createUser acts on the database it is run against, and that database becomes the account’s authentication database whether or not it is the one holding your records:

use appdb
db.createUser({ user: 'datahash', pwd: '...', roles: [{ role: 'read', db: 'appdb' }] })

Run the same command after use admin and you get an account that authenticates against admin and reads appdb. That is a normal arrangement, and it is why the connection has to state where to authenticate as well as what to read. authSource carries that. A driver given no authSource falls back to the database named in the connection string, and to admin when the string names none, so an account created in appdb behind a connection that resolves to admin is looked up in a database that has never heard of it. MongoDB reports the outcome as an authentication failure, worded no differently from a mistyped password, which is how a working password ends up being reset two or three times before anyone asks which database holds the account. Where there is nowhere to name the authentication database, create the account in the database holding the data, so that the two are the same database and the question does not arise.

Keep the role scoped as { role: 'read', db: 'appdb' }. Its cluster-wide counterpart, readAnyDatabase, exists only in admin and covers every database on the deployment other than local and config, which is far more reach than reading one collection calls for and not the kind of grant anyone revisits once the connection works.

Configuration

Instance Setup

Select the Integration Type, which is the kind of data your records hold. Offline Events is the common choice. Give the instance a name, then choose the table path or the query path. On either path you enter the Database Name, Host Name and Port, whether to Use SRV, and then either the Collection Name or a query. An SRV connection carries no port of its own, so ask your Datahash representative what to put in Port when Use SRV is on.

The integration type decides the columns Signals expects and which destinations the connection can feed, so it is worth settling before anyone models the data. It also decides which file format you get on the next screen.

Port and the SRV form

27017 is where mongod answers unless it has been moved. An SRV connection has two requirements of its own: exactly one host name, and no port. A port supplied alongside it is a parse error rather than a value the driver works around, and that error arrives before any DNS lookup is attempted. What gets resolved is the host name with _mongodb._tcp. in front of it, and the SRV records published under that name carry the host and the port of each member, which is what lets the deployment add or move a node without anyone returning to this screen.

A TXT record on the same name may set replicaSet and authSource, and only those two: a TXT record carrying any other option makes the client fail rather than ignore it. An authSource supplied that way is worth looking for before anyone concludes that none is set. The +srv form also turns TLS on by default where the plain form leaves it off, so an SRV host name pointed at a deployment that does not serve TLS fails during the handshake rather than at the credentials.

Table path

Enter the connection details including the collection name, then complete the setup. The name is typed rather than picked from a list, so it has to match the database exactly.

Query path

Enter the connection details without the collection name, then write the query. Preview the results before finishing, and read the column names in the output rather than just the row count: a query that runs but returns the wrong names will fail silently once the connection is live.

Manage instance

One instance reads one table or query for one integration type. To read another, add another instance from the Manage existing instance table. To change an existing one, open it from there, click the edit option in the menu to the top right, update the fields and click Finish.

File format and schema

Download the file format from the setup screen and shape the collection to it. The column names are what Signals matches on, so a column that has been renamed or cased differently is not recognized and the row it belongs to is dropped rather than reported.

On the query path the same rule applies to the column aliases your query returns. Aliasing to the expected names is the usual way to reconcile data you cannot or should not restructure.

Data & identifiers

Personal identifiers are normalized and hashed before they are sent to a destination.

Best practices

• Use a dedicated read-only user scoped to the data Datahash reads, rather than an application account.
• Prefer the query path with explicit column aliases over pointing at a raw collection. It lets your team change the underlying model without breaking the connection.
• Ask your Datahash representative whether this connection can carry a read preference before anyone stands up a secondary for it. Drivers default to primary, and against a replica set that default settles where the query runs whatever member’s host name was entered, so the scheduled scan arrives at the primary anyway. readPreference=secondaryPreferred on the connection string is what moves it, and it brings staleness with it, since a secondary applies the oplog behind the primary and rs.printSecondaryReplicationInfo() is where that distance is reported.
• Clean the data in the view or query: lowercase email, phone in E.164, no stray whitespace. Hashing a badly formatted value produces a hash that will never match.
• Rotate the password periodically and update the connection afterwards.

Troubleshooting & FAQ

The connection times out rather than reporting bad credentials. That points at reachability rather than authentication. Confirm the host is exposed, the port is open, and any firewall or allow list permits the connection.

Credentials are rejected. Check the user can read the data from a client of its own first. Most failures here are permissions rather than typos.

The collection name is rejected. It is typed rather than selected, so it has to match exactly.

The query previews correctly but nothing is delivered. The column names it returns do not match the expected schema. Alias them to the names in the downloaded file format.

Credentials are rejected although the user exists. The user may authenticate against a different database than the one holding the data. Check which database it was created in.

An Atlas cluster turns the connection away while the same account works from someone’s laptop. Atlas accepts client connections only from the entries in its project IP access list, and that list belongs to the project rather than to one cluster, so it governs every cluster in the project at once. An address missing from it is refused at the network layer, ahead of any credential being looked at, and the client is left reporting a connection or server selection timeout with nothing in it about the user, which is what makes this read as an outage. Ask Datahash which addresses the connection originates from and put those on the list: a refused attempt names no address, so there is nothing to recover from a failed run. Atlas can also hold an entry that expires by itself inside a window you choose, as long as seven days, so an address added to get a first run through disappears later and takes the connection down with it.

The failure names DNS or a missing SRV record rather than the database. With Use SRV on, the deployment is located by resolving _mongodb._tcp. plus the host name, and a resolver that answers for the bare host name is no evidence that the SRV name resolves as well. Split-horizon DNS and networks that forward only some zones are where this happens. The standard form, a host name with 27017 or whatever port the members listen on, involves no SRV lookup at all, which is what to fall back to while the record is being published.

It was working and stopped. The password may have been changed or the user disabled. A dedicated service user avoids this.