# Shaping a Document: Embed or Reference

Related data either goes inside a document, embedded, when it is read with it, or lives in its own collection and is pointed to by its \_id, referenced, when it is shared, changes on its own or grows without end.

Journeyman · MongoDB · NoSQL · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Embed related data inside a document when it is read together, such as a plant's care tips, and read it with dot notation
- Choose between embedding and referencing by asking whether the data is read together, shared by other documents, or grows without end

## Key takeaways

- Embedding puts related data inside the document it belongs to, such as a plant's care details inside the plant, so one read gets it all.
- Referencing keeps the data in its own collection and stores its _id instead, such as an order's customerId, so it lives in one place.
- Embed what is read together with the document. Reference what other documents share or what changes on its own.
- A list that can grow without end, such as every review a plant will ever get, goes in its own collection. A document can't grow past 16 MB.

Before you save a single document, you decide its shape, and that choice decides how much work every page of your app does. Get it right and a page reads one document. Get it wrong and the same page needs ten reads, or a document keeps growing until it can't. You'll make this choice every time you design a new collection.

Fern & Fig's plant page shows each plant with its care details: the light it needs, how often to water it, and a few tips. The shop also takes orders, and each order belongs to a customer. Where should the care details and the customer go?

## Embedding: what's read together, kept together

Think of a seed packet. The growing instructions are printed right on the back, so whoever picks up the packet has everything at once. Nobody keeps the instructions in a separate binder.

The plant page always shows the care details with the plant, and no other plant shares them. So they go inside the plant's document, as a document of their own. That's **embedding**, and the inner document is an **embedded document**. You read its fields with **dot notation**, a dot for each step inside (`plant.care.light` is read "plant dot care dot light"):

```javascript
const plant = {
  name: "Boston Fern",
  price: 22,
  petSafe: true,
  care: {
    light: "bright, indirect",
    water: "keep the soil damp",
    tips: ["Mist the leaves in dry weather.", "Keep it away from heaters."],
  },
};

console.log(plant.care.light);
console.log(plant.care.tips[0]);
console.log(plant.care.tips.length);
```

```text
bright, indirect
Mist the leaves in dry weather.
2
```

One read of the plant brings its care details along. That's the whole point.

## Referencing: data that lives in one place

Now the orders. Dana has placed 40 orders over two years. If her address were copied into each one, moving house would mean changing 40 documents, and missing one sends a fern to her old door.

So the customer gets a document in a `customers` collection, and each order stores only the customer's `_id`, in a field such as `customerId`. That's **referencing**: the order points at the customer, the way a library card points at a member. The arrays below stand in for the two collections, with small numbers as ids so they're easy to read:

```javascript
const customers = [
  { _id: 1, name: "Dana", address: "12 Elm Street" },
  { _id: 2, name: "Marco", address: "48 Lake Road" },
];
const orders = [
  { _id: 101, customerId: 1, items: [{ name: "Boston Fern", price: 22 }] },
  { _id: 102, customerId: 2, items: [{ name: "Snake Plant", price: 24 }, { name: "Spider Plant", price: 14 }] },
  { _id: 103, customerId: 1, items: [{ name: "Calathea", price: 32 }] },
];

const order = orders[1];
const customer = customers.find((c) => c._id === order.customerId);
console.log(`Order ${order._id}: ${order.items.length} plants for ${customer.name}, ${customer.address}`);
```

```text
Order 102: 2 plants for Marco, 48 Lake Road
```

Orders 101 and 103 both point at Dana, whose address is written down once. The price of a reference is a second lookup to fetch the customer. Notice that each order still embeds its items: what was bought, at the price paid that day, belongs to that order and is always shown with it.

## The questions that decide

![Embedding and referencing side by side: on the left, a plant's document holds its care details inside it; on the right, two orders each hold a customerId that points to the same customer's document in its own collection](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/9d40a0d4acd3438aae5e00e0c641ddca.webp)

Ask these about each piece of related data:

| Question | If yes |
|---|---|
| Is it read together with the document, nearly every time? | Embed it |
| Do other documents share it, such as one customer behind many orders? | Reference it |
| Does it change on its own, apart from the document? | Reference it |
| Can the list grow without end? | Give it its own collection |

The first question is the one that decides most cases: is it read together? A plant's care details always are, so they're embedded. A customer is read with many orders and changes on their own, so the customer is referenced.

## Lists that grow without end

Fern & Fig adds reviews. Embedding every review inside its plant looks tidy, until the Snake Plant has 3,000 of them. Every read of the plant now drags all 3,000 along, and the document keeps growing. MongoDB stops a document at 16 MB, so a list with no end will one day fail to save.

A list like that gets its own collection: each review is a document with a `plantId` that points at its plant. The plant page then asks for the newest few reviews, not all of them. MongoDB in Depth teaches more document shapes like these; the three questions above cover every API in this course.

## Do it: shape a plant from the shop's form

Fern & Fig's staff add plants through a form with one box per field and three boxes for care tips. The form's answers come in flat, and the shop wants each plant saved in the shape this lesson chose: the care details embedded.

**Your job:** write `plantDocument(form)`, which returns one plant document.

- `form`: the form's answers, an object with `name`, `price`, `petSafe`, `light`, `water`, `tip1`, `tip2` and `tip3`.
- Return an object with `name`, `price` and `petSafe` as the form gives them, and a `care` object holding `light`, `water` and `tips`.
- `tips` is a list of the tip boxes that were filled in, in the order `tip1`, `tip2`, `tip3`. A box left empty is `""`, and it is left out of the list.
- When every tip box is empty, `tips` is an empty list, `[]`.

Worked through: for the Calathea, the form is `{ name: "Calathea", price: 32, petSafe: true, light: "medium, indirect", water: "once a week", tip1: "Use filtered water.", tip2: "", tip3: "Turn it a quarter turn each week." }`. `tip2` is empty, so it's left out, and `plantDocument` returns `{ name: "Calathea", price: 32, petSafe: true, care: { light: "medium, indirect", water: "once a week", tips: ["Use filtered water.", "Turn it a quarter turn each week."] } }`.

Practiced live on the lesson page: write the JavaScript right there and check it.

## Check yourself

2 questions to try on the lesson page.

## So what

Every collection you design starts with one question, "is it read together?", and answering it well is what keeps your API's pages to one quick read each.

## Key terms

- [Embedded Document](https://www.ask-codey.com/glossary/embedded-document)
- [Embedding vs Referencing](https://www.ask-codey.com/glossary/embedding-vs-referencing)
- [Data Modeling in MongoDB](https://www.ask-codey.com/glossary/data-modeling-in-mongodb)

## Related

- [Documents and Collections](https://www.ask-codey.com/lessons/node-mongodb-documents-and-collections)
- [Connecting from Node and Saving Documents](https://www.ask-codey.com/lessons/node-mongodb-connect-and-insert)

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