SysPad › Lessons › database lessons › DocumentDB

How DocumentDB works

MongoDB-compatible managed document database. A cluster of instances shares a distributed storage volume - the primary takes writes, replicas serve reads. Scale reads by adding replicas, throughput by sizing instances.

DocumentDB asks a simple question: what if the shape of your data in the database matched the shape of the object in your code? It stores JSON documents whole, so the order you load is the order you saved, no joins to reassemble it, and it speaks the MongoDB API so your existing tools mostly just work.

What you will learn

Why does storing a whole document beat spreading it across joined tables, sometimes?
"MongoDB-compatible" is doing a lot of work in that sentence. What’s the catch?
How does DocumentDB borrow Aurora’s storage trick for durability and replicas?
When is a document database the wrong tool entirely?

Documents, not rows and joins

DocumentDB stores data as documents: flexible JSON-like objects (BSON) grouped into collections (the rough equivalent of tables). A document can nest arrays and sub-objects, so one record holds everything about an entity.

No fixed schema means each document can differ, which is great for evolving or semi-structured data like catalogs, profiles, and content.

"MongoDB-compatible" (read the small print)

DocumentDB implements the MongoDB API, so drivers, the query language, and many tools connect unchanged. AWS runs and scales it for you; you don’t manage Mongo servers.

So it’s not actually MongoDB under the hood?

Correct. DocumentDB is an AWS-built engine that speaks the MongoDB wire protocol and API, layered on the same distributed storage Aurora uses. It is not the MongoDB codebase, which is exactly why compatibility is "most things," not "everything."

Aurora’s storage trick, reused

Under the hood, DocumentDB separates compute from a shared distributed storage layer, the same architecture as Aurora. Your data is kept as six copies across three Availability Zones, and storage auto-scales as you write.

You get one primary (writer) plus up to 15 replicas that read the shared volume with low lag, so reads scale out while writes funnel through the single primary.

⚓ Common for content management, user profiles, catalogs, and mobile/app backends.

When a document store is the wrong tool

Documents shine when you read and write whole objects by key. They’re a poor fit when you need heavy multi-entity joins, complex transactions across many records, or rich relationship traversal.

Flashcards

You load an "order" with its line items and shipping address in DocumentDB. How many joins?: Zero. It’s stored as one nested document, so the whole object comes back in a single read.
A teammate says "DocumentDB is just MongoDB, everything will work." True?: Mostly, not entirely. It’s MongoDB-API-compatible up to a specific version and omits some features/operators. Test real queries before trusting a migration.
How many copies of your DocumentDB data exist, and where?: Six copies across three AZs on Aurora-style shared storage. Up to 15 replicas read that same volume with low lag.
Adding replicas to DocumentDB, does write throughput go up?: No. There’s a single writer (primary). Replicas scale reads; writes still go through the one primary.
Your data is all about connections between users (followers, mutual friends).: A document store isn’t ideal for relationship traversal. A graph database (Neptune) fits that far better.

Sources

Open the SysPad canvas · Official DocumentDB documentation