Understanding Documents

Introduction

A document is the basic unit of data in MongoDB. It's a record stored as BSON (Binary JSON) — like a JSON object but with extra types: ObjectId, Date, Decimal128, binary blobs, and more.

If you've ever written a JavaScript object literal, you already understand 90% of MongoDB documents.

Understanding the topic

Document anatomy:

• Every document has an _id primary key (auto-generated ObjectId if you don't supply one).
• Fields can be primitives, arrays, or nested sub-documents — arbitrarily deep.
• Max document size: 16 MB — large enough for almost anything, small enough to force good modeling.
• Field names are case-sensitive; don't reuse _id as a normal field.
• Order of fields is preserved (unlike JSON in some languages).

Informative example

A realistic e-commerce product document:

{
  _id: ObjectId("66f8a..."),
  sku: "BK-1099",
  title: "The Pragmatic Programmer",
  price: NumberDecimal("39.95"),
  tags: ["software", "career", "classic"],
  inventory: { warehouse: "EU-1", quantity: 142 },
  variants: [
    { color: "blue",  stock: 60 },
    { color: "black", stock: 82 }
  ],
  createdAt: ISODate("2026-06-01T09:00:00Z")
}

Real-world use

An e-commerce product, a chat message, a user profile, a webhook payload — they all map naturally to a single document. The data shape in MongoDB is the data shape in your API.

Best practices

• Use ObjectId for surrogate keys; use natural keys (email, slug) with a unique index when meaningful.
• Avoid documents above ~1 MB — split into related collections instead.
• Use NumberDecimal for money, never Double (floating-point errors).

Common mistakes

• Storing huge arrays inside a single document — kills query performance.