# Referencing: Linking Documents by \_id

Referencing links two documents by storing one's \_id in the other, like a customerId in each order, so shared or changing data lives in one place, at the cost of a second query to follow the link.

Apprentice · MongoDB · NoSQL · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Link documents by storing another document's \_id, such as customerId in an order, and follow the link with a second query
- Explain when referencing fits better than embedding, and what it costs, from a second query to links MongoDB doesn't check

## Key takeaways

- A reference is a field that holds another document's _id, such as customerId 1 in an order, pointing at customer 1.
- Following a reference takes a second query, one for each side of the link.
- Data that changes often, is shared by many documents, or is read on its own screen is usually referenced, so it lives in one place.
- MongoDB doesn't check a reference. An order can point at a customer who doesn't exist, so the app has to keep links right.

A customer with many orders, a post with many comments, a product sold in thousands of carts: whenever one piece of data is shared by many others, or changes and must look the same everywhere, you'll link documents instead of copying them. It's how an online store keeps one customer record that every order points to.

The examples use Riverbend's store from *Model for the Questions Your App Asks*. If you changed it in an earlier lesson, `load("riverbend-store.js")` puts it back as it started.

## When a copy has to keep up

*Embedding: Keeping Related Data Together* put each order's items inside the order. Why not put the customer inside too: her name, her email, her address? Then the order page could show "Ordered by Alex" with no second query.

Follow it a few months. Alex has placed 30 orders, so her details are copied into 30 documents. She changes her email. The shop has to find and change all 30 copies, and her customer document too. If one update is missed, the receipt email for order 18 goes to an address she stopped reading. The more often data changes, and the more documents share it, the worse copying gets.

## A reference: the customer's \_id in the order

A library card has your card number on it, not your whole life story. The library looks you up by the number when it needs more. A **reference** works the same way: a field that holds another document's `_id`. Each of Riverbend's orders holds `customerId`, the `_id` of the customer who placed it, and nothing else about her:

```mongodb
db.orders.findOne({ _id: 5003 }, { customerId: 1, total: 1 })
```

```text
{ _id: 5003, customerId: 1, total: 50 }
```

`customerId: 1` points at the customer whose `_id` is 1. To show "Ordered by Alex", follow the link with a second query:

```mongodb
db.customers.findOne({ _id: 1 }, { name: 1, email: 1 })
```

```text
{ _id: 1, name: 'Alex', email: 'alex@example.com' }
```

![Two cards side by side. The left card is order 5003, showing customerId 1 and total 50. An arrow runs from customerId 1 to the right card, customer 1, which shows the name Alex and the email alex@example.com. A label under the arrow says a second query follows the link.](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/1b5f0bd0623d4cd897e14df583eb7b71.webp)

Two queries, where an embedded customer would have taken one. The link works in the other direction too. "My orders" asks for every order that points at Alex:

```mongodb
db.orders.find({ customerId: 1 }, { total: 1 })
```

```text
[ { _id: 5001, total: 1288 }, { _id: 5003, total: 50 } ]
```

Riverbend's ids are small numbers, so your output matches this page. Most stores let MongoDB make an ObjectId for each `_id`, as *BSON Types and the _id Field* showed, and the reference then holds that ObjectId, such as `customerId: ObjectId("6740c2b1e4b0a1b2c3d4e5f6")`. It works the same way.

## One change, one place

Now Alex changes her email. Her details live in one document, so it's one update:

```mongodb
db.customers.updateOne({ _id: 1 }, { $set: { email: "alex.r@example.com" } })
```

```text
{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}
```

`modifiedCount: 1`: one document changed, and every order that points at customer 1 now leads to the new email. No copy is left behind.

## What a reference costs

**A second query.** Each link you follow is another trip to the database. For one order that's nothing; for a page of 50 orders, each showing its customer, it adds up. Module 4's *$lookup: Bringing in Related Documents* follows links inside one query.

**Nobody checks the link.** A relational database can refuse a row whose foreign key points nowhere. MongoDB doesn't. This order points at customer 99, and it goes in without a word:

```mongodb
db.orders.insertOne({ _id: 5006, customerId: 99, items: [], total: 0 })
```

```text
{ acknowledged: true, insertedId: 5006 }
```

```mongodb
db.customers.findOne({ _id: 99 })
```

```text
null
```

`null`: there is no customer 99. Keeping every reference pointing at a real document is your app's job, for example by checking that the customer exists before saving the order.

## When to reference

Reference when the data **changes often** and must look the same everywhere (a customer's email), when it's **shared by many** documents (one product in many orders), when it's **read on its own** screen (the customer's account page), or when the list of it **would grow without end** (all of a customer's orders). *Choosing by Relationship: One-to-Few, One-to-Many, Many-to-Many* turns these into rules of thumb.

## Check yourself

2 questions to try on the lesson page.

## So what

A reference keeps shared, changing data in one place, so one update reaches everything that points at it. You pay with a second query and a link that your app, not MongoDB, keeps honest.

## Key terms

- [Document Reference](https://www.ask-codey.com/glossary/document-reference)
- [\_id and ObjectId](https://www.ask-codey.com/glossary/id-and-objectid)
- [Embedding vs Referencing](https://www.ask-codey.com/glossary/embedding-vs-referencing)

## Related

- [Embedding: Keeping Related Data Together](https://www.ask-codey.com/lessons/mongodb-embedding-documents)
- [Choosing by Relationship: One-to-Few, One-to-Many, Many-to-Many](https://www.ask-codey.com/lessons/mongodb-choosing-by-relationship)
- [$lookup: Bringing in Related Documents](https://www.ask-codey.com/lessons/mongodb-aggregation-lookup)

Source: https://www.ask-codey.com/lessons/mongodb-referencing-documents
