The Document Model & BSON

The Document Model & BSON

The Document Model is the foundation of MongoDB. It allows data to be stored in flexible, JSON-like structures, bridging the gap between application code (objects) and the database (records).

---

🏗️ 1. Document vs. Relational

The core difference between Document and Relational databases lies in how they represent complex data structures.

Feature	Relational (RDBMS)	Document (MongoDB)
Data Structure	Normalized tables (Rows/Columns)	Rich Documents (JSON/BSON)
Schema	Rigid (Defined beforehand)	Flexible (Polymorphic documents)
Scaling	Vertical (Larger servers)	Horizontal (More servers)
Relationships	Joins (Foreign Keys)	Embedding or Referencing

The “Object-Relational Impedance Mismatch”

In an RDBMS, a single “User” object might be split across Users, Addresses, and PhoneNumbers tables. In MongoDB, that same data can often be stored in a single document.

// One document, multiple relationships represented naturally
{
  "_id": ObjectId("..."),
  "name": "Alice",
  "addresses": [
    {"type": "home", "city": "NYC"},
    {"type": "work", "city": "SF"}
  ],
  "contacts": {
    "email": "alice@example.com",
    "phone": "555-0199"
  }
}

---

🚀 2. BSON: Binary JSON

While MongoDB users work with JSON, the database stores and transfers data in BSON (Binary JSON).

Why BSON?

BSON was designed to be efficient, traversable, and supportive of more data types.

Feature	JSON	BSON
Format	Text-based	Binary-encoded
Speed	Slow to parse	Extremely fast to traverse
Data Types	Number, String, Boolean, Array, Object, Null	JSON types + Date, ObjectId, Binary, Int32, Int64, Decimal128

Tip

BSON documents include “size” prefixes for strings and arrays, allowing the MongoDB engine to skip unneeded fields during a query without parsing the entire document.

---

🧪 3. Working with BSON Types in Python

In Python, the bson library (shipped with pymongo) provides classes for MongoDB-specific types.

from pymongo import MongoClient
from datetime import datetime
from bson import ObjectId, Decimal128

client = MongoClient("mongodb://localhost:27017")
db = client.test_db
collection = db.inventory

# Using specific BSON types
item = {
    "product_name": "Premium Gadget",
    "price": Decimal128("199.99"), # Precision decimal
    "created_at": datetime.utcnow(), # BSON Date
    "tags": ["tech", "new"],
    "metadata": {
        "legacy_id": 1234567890123 # Automatic BSON Int64
    }
}

result = collection.insert_one(item)
print(f"Inserted Document ID: {result.inserted_id}") # result.inserted_id is a BSON ObjectId

Danger

The 16MB Limit: A single BSON document cannot exceed 16 megabytes. This limit ensures that query performance remains predictable and that MongoDB doesn’t consume excessive memory per document.

Summary

The Document Model aligns with modern application development by allowing you to store data in the same structure that you use in your code. BSON provides the performance and type-safety needed for a production-grade database.