MongoDB

MongoDB is in Preview in the connection wizard: it has not yet been proven against a live server, so check the imported tables before relying on them. Connect with a connection string, pick collections and review the proposed columns — each collection is imported as a table.

1. In DataSquares, open Data Sources and choose Connect Source. The Connect a data source page opens.

2. Pick MongoDB on that page (search or browse by category).

3. Fill in the connection details below, then test the connection and save.

Connection details

Field	What to enter
Source name	What the source is called in DataSquares (e.g. Shop orders).
Connection string	A mongodb:// or mongodb+srv:// connection string (e.g. mongodb+srv://reader:password@cluster0.example.net/). Stored encrypted; never shown again in full.
Database	The database to read collections from.

Use a read-only database user. The connection only reads, but DataSquares cannot enforce that on your server, so the user’s own permissions are the real guard. Every host the connection string names must be publicly reachable — a string that points at a private address is refused.

Choose Connect to test the connection. It lists the collections the user can read and shows how long the connection took.

Pick collections

Tick the collections to import. A collection that is a view is labelled as such. Each one you tick is sampled straight away so its columns can be proposed; untick it to drop it from the import.

Review the columns

DataSquares has no query language for MongoDB documents, so a collection is read through a column mapping that you review before anything is imported. For each collection the form states its bounds — for example columns proposed from 1,000 sampled documents of about 4,200,000 documents. A field that is absent from the sample is not proposed.

Each proposed column shows:

Column of the review	What it tells you
Import	Tick the fields you want. A field with no table representation (binary, timestamp or code) cannot be ticked.
Field	The path into the document (nested fields appear as parent.child).
Column	The column name in the table. It starts as the proposed name — edit it to rename.
Type	The detected type. A field whose type differs between documents is marked mixed types and is imported as text.
In sample	How many of the sampled documents contained the field.

An array is kept as JSON by default. Choose Unwind (one row per element) on it to get one row per element instead — the table then has more rows than the collection has documents, and the mapping is proposed again. To go back, choose Keep as JSON instead (or Stop unwinding).

Import

Choose Import & Create. It needs a source name and at least one collection, each with at least one column ticked. Each collection is imported as its own table through the mapping you reviewed, and the tables are staged in your workspace like any other staged source: models, dashboards and SQL read them from there.

The import is held to the same row and size limits as a file import; if a collection passes one, the message says which.

Refresh only what changed

Under each collection’s columns, On refresh chooses how a refresh reads it:

• Re-read the whole collection (the default) — every refresh reads every document again and replaces the table.
• Only new or changed documents, by a field — pick a field that only grows: a date such as updatedAt, a number, or _id (its value grows with creation time). A refresh then reads only documents whose field is at or past the highest value the last refresh saw, and replaces their rows by _id — so _id stays imported while this is on. New documents are added and changed ones updated; nothing is read twice into the table.

A document deleted in MongoDB is not seen by a refresh that reads only changes, and neither is a change that does not move the chosen field. Choose Full refresh in the source’s Refresh panel to re-read everything; it also removes deleted documents. A value that no longer fits its column’s type refuses the refresh with a message to run a full refresh, which retypes the table.

Refresh the source by hand (Refresh now) or on a schedule; through the API, POST /api/sources/{id}/resync with {"full": true} forces a full re-read.

Edit the mapping

Open the source’s Refresh panel and choose Edit mapping. The saved mapping is sampled again over the stored connection, so every column shows its type; a saved column the new sample no longer contains stays listed. You can rename, add or drop columns, unwind an array, change On refresh, and tick or untick collections. Each collection keeps the table it already has, so models and dashboards keep their bindings. Save and re-read re-reads every collection under the new mapping; removing a collection whose table holds rows asks first.

Related

• Connector catalog — everything DataSquares connects to.
• Quickstart — from connection to shared dashboard.