Cloud Parts

Document databases

Records stored as JSON documents that the database can query, index and update field by field.

3 technologies on this page ↓
Live model
What you’re watchingThe collection is sharded by user ID. Lookups that include it (colored by key) go to the one shard that holds that user. A search on another field, such as city, can’t know where matches live, so the router sends it to every shard and merges the answers.

How it works

A document database stores each record as a self-contained document, usually JSON or a binary form of it such as MongoDB’s BSON, grouped into collections. Like a key-value store it can fetch a document by its ID, but it also understands what’s inside. You can filter on any field, including nested objects and arrays, index those fields, change one field without rewriting the rest, and run aggregations. Documents in one collection don’t need the same fields, so the shape can change without a migration, and most databases can still validate documents against a schema if you want one. Data that’s read together, such as an order and its line items, usually lives in one document, so reading it is one lookup, but data shared between documents gets copied or linked by ID, and joins across collections are limited. To scale out, a collection is split across shards by a shard key: a query that includes the key goes to one shard, and one that doesn’t goes to all of them.

Think of it as

A filing cabinet of complete forms, one folder per customer. The clerk can pull every folder where the city is Oslo, and new forms can gain boxes without reprinting the old ones.

Reach for it when

  • Records with nested, varying fields: product catalogs, user profiles, content
  • Data that’s read and written as one object, like an order with its line items
  • Apps whose data shape changes often, especially when the code already works in JSON

Think twice when

  • Data with many relationships, queried from every side; joins across collections are limited
  • Work that needs transactions across many records all the time; they exist, but cost more than single-document writes

A real example

An online shop keeps each product as one MongoDB document: name, price, a specs object whose fields differ between laptops and shoes, and an array of sizes with stock counts. An index on specs.brand serves the brand filter, and a price change is one $set on one field. A monthly report joining products with orders and returns, though, is easier in SQL.

Technologies

Specific products, and what each does differently.

What each provider calls it

AWS
Amazon DocumentDB (MongoDB-compatible); DynamoDB also stores JSON documents
Google Cloud
Firestore
Azure
Azure Cosmos DB, with its own NoSQL API or a MongoDB-compatible one
Open source & others
MongoDB (SSPL, source-available), Apache CouchDB, FerretDB (MongoDB-compatible, on PostgreSQL), ArangoDB (BSL, also a graph database); PostgreSQL’s `jsonb` for documents inside a relational database

See it in a real stack

Architectures that use document databases

Serverless web app on AWSCloudFront serves the site from S3 and sends API calls through API Gateway to Lambda functions backed by DynamoDB.Amazon CloudFrontAmazon S3Amazon API GatewayAWS LambdaAmazon DynamoDB

In code · python

from pymongo import MongoClient
products = MongoClient()["shop"]["products"]

products.insert_one({
    "_id": "sku-17", "name": "Trail runner", "price": 89,
    "specs": {"brand": "Ostra", "drop_mm": 6},
    "sizes": [{"eu": 42, "stock": 3}, {"eu": 43, "stock": 0}],
})

products.create_index("specs.brand")                    # index a nested field
cheap = products.find({"specs.brand": "Ostra", "price": {"$lt": 100}})
products.update_one({"_id": "sku-17"}, {"$set": {"price": 79}})   # change one field

Worth exploring

WebsiteDB-EnginesDB-Engines, provided by Redgate SoftwareA directory of hundreds of database systems with their data models, licences and features, which you can compare side by side. Its monthly ranking measures popularity (search results, Google Trends, Stack Overflow questions, job ads, LinkedIn profiles, posts on X), not quality or speed.
All resources →

Often confused with

Key-value storesWide-column storesRelational databasesSearch indexesEmergent schema (JSON columns)Key-value, document or wide-column?EAV, JSON column, wide table or document?
Where it came from2005–2019

By the mid-2000s, web applications passed data around as JSON, which Douglas Crockford described in RFC 4627 in 2006, while relational databases made developers split every object into rows across tables and join them back together. In April 2005 Damien Katz, who had worked on Lotus Notes at IBM, started CouchDB: a database of JSON documents with a schema-free design, read and written over HTTP. It became a top-level Apache project in November 2008.

MongoDB, built at 10gen, had its first official release in February 2009. It kept the JSON-like documents but added what developers expected from a database, such as queries on any field, secondary indexes and in-place updates. Later releases filled in what the early versions left out, including the WiredTiger storage engine, acquired in 2014, and multi-document ACID transactions in 2018.

The model then spread beyond MongoDB itself. In October 2018 MongoDB moved to the SSPL, aimed at companies offering it as a service, and in January 2019 AWS launched DocumentDB, its own MongoDB-compatible service. Relational databases met documents halfway: PostgreSQL 9.4 added the indexable jsonb type in 2014. Today the same JSON record can live in a document database, a relational one or DynamoDB.

Why it’s built this way

Store objects whole, as JSON
Applications already worked with nested objects. Keeping an object and its parts in one document removed the mapping to tables and made reading it a single lookup.
No fixed schema per collection
Each document can have its own fields, so a new field ships with the code instead of waiting for a migration. Optional schema validation lets teams add the guarantees back where they want them.
Shard by a key the developer chooses
Splitting a collection across servers by a shard key lets the cluster grow, and queries that name the key stay on one shard. Choosing that key well is the big design decision.

Timeline

  1. 2005

    Damien Katz starts CouchDB

  2. 2006

    RFC 4627 describes JSON

  3. 2008

    CouchDB becomes a top-level Apache project

  4. 2009

    MongoDB’s first official release, 0.8

  5. 2014

    PostgreSQL 9.4 adds the jsonb type

  6. 2018

    MongoDB 4.0 adds multi-document transactions; licence moves to SSPL

  7. 2019

    AWS launches DocumentDB, compatible with MongoDB

Sources19

Improve this page on GitHub