Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 70 ยท Documents and BSON

Capped Collections and Managing Databases and Collections

Create, list, rename and drop MongoDB collections, read dbStats and collStats, and learn when to use a capped collection or a TTL index for logs and other rolling data.

Until now collections have appeared by magic: the first insertOne created them. That is convenient, but real projects also need to create collections on purpose with options, list and rename them, check how big they are, and drop the ones they no longer need. This lesson covers those housekeeping commands and one special kind of collection, the capped collection, which behaves like a fixed-size ring buffer and is a natural fit for logs and recent-activity feeds.

The snippets in plain code blocks are real mongosh commands and cannot run in this page. The TryIts are stand-ins written in plain JavaScript that reproduce the behavior of capped collections and TTL expiry with a fake clock; they are not a MongoDB server.

Databases and collections appear lazily

In mongosh, use shop switches to a database called shop even if it does not exist yet. MongoDB creates the database and a collection only when you first store data in it:

JavaScript
use shop
db.products.insertOne({ name: "Lamp" })   // creates database "shop" and collection "products"
show dbs                                   // lists databases that contain data
show collections                           // lists collections of the current database

Naming rules are short: collection names cannot be empty, cannot contain the null character or start with system., and should not contain $. Keep names lowercase, plural and descriptive (orders, page_views). Database names are case-sensitive, so Shop and shop are different databases, which is a classic source of "my data disappeared" confusion.

createCollection and its options

You create a collection explicitly when you need options that implicit creation cannot give you:

JavaScript
db.createCollection("events", {
  capped: true,           // fixed size, ring-buffer behavior
  size: 10 * 1024 * 1024, // maximum size in bytes (required for capped)
  max: 50000              // optional: maximum number of documents
})

db.createCollection("users", {
  validator: { $jsonSchema: { bsonType: "object", required: ["email"] } },
  validationLevel: "strict",
  validationAction: "error"
})

db.createCollection("readings", {
  timeseries: { timeField: "ts", metaField: "sensor", granularity: "minutes" }
})

The common options are:

Option Purpose
capped, size, max A fixed-size collection (below).
validator, validationLevel, validationAction Schema rules checked on writes; see Schema Validation.
timeseries A collection optimized for measurements over time.
expireAfterSeconds Expiry for documents in a time series collection.
collation Default string comparison rules (language, case sensitivity).
clusteredIndex Store documents ordered by a key instead of a separate _id index.

createCollection fails if the collection already exists with different options. Calling it from startup code is common; wrap it in a check of listCollections first.

Listing, renaming, dropping

JavaScript
db.getCollectionNames()                       // ["events", "products", "users"]
db.getCollectionInfos({ name: "events" })     // options, including capped and the validator
db.runCommand({ listCollections: 1, filter: { type: "collection" } })

db.products.renameCollection("catalog")             // rename within the database
db.products.renameCollection("catalog", true)       // true = dropTarget: replace an existing "catalog"

db.events.drop()          // removes the collection, its documents AND its indexes; returns true or false
db.dropDatabase()         // removes the CURRENT database with everything in it

Renaming is quick (a metadata change) in the same database, and it keeps the indexes. It is a handy way to swap a rebuilt collection into place: load the new data into catalog_new, then renameCollection("catalog", true). Moving a collection to another database with renameCollection works only through the admin command with full db.collection names, and is not allowed on sharded collections.

drop() and dropDatabase() are immediate and permanent. There is no recycle bin and no confirmation prompt. Check db (the current database name) before dropping, take a backup first, and limit who has the dropCollection and dropDatabase privileges with roles.

Copying a collection

Old shells had db.collection.copyTo(target), which copied every document into another collection using server-side JavaScript. It was removed in MongoDB 4.2, together with the eval machinery it relied on, so modern code copies with aggregation instead:

JavaScript
db.products.aggregate([ { $match: {} }, { $out: "products_copy" } ])
// or merge into an existing collection without replacing it:
db.products.aggregate([ { $merge: { into: "products_copy", whenMatched: "replace", whenNotMatched: "insert" } } ])

$out replaces the target atomically and does not copy indexes, so recreate them on the new collection. For one-off moves between deployments use mongodump and mongorestore (Backup and Restore) or mongoexport and mongoimport. The method db.runCommand({ cloneCollectionAsCapped: "events", toCollection: "events_capped", size: 1048576 }) copies a collection into a new capped one, and db.runCommand({ convertToCapped: "events", size: 1048576 }) converts it in place: afterwards documents beyond the size limit are evicted, so only run it when that is what you want.

How big is it? dbStats and collStats

Two helpers answer capacity questions:

JavaScript
db.stats()                 // for the current database
db.events.stats()          // for one collection (same data as the $collStats stage)
db.events.dataSize()       // bytes of uncompressed data
db.events.storageSize()    // bytes allocated on disk (compressed)
db.events.totalIndexSize() // bytes used by all indexes
db.events.countDocuments({})   // exact number of documents

Useful fields: count (number of documents), size (data size), avgObjSize (average document size), storageSize (disk space after compression), nindexes and totalIndexSize. When dataSize is much larger than storageSize the data compresses well; when storageSize is far larger than dataSize after many deletes, the collection has free space that the engine can reuse. Watching these numbers over time tells you when to shard, add RAM or archive data. See Storage Engine Internals for what the numbers mean on disk.

Capped collections

A capped collection has a fixed maximum size. Documents are stored in the order they were inserted, and when the collection is full the oldest documents are overwritten to make room for new ones, with no cleanup job and no index scans. That gives three properties:

  • Insertion order is guaranteed, so find() without a sort returns documents oldest to newest, and sort({ $natural: -1 }) returns the newest first.
  • Constant size. The collection never grows beyond size bytes (and max documents, if set), so disk use is predictable.
  • Fast writes, because inserts append and old data is dropped in bulk.
JavaScript
db.createCollection("recent_logs", { capped: true, size: 4096, max: 100 })
db.recent_logs.insertOne({ level: "info", msg: "server started" })
db.recent_logs.find().sort({ $natural: -1 }).limit(10)   // the ten newest entries
db.recent_logs.isCapped()                                // true

There are limits. You must choose size up front (MongoDB rounds it up to a multiple of 256 bytes and reserves at least a minimum). An update may not make a document larger than it was, because documents are not moved. You cannot shard a capped collection. You should not rely on deleting individual documents: the collection removes data itself, oldest first, and the right tool for removal by age is the TTL index (compared below). An existing ordinary collection can be turned into a capped one with the convertToCapped command, which rewrites it and cannot be undone. MongoDB itself uses a capped collection for the replica-set oplog (see Replication).

The first TryIt models a capped collection with room for five documents, and prints what remains after each insert.

JS A capped collection overwrites the oldest

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Inserts 6 and 7 overwrote documents 1 and 2. The collection never holds more than five documents, and the natural order is always oldest to newest.

Capped or TTL?

Both features keep a collection from growing without bound, but they answer different questions:

  • A capped collection limits size (or count). It keeps the most recent N items whatever their age, never needs an index, and preserves insertion order. Use it for a rolling window, such as "the last 1,000 log lines" or a small queue.
  • A TTL index limits age. A background task deletes documents older than a time you set, no matter how many there are. Use it for sessions, tokens, cache entries or "keep 30 days of events".
JavaScript
db.sessions.createIndex({ createdAt: 1 }, { expireAfterSeconds: 3600 })   // delete 1 hour after createdAt

TTL is approximate: the cleanup task runs about once a minute, so documents can live a little past their deadline. TTL collections can grow arbitrarily large if the write rate rises, while a capped collection cannot. When you need both limits, create a capped collection (size limit) and accept that old data is dropped by the size rule, or use a TTL index and watch the size. The second TryIt compares the two with a fake clock.

JS Capped (by size) versus TTL (by age)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

During the burst the TTL collection kept all six events (they were young), while the capped collection kept only the last four. After the quiet minute the capped collection still held its last four events, but the TTL collection was empty, because everything had aged out. Pick the rule that matches the question you ask of the data.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What happens when a capped collection is full and you insert another document?

    A capped collection is a fixed-size ring buffer: the oldest documents are removed automatically so new ones fit.
  2. 2. Which options must you set to create a capped collection?

    size (in bytes) is required for capped collections. max, the document limit, is optional.
  3. 3. You need to delete login tokens 15 minutes after they are created. Which tool fits best?

    TTL indexes remove documents by age. A capped collection limits size, not age.
  4. 4. What does db.orders.renameCollection('orders_2024', true) do?

    The second argument is dropTarget. With true, an existing target collection is dropped first.
  5. 5. Why is drop() dangerous?

    There is no undo. Take a backup first and restrict the drop privileges.

Summary

  • Databases and collections are created lazily on first write; use createCollection when you need options such as capped, validator, timeseries or a collation.
  • getCollectionNames, renameCollection(name, dropTarget), drop() and dropDatabase() manage collections; drops are immediate and permanent.
  • db.stats() and db.collection.stats() report document counts and data, storage and index sizes.
  • A capped collection is a fixed-size, insertion-ordered ring buffer: great for recent logs, but updates cannot grow a document and it cannot be sharded.
  • Use a TTL index to expire by age and a capped collection to limit size or count.

Next, see how MongoDB stores identifiers in _id and ObjectId, or jump ahead to Geospatial Data and Queries.