Relations

Link documents across databases and connections, where MongoDB's $lookup can't reach. Mongo Studio joins them for you, page by page, and shows every document's related documents: counts, sums and orphans included.

What it is

Real systems split their data. Orders live in one database, the shipments for them in another, often behind another connection with its own credentials. MongoDB's $lookup only joins collections of the same database, so answering "which orders were shipped twice?" or "which orders never shipped?" usually means exporting both sides and matching them by hand.

A relation is a saved link between two collections: "an order's shipments are the shipments whose orderRef is the order's orderId". Once it's saved, Mongo Studio joins the two sides itself, on the connections you already use, and shows the result where you work:

It works both ways: from an order you see its shipments, and from a shipment its order.

The running example

This page uses one setup throughout: a store platform where each store keeps its own orders, and a separate logistics service ships them.

Different databases, different connections, ids stored as binary on one side and text on the other, a suffix sometimes, an older format for old rows. All of it fits in one relation.

Concepts

TermWhat it means
From and ToThe two sides. The From side is where you usually start (orders); the To side is what you look up (shipments). Each side is a connection, a database and a collection.
{tenant} patternA collection name with a varying part: {tenant}_orders covers berlin_orders, lisbon_orders and the rest. The part that varies is the tenant (here, the store), and can be used in filters.
LinkA pair of fields that must match: orderId on the From side, orderRef on the To side. A link can also be built from several fields, like {customerId}-{orderId}.
Operatorequals; starts with, when the To value can carry a suffix (<uuid>-2); is in the array, when the From field is a list of ids.
Compare asHow values of different types meet: As stored, UUID (Binary 4) ↔ text, GUID .NET (Binary 3) ↔ text, ObjectId ↔ text, Number ↔ text.
RuleA set of links that must all match. A relation can have several rules: they're tried in order, and a later rule only runs for the documents earlier rules found nothing for. That's how old and new formats live in one relation.
Tenant filterA condition that always applies to the To side, like store = {tenant}: from berlin_orders, only Berlin's shipments can match. Going back, it's how a shipment finds its collection.
NamesWhat each side calls the other: from an order, "shipments"; from a shipment, "order". They label the Related section and the columns.
DraftA relation an AI agent proposed over MCP. Nothing uses it until you open it and save it.

How the join works

Nothing is copied and nothing is precomputed. When a page of documents is on screen, Mongo Studio finds their related documents with a few targeted queries:

For a page of orders from shop.berlin_orders, Mongo Studio reads the tenant from the collection name, picks the logistics connection (your pick, else the one on the same cluster), and the shipments collection filtered to the store. Rule 1 runs as one query for the whole page; rule 2 runs only for the rows rule 1 found nothing for. The found shipments are matched back to their rows and shown in the Related section, Related columns and the orphans filter.nothing foundboth rules' results1A page of documentsshop.berlin_ordersthe 50 rows on screen2Tenant{tenant}_orders→ berlin3Other connectionyour pick for this one,else the same cluster4Other collectionlogistics.shipmentsonly where store = "berlin"5Rule 1: one query for the page{ store: "berlin", customerRef: {$in: […]}, orderRef: … }15 s limit · at most 5,000 documents · by _id6Rule 2: only for the restrows rule 1 found nothing for{ store: "berlin", legacyRef: {$in: ["cust-order", …]} }7Match backeach found document goes tothe rows whose values it holdsRelated sectionthe selected order'sshipments, open in a tabRelated columnscount, count where, sum,exists, first · page totalsOrphansrows with none, ornot exactly one
Finding the shipments of a page of orders: the tenant, the connection, the collection, one query per rule, then the results matched back to each row.
  1. The page. Only the documents on screen are joined: 50 rows means 50 rows' worth of lookups, however big the collections are.
  2. The tenant comes from the collection's name, matched against the pattern.
  3. The other connection is the one you picked for this connection, or the one to the same cluster. See Connections and clusters.
  4. The other collection follows from the pattern and the tenant. It's never searched for: with hundreds or thousands of collections, the app doesn't list them to find it.
  5. Rule 1 runs as one query for the whole page, values converted as the links say (UUIDs to text here), the tenant filter included. It has a 15-second limit and reads at most 5,000 documents.
  6. Rule 2 runs only for the rows rule 1 found nothing for, and so on for each rule.
  7. The results are matched back to each row by the values they hold, and counted, summed or listed for the views.

Create a relation

Start wherever you notice the link:

It opens in its own tab, with the collection you started from as the From side. When other collections share its name's ending, it becomes a pattern: starting from berlin_orders gives {tenant}_orders.

  1. Pick the To side in Connections: the database and collection (both searchable), and which connection it lives on, usually The one on the same cluster.
  2. Link the fields. Click a field on the left, then its partner on the right. Or press Link on a suggestion: Mongo Studio compares samples of both sides and proposes the pairs that match, with how many sampled values did.
  3. Check each wire's chip. It shows the operator and the comparison; click it to change either, or to remove the link.
  4. Add the tenant filter under Tenant › Add a filter, if the To side is shared between tenants: store = {tenant}.
  5. Read the preview. Every sample document shows what it finds. None found and Several filter it to the surprises.
  6. Add a rule for an older format, under Rules › Add an alternative rule. A link's From side can be a template like {customerId}-{orderId}.
  7. Name the two sides under Names, run the Check, and Save.

The editor

The relation editor: the sample document on the left, the document it finds on the right, wires between linked fields, suggestions, the preview of every sample document, and the settings panel.Order shipmentsper clusterSave relationDiscard draftShop (prod) · any connection with shopshop · {tenant}_orders◉ berlin_orders‹ 1 of 20 ›_idobjectId6612…a0c9orderIduuid7f3c…b912customerIduuidc41e…08d2statusstringpaidtotaldecimal129.90createdAtdate2026-10-01 14:03Same cluster · Logistics (prod)logistics · shipments1 found for this sample_idobjectId6612…f122storestring= berlinorderRefstring7f3c…b912customerRefstringc41e…08d2statusstringDELIVEREDweightKgnumber2.4starts with · UUID ↔ textUUID ↔ text✦ SuggestedcustomerId ⇄ recipientRef41 of 50 sampled values matchLinkPreview20 documents · 3 found several · 14 found one · 3 found noneAll · Several · None found1c41e…08d214:03:59DELIVERED ×129a07…71b214:02:58DELIVERED ×1 RETURNED ×134e63…f90114:01:57none› Connections› Tenant› Rules› Names› Check1234567
The relation editor. The numbers are explained below.
  1. The sample document from the From side. Its collection is searchable among every tenant the pattern matches; the arrows step through the sample.
  2. The document it finds on the To side, and how many it found. With several, the arrows step through them. Fields the tenant filter covers show its value in green.
  3. The wires join linked fields. Each chip shows how they compare; click it to change it.
  4. Suggestions, from samples of both sides. Link adds one.
  5. The preview: every sample document and what it finds, with the rule that found it when it isn't the first.
  6. The settings, one line each until opened: Connections (and pairs), Tenant, Rules, Names, and Check.
  7. Save, and Delete; a draft has Save relation and Discard draft, with the agent's reason in a banner.

The check

Check › Test samples both sides (a few tenants of a pattern, a couple hundred documents) and reports how many documents each rule finds, how many find nothing in each direction, and whether the fields are indexed:

Check
✓ Sampled 61 orders in the 5 busiest of 20 tenants picked at random (of 340):
  rule 1 matched 39 · rule 2 matched 18 more · 4 have none (1–3 each, avg 1.3)
✓ Sampled 200 shipments in 5 tenants: 197 have an order · 3 don't
✓ Index store_1_customerRef_1 on shipments (rule 1)
! No index on shipments.legacyRef: rule 2 scans the collection.

A missing index comes with Create index…. It opens a console with the createIndex script, for a pattern a loop over its collections, and runs nothing until you press Run.

Use it

The Related section

Select a document in the grid: under its fields, Related lists each relation it takes part in, with the count and where the other side lives. Expand one to see the related documents, then Open all in a tab to get them as a filtered query on the other connection.

Related columns

The Related button above the results adds columns, joined for the rows on the page:

The footer totals each column for the page: for instance 58 shipments, 55 delivered, 3 returned, 47 orders shipped.

Orphans

Click a column's chip above the grid to show only the rows where it isn't 1, or, for an exists column, where the other side is missing. From the orders, shipments · exists filtered this way lists the orders that never shipped; from the shipments, order · exists lists the shipments without an order.

Connections and clusters

The To side's connection is set in Connections:

Pairs overrides it per From connection: pick the To connection by hand, or None to skip one. If the other connection isn't open, the Related section offers Connect; nothing is read until it is.

Relations over MCP

An AI agent connected through the MCP server often knows how two systems link, from their code. It can propose the relation; you decide whether it's kept.

The agent calls suggest_relation_links to find matching fields from samples, then create_relation, which saves a draft with its reason. Mongo Studio tells you, and you review the draft in its editor: preview, check, changes. Save relation puts it in use; Discard removes it. The agent can run test_relation to read the same check report.1suggest_relation_linkswhich fields link, from samples;no document values come back2create_relationsaved as a draft,with the agent's reason3You're told“Claude Code proposed arelation” · Open4Review in the editorpreview on samples, Check,change links, rules, namestest_relationthe Check report, for the agentSave relationit's in useDiscardit's gone
An agent proposes a relation: it looks for the links, saves a draft, and you review and save it.
ToolWhat the agent gets
list_relations, get_relationYour relations and drafts, in short or in full.
suggest_relation_linksField pairs that link two collections, with match rates from samples. No document values.
create_relation, update_relationSave or change a draft, with a reason you read in the banner. Agents only change drafts.
test_relationThe check report.
find_relatedJoins through a relation: per document, the count, the rule that found them, aggregates and up to five related documents.
delete_relationDeletes a draft an agent created.

A relation as the agent sends it, for the running example:

create_relation · relation
{
  "name": "Order shipments",
  "from": { "conn": "any",     "db": "shop",      "coll": "{tenant}_orders" },
  "to":   { "conn": "cluster", "db": "logistics", "coll": "shipments" },
  "rules": [
    [
      { "from": "customerId", "op": "eq",     "to": "customerRef", "as": "uuid-string" },
      { "from": "orderId",    "op": "prefix", "to": "orderRef",    "as": "uuid-string" }
    ],
    [
      { "from": "{customerId}-{orderId}", "op": "eq", "to": "legacyRef", "as": "uuid-string" }
    ]
  ],
  "ruleNotes": ["", "Shipments created before orderRef and customerRef existed."],
  "scope": [{ "to": "store", "value": "{tenant}" }],
  "fromName": "shipments",
  "toName": "order"
}

Things to ask an agent:

The capabilities are See relations and find related documents and Propose and test relations, in Settings › MCP server. find_related also needs Read documents and Read access to both connections.

Performance and safety

Troubleshooting

"No connection pairs with …"

No other saved connection has the same hosts. Pick the To connection in Connections › Pairs, or choose The From connection itself if it can read both databases.

Nothing found, but there should be

The preview says "capped"

The page's documents found more than 5,000 related documents. Counts and sums may be low; use a smaller page or a narrower filter.

The sample collection is a tiny tenant

Click its name in the From card and search for a busier tenant; the editor keeps sampling it.