MongoDB Cheat Sheet

A throwaway server in Docker, with a root user and a volume for the data

docker run -d --name mongo -p 127.0.0.1:27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=root \
  -e MONGO_INITDB_ROOT_PASSWORD="$(openssl rand -base64 24)" \
  -v mongo-data:/data/db \
  mongo:8.0

docker exec -it mongo mongosh -u root -p            # prompts for the password
docker logs -f mongo

A single node replica set, so transactions and change streams work locally

docker run -d --name mongo-rs -p 127.0.0.1:27017:27017 mongo:8.0 --replSet rs0 --bind_ip_all
docker exec -it mongo-rs mongosh --eval "rs.initiate()"
mongosh "mongodb://localhost:27017/?replicaSet=rs0&directConnection=true"

Ubuntu 24.04 from the official repository (the distribution package is old or missing)

curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
  sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" | \
  sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
sudo apt-get update && sudo apt-get install -y mongodb-org
sudo systemctl enable --now mongod
systemctl status mongod

Homebrew, from MongoDB's own tap

brew tap mongodb/brew
brew install mongodb-community            # or mongodb-community@8.0 to pin a version
brew services start mongodb-community
brew install mongosh mongodb-database-tools

A local Atlas deployment with Search and Vector Search, or a free cloud cluster

brew install mongodb-atlas-cli
atlas deployments setup local1 --type local      # runs in Docker or Podman, includes mongot
atlas deployments connect local1 --connectWith mongosh

atlas setup                                       # sign in and create a free M0 cluster
atlas clusters connectionStrings describe Cluster0

Connection strings: local, replica set, Atlas

mongosh                                                        # mongodb://127.0.0.1:27017
mongosh "mongodb://localhost:27017/shop"
mongosh "mongodb://db1:27017,db2:27017,db3:27017/shop?replicaSet=rs0&tls=true" -u app
mongosh "mongodb+srv://cluster0.example.net/shop" --username app   # prompts for the password
mongosh "$MONGODB_URI" --quiet --eval "db.runCommand({ ping: 1 })"

Where am I

db                                  // current database
db.getMongo()                       // connection
db.version()                        // server version
db.hello()                          // role in the replica set, limits
db.runCommand({ connectionStatus: 1 }).authInfo

Common startup options

mongosh "$MONGODB_URI" --file seed.js          # run a script and exit
mongosh "$MONGODB_URI" --nodb                   # a JavaScript REPL without a connection
mongosh "$MONGODB_URI" --apiVersion 1 --apiStrict
mongosh "$MONGODB_URI" --tls --tlsCAFile ca.pem --tlsCertificateKeyFile client.pem
mongosh "$MONGODB_URI" --authenticationMechanism MONGODB-X509

Databases and collections

show dbs                     // databases that hold data
use shop                     // switch; created on the first write
show collections
db.getCollectionNames()
db.orders.find().limit(3)
db.getCollection('order-items').find()      // names with dashes or dots

Help at every level

help
db.help()
db.orders.help()
db.orders.find().help()
db.orders.find            // print the method without calling it

Leave the shell

exit
quit()
// or Ctrl+D; Ctrl+C twice while nothing is running

Iterate a cursor

db.orders.find({ status: 'paid' })   // prints the first 20 documents
it                                   // the next batch
config.set('displayBatchSize', 50)
db.orders.find().toArray()           // everything, into memory
db.orders.find().forEach(d => print(d._id))

Printing and JSON

printjson(db.orders.findOne())
print(EJSON.stringify(db.orders.findOne(), null, 2))   // Extended JSON, keeps types
db.orders.findOne({}, { _id: 0, total: 1 })
JSON.stringify({ at: new Date() })                      // plain JSON loses the type

Run scripts and one liners

mongosh "$MONGODB_URI" --quiet --eval 'db.orders.countDocuments({ status: "new" })'
mongosh "$MONGODB_URI" --quiet --json=relaxed --eval 'db.orders.findOne()' > one.json
load('scripts/seed.js')              // inside mongosh

Settings and the startup file

config                                    // every setting
config.set('editor', 'code --wait')
edit myPipeline                           // edit a variable in that editor
config.set('inspectDepth', 10)
config.set('historyLength', 5000)
// ~/.mongoshrc.js runs at every start:
prompt = () => `${db.getName()}> `

Tab completion, history, snippets

db.ord<Tab>                  // completes collection names and methods
// Ctrl+R searches the history in ~/.mongodb/mongosh/
snippet search               // community snippets package manager
snippet install analyze-schema

Connect to a second server from the same shell

const other = connect('mongodb://reports.internal:27017/archive')
other.orders.countDocuments()
const m = new Mongo('mongodb://db2.internal:27017')
m.getDB('shop').orders.findOne()
db.getSiblingDB('admin').runCommand({ listDatabases: 1, nameOnly: true })

Time a query from the shell

const t0 = Date.now()
db.orders.find({ status: 'paid' }).toArray().length
print(`${Date.now() - t0} ms`)

Create, inspect and drop

use shop
db.orders.insertOne({ status: 'new' })     // the database now exists
db.stats()
db.getSiblingDB('reports').getCollectionNames()
db.dropDatabase()                          // the current database, no undo

Database name rules

// max 64 bytes; no / \ . " $ * < > : | ? space or null character
// case matters but two databases cannot differ only by case (Shop vs shop)
// admin, local and config are reserved

Create explicitly with options, or implicitly on the first insert

db.createCollection('orders')
db.createCollection('events', { validator: { $jsonSchema: { required: ['type', 'at'] } } })
db.orders.renameCollection('orders_2025')
db.orders_tmp.drop()
db.getCollectionInfos({ name: 'orders' })

Size of a collection and its indexes

db.orders.aggregate([{ $collStats: { storageStats: { scale: 1024 * 1024 } } }])
  .next().storageStats
db.orders.totalIndexSize()
db.orders.estimatedDocumentCount()

Modify options later with collMod

db.runCommand({ collMod: 'orders', validationLevel: 'moderate' })
db.runCommand({ collMod: 'sessions', index: { keyPattern: { last_seen: 1 }, expireAfterSeconds: 3600 } })
db.runCommand({ collMod: 'orders', changeStreamPreAndPostImages: { enabled: true } })

A read only view defined by a pipeline

db.createView('paid_orders', 'orders', [
  { $match: { status: 'paid' } },
  { $project: { customer_id: 1, total: 1, created_at: 1 } }
])
db.paid_orders.find({ total: { $gt: 100 } })

Capped collection: fixed size, insertion order, oldest out first

db.createCollection('log', { capped: true, size: 64 * 1024 * 1024, max: 100000 })
db.log.find().sort({ $natural: -1 }).limit(10)     // newest first
db.log.isCapped()

Clustered collection: documents stored in _id order

db.createCollection('events', {
  clusteredIndex: { key: { _id: 1 }, unique: true },
  expireAfterSeconds: 60 * 60 * 24 * 30
})

Names and types of every collection and view

db.getCollectionInfos().map(c => ({ name: c.name, type: c.type, capped: !!c.options.capped }))

ObjectId: 12 bytes, sortable by creation time

const id = ObjectId()
id.getTimestamp()
ObjectId('66f9a1c2e4b0d7a1c3f2e9b4').toHexString()
db.orders.find({ _id: { $gt: ObjectId.createFromTime(Math.floor(Date.now() / 1000) - 3600) } })   // last hour

Dates are UTC milliseconds; Date() without new is a string

new Date()                             // Date, stored as a BSON date
ISODate('2026-09-29T10:00:00Z')        // same type, mongosh helper
Date()                                 // a string: do not store this
db.orders.find({ created_at: { $gte: ISODate('2026-09-01'), $lt: ISODate('2026-10-01') } })

Int32, Long, Double, Decimal128

db.t.insertOne({
  qty: 3,                            // mongosh sends whole numbers as int32
  views: Long('9007199254740993'),   // 64 bit integer, beyond JavaScript precision
  ratio: 0.25,                       // double
  price: Decimal128('19.99')         // exact decimal for money
})
db.t.find({ qty: { $type: 'int' } })

Money: Decimal128, or integer cents

0.1 + 0.2                                    // 0.30000000000000004
db.products.updateOne({ sku: 'OAK-1' }, { $inc: { price: Decimal128('0.10') } })
db.products.insertOne({ sku: 'OAK-2', price_cents: 1999 })

UUID, binary data, booleans, null and missing fields

UUID()                                         // random v4, binary subtype 4
UUID('4f6c8d0e-2b1a-4c3d-9e8f-7a6b5c4d3e2f')
BinData(0, 'aGVsbG8=')
db.users.find({ deleted_at: null })            // null or missing
db.users.find({ deleted_at: { $exists: false } })   // missing only
db.users.find({ deleted_at: { $type: 'null' } })    // explicitly null only

$type names and numbers

Sort and comparison order across types

// MinKey < null < numbers < strings < objects < arrays < binData
//   < ObjectId < booleans < dates < timestamps < regex < MaxKey
db.t.find().sort({ v: 1 })      // mixed types come out in this order

Limits worth knowing

// document: 16 MiB, nesting depth: 100 levels
// field names may contain . and $ since 5.0, but most operators need $getField for them
Object.bsonsize(db.orders.findOne())       // bytes of one document

Convert string prices to Decimal128 and string dates to dates

db.products.updateMany({ price: { $type: 'string' } }, [{ $set: { price: { $toDecimal: '$price' } } }])
db.orders.updateMany({ created_at: { $type: 'string' } }, [{ $set: { created_at: { $toDate: '$created_at' } } }])

Embed what is read together and bounded in size

{
  _id: ObjectId('66f9a1c2e4b0d7a1c3f2e9b4'),
  customer_id: ObjectId('66f99f10e4b0d7a1c3f2d001'),
  status: 'paid',
  shipping: { city: 'Cluj-Napoca', country: 'RO' },   // one to one: embed
  items: [                                              // one to few: embed
    { sku: 'OAK-1', qty: 2, price: Decimal128('19.99') }
  ],
  total: Decimal128('39.98')
}

Reference what grows without limit or is shared

// customers: { _id, name, email }
// orders:    { _id, customer_id, ... }    one to many with an unbounded many
db.orders.find({ customer_id: cid }).sort({ created_at: -1 }).limit(20)
db.orders.createIndex({ customer_id: 1, created_at: -1 })

A rule of thumb

Extended reference: copy the few fields you display

{ _id: 1, customer: { _id: cid, name: 'Ana Pop', country: 'RO' }, total: 129.9 }

Subset: the latest items embedded, the rest elsewhere

{ _id: 'OAK-1', name: 'Oak table', recent_reviews: [ /* last 10 */ ], review_count: 1482 }
db.reviews.find({ product_id: 'OAK-1' }).sort({ at: -1 }).skip(10)

Computed: keep totals up to date on write

db.products.updateOne(
  { _id: 'OAK-1' },
  { $inc: { review_count: 1, rating_sum: 5 } }
)

Bucket: group many small readings into one document per period

db.readings.updateOne(
  { sensor: 's1', day: ISODate('2026-09-29'), n: { $lt: 200 } },
  { $push: { r: { t: new Date(), v: 21.4 } }, $inc: { n: 1 } },
  { upsert: true }
)

Schema versioning and polymorphic documents

{ _id: 1, schema_version: 2, name: { first: 'Ana', last: 'Pop' } }
{ _id: 2, name: 'Radu Ionescu' }                          // version 1, migrated lazily
db.people.find({ schema_version: { $ne: 2 } }).limit(1000)   // batch migration

Anti patterns

// unbounded arrays that grow forever (followers, logs)
// one collection per customer or per day: thousands of collections and indexes
// huge documents read in full to show two fields
// $lookup on every request to rebuild a relational schema
// fields that hold different types in different documents

Insert one document; _id is added when missing

db.customers.insertOne({ name: 'Ana Pop', email: 'ana@example.com', country: 'RO', created_at: new Date() })

Insert many; ordered: false keeps going after an error

db.products.insertMany([
  { sku: 'OAK-1', name: 'Oak table', price: Decimal128('199.00'), tags: ['wood', 'table'] },
  { sku: 'ASH-2', name: 'Ash chair', price: Decimal128('79.50'), tags: ['wood', 'chair'] }
], { ordered: false })

Duplicate key error

db.customers.createIndex({ email: 1 }, { unique: true })
db.customers.insertOne({ email: 'ana@example.com' })

How many members must confirm a write

db.orders.insertOne(doc, { writeConcern: { w: 'majority', wtimeout: 5000 } })
db.orders.insertOne(doc, { writeConcern: { w: 1 } })          // primary only
db.adminCommand({ getDefaultRWConcern: 1 })

Change the cluster default

db.adminCommand({
  setDefaultRWConcern: 1,
  defaultWriteConcern: { w: 'majority' },
  defaultReadConcern: { level: 'majority' }
})

mongoimport from JSON, JSON arrays and CSV

mongoimport --uri "$MONGODB_URI" --collection products --file products.json          # one document per line
mongoimport --uri "$MONGODB_URI" --collection products --jsonArray --file products.json
mongoimport --uri "$MONGODB_URI" --collection products --type csv --headerline --file products.csv
mongoimport --uri "$MONGODB_URI" --collection products --type csv --headerline \
  --mode upsert --upsertFields sku --file products.csv

Typed CSV columns

mongoimport --uri "$MONGODB_URI" -c products --type csv --file products.csv \
  --columnsHaveTypes --fields "sku.string(),price.decimal(),stock.int32(),added.date_go(2006-01-02)"

Your own _id instead of an ObjectId

db.products.insertOne({ _id: 'OAK-1', name: 'Oak table' })          // natural key
db.events.insertOne({ _id: UUID(), type: 'signup', at: new Date() })
db.order_items.insertOne({ _id: { order: 9001, line: 1 }, sku: 'OAK-1', qty: 2 })   // compound key

Generate test data in batches

const batch = []
for (let i = 1; i <= 100000; i++) {
  batch.push({ n: i, status: ['new', 'paid', 'shipped'][i % 3], total: Math.round(Math.random() * 50000) / 100, created_at: new Date(Date.now() - i * 60000) })
  if (batch.length === 1000) { db.orders_test.insertMany(batch, { ordered: false }); batch.length = 0 }
}
if (batch.length) db.orders_test.insertMany(batch)
db.orders_test.countDocuments()

Equality and comparison

db.orders.find({ status: 'paid' })
db.orders.find({ total: { $gte: 100, $lt: 500 } })
db.orders.find({ status: { $in: ['paid', 'shipped'] } })
db.orders.find({ status: { $ne: 'cancelled' } })       // also matches documents without status
db.orders.findOne({ _id: ObjectId('66f9a1c2e4b0d7a1c3f2e9b4') })

AND is implicit; OR needs $or

db.orders.find({ status: 'paid', country: 'RO' })
db.orders.find({ $or: [{ status: 'paid' }, { total: { $gt: 1000 } }] })
db.orders.find({ $and: [{ $or: [{ a: 1 }, { b: 1 }] }, { $or: [{ c: 1 }, { d: 1 }] }] })
db.orders.find({ total: { $not: { $gt: 100 } } })       // also matches missing total

Embedded documents: dotted path versus exact match

db.orders.find({ 'shipping.country': 'RO' })               // field inside
db.orders.find({ shipping: { city: 'Cluj', country: 'RO' } }) // whole document, same field order

Count and distinct

db.orders.countDocuments({ status: 'paid' })
db.orders.estimatedDocumentCount()              // metadata, fast, no filter
db.orders.distinct('status')
db.orders.distinct('shipping.country', { status: 'paid' })

$exists, $type and null

db.users.find({ phone: { $exists: true } })
db.users.find({ phone: { $exists: true, $ne: null } })
db.users.find({ zip: { $type: 'string' } })
db.users.find({ zip: { $type: ['int', 'long'] } })
db.users.find({ phone: null })                  // null or missing

null no longer matches undefined

db.t.find({ v: null })       // 8.0+: matches null and missing, not the deprecated undefined type

Dotted paths compared with null

db.orders.find({ 'items.discount': null })
db.orders.find({ 'items.discount': { $in: [null, 0] } })

Regular expressions

db.users.find({ email: /@example\.com$/ })
db.users.find({ name: /^ana/i })
db.users.find({ name: { $regex: '^ana', $options: 'i' } })
db.users.find({ sku: { $regex: '^OAK-' } })          // anchored and case sensitive: uses an index

$expr: compare two fields of the same document

db.products.find({ $expr: { $lt: ['$stock', '$reorder_level'] } })
db.orders.find({ $expr: { $gt: [{ $size: '$items' }, 10] } })
db.orders.find({ $expr: { $eq: [{ $year: '$created_at' }, 2026] } })

$mod, bitwise, $jsonSchema in a query

db.orders.find({ number: { $mod: [100, 0] } })
db.users.find({ flags: { $bitsAllSet: [0, 2] } })
db.users.find({ $jsonSchema: { required: ['email'], properties: { email: { bsonType: 'string' } } } })

$where: server side JavaScript

db.orders.find({ $where: 'this.total > this.budget' })        // prefer $expr

The operators by group

Include or exclude fields

db.customers.find({}, { name: 1, email: 1 })             // plus _id
db.customers.find({}, { name: 1, email: 1, _id: 0 })
db.customers.find({}, { password_hash: 0, tokens: 0 })   // everything else
db.orders.find({}, { 'shipping.city': 1 })

Arrays and computed fields in a projection

db.posts.find({}, { title: 1, comments: { $slice: -3 } })                 // last 3
db.orders.find({ 'items.sku': 'OAK-1' }, { 'items.$': 1 })                // first matching element
db.orders.find({}, { items: { $elemMatch: { qty: { $gte: 5 } } } })
db.orders.find({}, { total: 1, year: { $year: '$created_at' } })          // aggregation expressions

Chain them in any order; the server applies sort, then skip, then limit

db.orders.find({ status: 'paid' }).sort({ created_at: -1 }).limit(20)
db.orders.find().sort({ total: -1, _id: 1 }).skip(40).limit(20)
db.orders.find().sort({ $natural: -1 }).limit(5)       // storage order, no index

Keyset pagination instead of large skip values

const page = db.orders.find({ status: 'paid' }).sort({ created_at: -1, _id: -1 }).limit(20).toArray()
const last = page[page.length - 1]
db.orders.find({
  status: 'paid',
  $or: [
    { created_at: { $lt: last.created_at } },
    { created_at: last.created_at, _id: { $lt: last._id } }
  ]
}).sort({ created_at: -1, _id: -1 }).limit(20)

Case insensitive sorting and matching with a collation

db.users.createIndex({ name: 1 }, { collation: { locale: 'en', strength: 2 } })
db.users.find({ name: 'ana pop' }).collation({ locale: 'en', strength: 2 })
db.users.find().sort({ name: 1 }).collation({ locale: 'ro' })              // ă, â, î, ș, ț in Romanian order
db.items.find().sort({ code: 1 }).collation({ locale: 'en', numericOrdering: true })   // 2 before 10

Time limits, hints, comments

db.orders.find({ status: 'new' }).maxTimeMS(2000)
db.orders.find({ status: 'new' }).hint({ status: 1, created_at: -1 })
db.orders.find({ status: 'new' }).comment('dashboard: new orders')
db.orders.find().sort({ note: 1 }).allowDiskUse()

A default time limit for every query

db.adminCommand({ setClusterParameter: { defaultMaxTimeMS: { readOperations: 30000 } } })

Read preference and read concern per query

db.orders.find({ status: 'paid' }).readPref('secondaryPreferred')
db.orders.find({ status: 'paid' }).readConcern('majority')

One page of results and the total count in a single aggregation

db.orders.aggregate([
  { $match: { status: 'paid' } },
  { $sort: { created_at: -1, _id: -1 } },
  { $facet: { page: [{ $skip: 0 }, { $limit: 20 }], total: [{ $count: 'n' }] } }
])

updateOne and updateMany

db.customers.updateOne({ email: 'ana@example.com' }, { $set: { country: 'DE', updated_at: new Date() } })
db.orders.updateMany({ status: 'new', created_at: { $lt: ISODate('2026-09-01') } }, { $set: { status: 'expired' } })

The update needs operators, or it is a replacement

db.customers.updateOne({ _id: id }, { $set: { name: 'Ana' } })      // changes one field
db.customers.replaceOne({ _id: id }, { name: 'Ana' })               // the document is now only { _id, name }
db.customers.updateOne({ _id: id }, { name: 'Ana' })                // error: needs atomic operators

Set, remove, increment, rename

db.products.updateOne({ sku: 'OAK-1' }, {
  $set: { 'dims.width': 120, active: true },
  $unset: { legacy_code: '' },
  $inc: { stock: -1, sold: 1 },
  $mul: { price: Decimal128('1.10') },
  $rename: { desc: 'description' },
  $currentDate: { updated_at: true }
})

Keep the lowest or highest value

db.stats.updateOne({ _id: 'day-2026-09-29' }, { $min: { low: 12.4 }, $max: { high: 31.2 } }, { upsert: true })

Update operator reference

Insert when nothing matches

db.daily_visits.updateOne(
  { page: '/pricing', day: '2026-09-29' },
  { $inc: { count: 1 }, $setOnInsert: { first_seen: new Date() } },
  { upsert: true }
)

Read and modify in one atomic step

db.counters.findOneAndUpdate(
  { _id: 'invoice' },
  { $inc: { seq: 1 } },
  { upsert: true, returnDocument: 'after' }
)

Update the first document in a given order

db.jobs.updateOne(
  { state: 'queued' },
  { $set: { state: 'running', worker: 'w1', started_at: new Date() } },
  { sort: { priority: -1, created_at: 1 } }
)

Use other fields of the document in the update

db.orders.updateMany({}, [
  { $set: { total: { $sum: { $map: { input: '$items', in: { $multiply: ['$$this.qty', '$$this.price'] } } } } } },
  { $set: { tier: { $switch: { branches: [{ case: { $gte: ['$total', 1000] }, then: 'gold' }], default: 'standard' } } } },
  { $unset: 'tmp' }
])

Move fields into a sub document

db.users.updateMany({ street: { $exists: true } }, [
  { $set: { address: { street: '$street', city: '$city' } } },
  { $unset: ['street', 'city'] }
])

A value inside an array

db.products.find({ tags: 'wood' })                    // any element equals
db.products.find({ tags: { $all: ['wood', 'table'] } })
db.products.find({ tags: ['wood', 'table'] })         // exactly this array, this order
db.products.find({ tags: { $size: 2 } })
db.products.find({ 'tags.0': 'wood' })                // by position

$elemMatch: all conditions on the same element

db.orders.find({ 'items.sku': 'OAK-1', 'items.qty': { $gte: 5 } })            // may match two different items
db.orders.find({ items: { $elemMatch: { sku: 'OAK-1', qty: { $gte: 5 } } } }) // the same item

$push, $addToSet, $pull, $pop

db.posts.updateOne({ _id: 1 }, { $push: { tags: 'mongodb' } })
db.posts.updateOne({ _id: 1 }, { $addToSet: { tags: { $each: ['nosql', 'db'] } } })   // no duplicates
db.posts.updateOne({ _id: 1 }, { $pull: { tags: 'db' } })
db.posts.updateOne({ _id: 1 }, { $pull: { comments: { spam: true } } })               // by condition
db.posts.updateOne({ _id: 1 }, { $pop: { tags: 1 } })                                 // last; -1 first

Keep only the latest N elements, sorted

db.users.updateOne({ _id: uid }, {
  $push: { recent: { $each: [{ at: new Date(), page: '/pricing' }], $sort: { at: -1 }, $slice: 10 } }
})

Insert at a position

db.lists.updateOne({ _id: 1 }, { $push: { items: { $each: ['first'], $position: 0 } } })

Positional operators

db.orders.updateOne({ _id: oid, 'items.sku': 'OAK-1' }, { $inc: { 'items.$.qty': 1 } })     // first match
db.orders.updateOne({ _id: oid }, { $set: { 'items.$[].shipped': true } })                  // every element
db.orders.updateMany(
  {},
  { $set: { 'items.$[it].price': Decimal128('17.99') } },
  { arrayFilters: [{ 'it.sku': 'OAK-1', 'it.price': { $gt: Decimal128('17.99') } }] }
)

Nested arrays

db.courses.updateOne(
  { _id: 1 },
  { $set: { 'modules.$[m].lessons.$[l].done': true } },
  { arrayFilters: [{ 'm.code': 'M2' }, { 'l.id': 7 }] }
)

A compound multikey index for $elemMatch queries

db.orders.createIndex({ 'items.sku': 1, 'items.qty': 1 })
db.orders.find({ items: { $elemMatch: { sku: 'OAK-1', qty: { $gte: 5 } } } }).explain('executionStats').executionStats.totalKeysExamined

Delete one or many

db.sessions.deleteOne({ _id: sid })
db.sessions.deleteMany({ expires_at: { $lt: new Date() } })
db.jobs.findOneAndDelete({ state: 'done' }, { sort: { finished_at: 1 } })

Empty a collection

db.logs.deleteMany({})     // deletes one by one, keeps indexes, slow on big collections
db.logs.drop()             // instant, drops the indexes too

Delete in batches on a busy server

let n
do {
  const ids = db.events.find({ at: { $lt: ISODate('2025-01-01') } }, { _id: 1 }).limit(5000).toArray().map(d => d._id)
  n = ids.length ? db.events.deleteMany({ _id: { $in: ids } }).deletedCount : 0
  sleep(200)
} while (n > 0)

Mixed writes to one collection in one round trip

db.products.bulkWrite([
  { insertOne: { document: { sku: 'ELM-3', stock: 5 } } },
  { updateOne: { filter: { sku: 'OAK-1' }, update: { $inc: { stock: -1 } } } },
  { updateMany: { filter: { stock: 0 }, update: { $set: { active: false } } } },
  { replaceOne: { filter: { sku: 'ASH-2' }, replacement: { sku: 'ASH-2', stock: 3 }, upsert: true } },
  { deleteOne: { filter: { sku: 'OLD-9' } } }
], { ordered: false })

One bulk write across several collections

db.getMongo().bulkWrite([
  { insertOne: { namespace: 'shop.orders', document: { _id: 9001, total: 40 } } },
  { updateOne: { namespace: 'shop.products', filter: { sku: 'OAK-1' }, update: { $inc: { stock: -1 } } } }
])

Remove duplicates, keeping the newest document per key

const dupes = db.customers.aggregate([
  { $sort: { email: 1, created_at: -1 } },
  { $group: { _id: '$email', keep: { $first: '$_id' }, all: { $push: '$_id' }, n: { $sum: 1 } } },
  { $match: { n: { $gt: 1 } } }
], { allowDiskUse: true }).toArray()
const extra = dupes.flatMap(d => d.all.filter(id => !id.equals(d.keep)))
db.customers.deleteMany({ _id: { $in: extra } })
db.customers.createIndex({ email: 1 }, { unique: true })

Soft delete with a partial index

db.posts.updateOne({ _id: pid }, { $set: { deleted_at: new Date() } })
db.posts.createIndex({ author_id: 1, created_at: -1 }, { partialFilterExpression: { deleted_at: null } })
db.posts.find({ author_id: aid, deleted_at: null }).sort({ created_at: -1 })

Copy then delete: archive old documents

db.orders.aggregate([
  { $match: { created_at: { $lt: ISODate('2025-01-01') } } },
  { $merge: { into: 'orders_archive', on: '_id', whenMatched: 'keepExisting', whenNotMatched: 'insert' } }
])
db.orders.deleteMany({ created_at: { $lt: ISODate('2025-01-01') } })

Filter, group, sort

db.orders.aggregate([
  { $match: { status: 'paid', created_at: { $gte: ISODate('2026-01-01') } } },
  { $group: { _id: '$country', orders: { $sum: 1 }, revenue: { $sum: '$total' }, avg: { $avg: '$total' } } },
  { $sort: { revenue: -1 } },
  { $limit: 5 }
])

SQL to aggregation

Group by several fields, then HAVING

db.orders.aggregate([
  { $group: { _id: { country: '$country', status: '$status' }, n: { $sum: 1 } } },
  { $match: { n: { $gt: 100 } } },
  { $project: { _id: 0, country: '$_id.country', status: '$_id.status', n: 1 } }
])

Count, and group everything

db.orders.aggregate([{ $match: { status: 'paid' } }, { $count: 'paid' }])
db.orders.aggregate([{ $group: { _id: null, total: { $sum: '$total' }, max: { $max: '$total' } } }])

The $group accumulators

db.orders.aggregate([{ $group: {
  _id: '$customer_id',
  n: { $sum: 1 },
  spent: { $sum: '$total' },
  first_order: { $min: '$created_at' },
  last_order: { $max: '$created_at' },
  statuses: { $addToSet: '$status' },
  latest3: { $topN: { n: 3, sortBy: { created_at: -1 }, output: '$_id' } },
  p90: { $percentile: { input: '$total', p: [0.9], method: 'approximate' } }
} }])

Memory limits and spilling to disk

db.orders.aggregate(pipeline, { allowDiskUse: true })       // the default since 6.0
db.orders.aggregate(pipeline, { maxTimeMS: 60000, comment: 'nightly report' })

Explain a pipeline

db.orders.explain('executionStats').aggregate(pipeline)
db.orders.aggregate(pipeline, { explain: true })

Revenue per month, in the business time zone

db.orders.aggregate([
  { $match: { status: 'paid' } },
  { $group: {
      _id: { $dateTrunc: { date: '$created_at', unit: 'month', timezone: 'Europe/Bucharest' } },
      revenue: { $sum: '$total' },
      orders: { $sum: 1 }
  } },
  { $sort: { _id: 1 } }
])

$lookup: a left outer join

db.orders.aggregate([
  { $match: { status: 'paid' } },
  { $lookup: { from: 'customers', localField: 'customer_id', foreignField: '_id', as: 'customer' } },
  { $unwind: '$customer' },
  { $project: { total: 1, 'customer.name': 1, 'customer.email': 1 } }
])

$lookup with conditions and a sub pipeline

db.customers.aggregate([
  { $lookup: {
      from: 'orders',
      localField: '_id',
      foreignField: 'customer_id',
      pipeline: [{ $match: { status: 'paid' } }, { $sort: { created_at: -1 } }, { $limit: 3 }],
      as: 'recent_paid'
  } }
])

$unwind: one document per array element

db.orders.aggregate([
  { $unwind: { path: '$items', preserveNullAndEmptyArrays: true, includeArrayIndex: 'pos' } },
  { $group: { _id: '$items.sku', sold: { $sum: '$items.qty' } } },
  { $sort: { sold: -1 } }
])

$graphLookup: follow references recursively

db.employees.aggregate([
  { $match: { name: 'Ana' } },
  { $graphLookup: { from: 'employees', startWith: '$manager_id', connectFromField: 'manager_id', connectToField: '_id', as: 'chain', depthField: 'level' } }
])

$set, $project, $replaceWith, $unset

db.orders.aggregate([
  { $set: { item_count: { $size: '$items' } } },
  { $unset: ['internal_notes', 'items'] },
  { $replaceWith: { $mergeObjects: ['$shipping', { order_id: '$_id', total: '$total' }] } }
])

$facet: several aggregations over the same input

db.products.aggregate([
  { $match: { active: true } },
  { $facet: {
      by_category: [{ $sortByCount: '$category' }],
      price_bands: [{ $bucket: { groupBy: '$price', boundaries: [0, 50, 200, 1000], default: '1000+' } }],
      total: [{ $count: 'n' }]
  } }
])

$unionWith, $sample, $documents

db.orders_2025.aggregate([{ $unionWith: 'orders_2026' }, { $count: 'all' }])
db.users.aggregate([{ $sample: { size: 5 } }])
db.aggregate([{ $documents: [{ x: 1 }, { x: 2 }] }, { $set: { y: { $multiply: ['$x', 10] } } }])

Running totals, moving averages and ranks with $setWindowFields

db.sales.aggregate([
  { $setWindowFields: {
      partitionBy: '$store',
      sortBy: { day: 1 },
      output: {
        running: { $sum: '$amount', window: { documents: ['unbounded', 'current'] } },
        avg7: { $avg: '$amount', window: { range: [-6, 0], unit: 'day' } },
        rank: { $denseRank: {} }
      }
  } }
])

Fill gaps in a time series

db.sales.aggregate([
  { $densify: { field: 'day', partitionByFields: ['store'], range: { step: 1, unit: 'day', bounds: 'partition' } } },
  { $fill: { partitionBy: '$store', sortBy: { day: 1 }, output: { amount: { value: 0 } } } }
])

$merge into a collection, $out to replace one

db.orders.aggregate([
  { $match: { created_at: { $gte: ISODate('2026-09-01') } } },
  { $group: { _id: { $dateTrunc: { date: '$created_at', unit: 'day' } }, revenue: { $sum: '$total' } } },
  { $merge: { into: 'daily_revenue', on: '_id', whenMatched: 'replace', whenNotMatched: 'insert' } }
])
db.orders.aggregate([{ $match: { status: 'paid' } }, { $out: 'paid_snapshot' }])

Stage reference

$cond, $ifNull, $switch

db.orders.aggregate([{ $project: {
  total: 1,
  size: { $cond: [{ $gte: ['$total', 500] }, 'large', 'small'] },
  coupon: { $ifNull: ['$coupon', 'none'] },
  band: { $switch: {
    branches: [
      { case: { $lt: ['$total', 50] }, then: 'low' },
      { case: { $lt: ['$total', 200] }, then: 'mid' }
    ],
    default: 'high'
  } }
} }])

Arithmetic

{ $add: ['$price', '$shipping'] }
{ $subtract: ['$total', '$discount'] }
{ $multiply: ['$qty', '$price'] }
{ $divide: ['$total', '$qty'] }
{ $round: [{ $multiply: ['$total', 1.19] }, 2] }
{ $mod: ['$number', 2] }
{ $abs: '$delta' }

String operators

{ $concat: ['$first', ' ', '$last'] }
{ $toLower: '$email' }
{ $trim: { input: '$name' } }
{ $split: ['$path', '/'] }
{ $substrCP: ['$name', 0, 3] }
{ $strLenCP: '$name' }
{ $regexMatch: { input: '$email', regex: /@example\.com$/ } }
{ $replaceAll: { input: '$phone', find: ' ', replacement: '' } }

Date operators with a time zone

db.orders.aggregate([{ $group: {
  _id: { $dateToString: { format: '%Y-%m-%d', date: '$created_at', timezone: 'Europe/Bucharest' } },
  n: { $sum: 1 }
} }])
{ $dateTrunc: { date: '$created_at', unit: 'week', startOfWeek: 'monday' } }
{ $dateAdd: { startDate: '$created_at', unit: 'day', amount: 30 } }
{ $dateDiff: { startDate: '$created_at', endDate: '$$NOW', unit: 'day' } }
{ $dateFromString: { dateString: '$date_text', format: '%d.%m.%Y' } }
{ $year: { date: '$created_at', timezone: '+03:00' } }

$map, $filter, $reduce

{ $map: { input: '$items', as: 'i', in: { $multiply: ['$$i.qty', '$$i.price'] } } }
{ $filter: { input: '$items', as: 'i', cond: { $gte: ['$$i.qty', 5] }, limit: 3 } }
{ $reduce: { input: '$items', initialValue: 0, in: { $add: ['$$value', '$$this.qty'] } } }
{ $sum: '$items.qty' }                          // simpler when you only need the sum

The position of each element

{ $map: { input: '$steps', arrayIndexAs: 'i', in: { n: { $add: ['$$IDX', 1] }, step: '$$this' } } }

Other array expressions

{ $size: '$items' }
{ $arrayElemAt: ['$items', -1] }            // last
{ $in: ['vip', '$tags'] }
{ $slice: ['$items', 3] }
{ $concatArrays: ['$a', '$b'] }
{ $setUnion: ['$a', '$b'] }
{ $sortArray: { input: '$items', sortBy: { price: -1 } } }
{ $firstN: { input: '$scores', n: 3 } }

Type conversion

{ $toString: '$_id' }
{ $toObjectId: '$customer_ref' }
{ $toDate: '$ts_millis' }
{ $toDecimal: '$price_text' }
{ $convert: { input: '$qty', to: 'int', onError: 0, onNull: 0 } }
{ $toUUID: '$uuid_text' }

Newer conversion helpers

{ $convert: { input: 'ff', to: 'int', base: 16 } }
{ $toArray: '$tags_json' }
{ $hexHash: { input: '$email', algorithm: 'sha256' } }
{ $createObjectId: {} }

System variables and $let

'$$ROOT'           // the whole input document
'$$CURRENT'
'$$NOW'            // same value for the whole operation
'$$REMOVE'         // leave the field out
{ $let: { vars: { net: { $subtract: ['$total', '$tax'] } }, in: { $multiply: ['$$net', 0.1] } } }
{ $project: { email: { $cond: ['$public', '$email', '$$REMOVE'] } } }

Fields with dots or dollar signs in the name

{ $getField: { field: 'price.usd', input: '$$ROOT' } }
{ $setField: { field: '$unit', input: '$$ROOT', value: 'kg' } }

Create, list, drop

db.orders.createIndex({ customer_id: 1, created_at: -1 })
db.orders.createIndex({ email: 1 }, { unique: true, name: 'email_unique' })
db.orders.getIndexes()
db.orders.dropIndex('email_unique')

Compound indexes follow the ESR rule

// query: status = 'paid', sorted by created_at, total > 100
db.orders.createIndex({ status: 1, created_at: -1, total: 1 })
// Equality fields first, then Sort fields, then Range fields

Prefixes: one compound index serves several queries

db.orders.createIndex({ customer_id: 1, status: 1, created_at: -1 })
// used by: { customer_id }, { customer_id, status }, { customer_id, status, created_at }
// not by:  { status } alone, { created_at } alone

Build indexes on a live replica set

db.orders.createIndex({ sku: 1 })                 // does not block reads and writes for its duration
db.currentOp({ 'command.createIndexes': { $exists: true } })
db.orders.createIndexes([{ a: 1 }, { b: 1, c: -1 }])

TTL: delete documents after a time

db.sessions.createIndex({ last_seen: 1 }, { expireAfterSeconds: 3600 })
db.events.createIndex({ expire_at: 1 }, { expireAfterSeconds: 0 })     // at the date in the field

Partial and unique

db.users.createIndex({ email: 1 }, { unique: true, partialFilterExpression: { email: { $type: 'string' } } })
db.orders.createIndex({ created_at: -1 }, { partialFilterExpression: { status: { $in: ['new', 'paid'] } } })

Multikey: an index on an array field

db.products.createIndex({ tags: 1 })          // one entry per element
db.products.find({ tags: 'oak' })

Text, wildcard and hashed

db.articles.createIndex({ title: 'text', body: 'text' }, { weights: { title: 5 }, default_language: 'english' })
db.products.createIndex({ 'attrs.$**': 1 })        // any field under attrs
db.users.createIndex({ user_id: 'hashed' })        // for hashed shard keys

Case insensitive index

db.users.createIndex({ name: 1 }, { collation: { locale: 'en', strength: 2 } })
db.users.find({ name: 'ANA POP' }).collation({ locale: 'en', strength: 2 })

Hide an index before dropping it

db.orders.hideIndex('status_1')        // kept up to date, ignored by the planner
db.orders.unhideIndex('status_1')

Which indexes are used

db.orders.aggregate([{ $indexStats: {} }, { $project: { name: 1, 'accesses.ops': 1, 'accesses.since': 1 } }])

Index sizes

db.orders.stats({ indexDetails: false }).indexSizes
db.orders.totalIndexSize()

executionStats runs the query and reports what it did

db.orders.find({ status: 'paid' }).sort({ created_at: -1 }).explain('executionStats')

The stages you will see

Covered queries

db.users.createIndex({ email: 1, name: 1 })
db.users.find({ email: 'ana@example.com' }, { _id: 0, email: 1, name: 1 }).explain('executionStats').executionStats.totalDocsExamined

Log and profile slow operations

db.setProfilingLevel(1, { slowms: 100 })          // profile operations slower than 100 ms
db.system.profile.find().sort({ ts: -1 }).limit(5).pretty()
db.system.profile.find({ planSummary: 'COLLSCAN' }, { ns: 1, millis: 1, command: 1 })
db.setProfilingLevel(0)

What is running now, and stopping it

db.currentOp({ active: true, secs_running: { $gte: 5 } })
db.killOp(12345)
db.aggregate([{ $currentOp: { allUsers: true } }, { $match: { secs_running: { $gt: 10 } } }])

Query statistics per query shape

db.getSiblingDB('admin').aggregate([
  { $queryStats: {} },
  { $sort: { 'metrics.totalExecMicros.sum': -1 } },
  { $limit: 10 }
])

Pin a plan or reject a query shape with query settings

db.adminCommand({
  setQuerySettings: { find: 'orders', filter: { status: 'paid' }, sort: { created_at: -1 }, $db: 'shop' },
  settings: { indexHints: { ns: { db: 'shop', coll: 'orders' }, allowedIndexes: ['status_1_created_at_-1'] } }
})
db.adminCommand({ setQuerySettings: querySettingsHash, settings: { reject: true } })
db.aggregate([{ $querySettings: {} }])

Query settings for one command only

db.runCommand({
  find: 'orders',
  filter: { status: 'paid' },
  querySettings: { indexHints: { ns: { db: 'shop', coll: 'orders' }, allowedIndexes: [{ status: 1 }] } }
})

The plan cache

db.orders.getPlanCache().list()
db.orders.getPlanCache().clear()

What each verbosity level runs

Create a collection with rules

db.createCollection('customers', {
  validator: { $jsonSchema: {
    bsonType: 'object',
    required: ['email', 'name', 'created_at'],
    properties: {
      email: { bsonType: 'string', pattern: '^[^@\\s]+@[^@\\s]+$' },
      name: { bsonType: 'string', minLength: 1, maxLength: 200 },
      tier: { enum: ['free', 'pro', 'enterprise'] },
      credits: { bsonType: ['int', 'long'], minimum: 0 },
      created_at: { bsonType: 'date' }
    }
  } },
  validationAction: 'error'
})

What a rejected write looks like

db.customers.insertOne({ email: 'not-an-email', name: 'Ana', created_at: new Date() })

Add or change rules on an existing collection

db.runCommand({
  collMod: 'customers',
  validator: { $jsonSchema: { required: ['email'] } },
  validationLevel: 'moderate',
  validationAction: 'warn'
})
db.getCollectionInfos({ name: 'customers' })[0].options.validator

What each setting does

Find documents that break the current rules

db.customers.find({ $nor: [db.getCollectionInfos({ name: 'customers' })[0].options.validator] })

Bypass validation for a one off fix

db.runCommand({ insert: 'customers', documents: [legacyDoc], bypassDocumentValidation: true })

Validators with query operators

db.runCommand({
  collMod: 'orders',
  validator: { $and: [
    { total: { $gte: 0 } },
    { status: { $in: ['new', 'paid', 'shipped', 'refunded', 'cancelled'] } },
    { $expr: { $lte: ['$discount', '$total'] } }
  ] }
})

Check a collection's data files and indexes

db.orders.validate({ full: true })

withTransaction commits, and retries on transient errors

const session = db.getMongo().startSession()
session.withTransaction(() => {
  const s = session.getDatabase('shop')
  s.accounts.updateOne({ _id: 'A' }, { $inc: { balance: -100 } })
  s.accounts.updateOne({ _id: 'B' }, { $inc: { balance: 100 } })
  s.transfers.insertOne({ from: 'A', to: 'B', amount: 100, at: new Date() })
}, { readConcern: { level: 'snapshot' }, writeConcern: { w: 'majority' } })
session.endSession()

The same in Node.js

const session = client.startSession()
try {
  await session.withTransaction(async () => {
    await accounts.updateOne({ _id: 'A' }, { $inc: { balance: -100 } }, { session })
    await accounts.updateOne({ _id: 'B' }, { $inc: { balance: 100 } }, { session })
  })
} finally {
  await session.endSession()
}

Manual control

session.startTransaction({ readConcern: { level: 'snapshot' }, writeConcern: { w: 'majority' } })
try {
  session.getDatabase('shop').orders.insertOne({ total: 50 })
  session.commitTransaction()
} catch (e) {
  session.abortTransaction()
  throw e
}

What to keep in mind

A cap on open transactions

db.adminCommand({ getParameter: 1, maxConcurrentMultiDocumentTransactions: 1 })

Retryable writes are on by default

mongodb+srv://cluster0.example.net/shop?retryWrites=true&w=majority

Causal consistency: read your own writes on secondaries

const s = db.getMongo().startSession({ causalConsistency: true })
const sdb = s.getDatabase('shop')
sdb.orders.insertOne({ _id: 9002, total: 75 })
sdb.orders.find({ _id: 9002 }).readPref('secondary').readConcern('majority')

A transaction in Python

with client.start_session() as session:
    def transfer(s):
        accounts = s.client.shop.accounts
        accounts.update_one({"_id": "A"}, {"$inc": {"balance": -100}}, session=s)
        accounts.update_one({"_id": "B"}, {"$inc": {"balance": 100}}, session=s)
    session.with_transaction(transfer)

Watch a collection

const cs = db.orders.watch(
  [{ $match: { operationType: { $in: ['insert', 'update'] } } }],
  { fullDocument: 'updateLookup' }
)
while (cs.hasNext()) { printjson(cs.next()) }

Watch a database or the whole deployment

db.watch()
db.getMongo().watch([{ $match: { 'ns.coll': 'orders' } }])

Resume after a restart

const token = lastEvent._id                         // store it after handling each event
db.orders.watch([], { resumeAfter: token })
db.orders.watch([], { startAfter: token })          // also works after an invalidate event
db.orders.watch([], { startAtOperationTime: Timestamp({ t: 1790678034, i: 0 }) })

The document before the change

db.runCommand({ collMod: 'orders', changeStreamPreAndPostImages: { enabled: true } })
db.orders.watch([], { fullDocumentBeforeChange: 'whenAvailable', fullDocument: 'whenAvailable' })

Events larger than 16 MB

db.orders.watch([{ $changeStreamSplitLargeEvent: {} }], { fullDocument: 'updateLookup', fullDocumentBeforeChange: 'required' })

Event types

Node.js, with a stored resume token

const stream = orders.watch([{ $match: { operationType: 'insert' } }], { resumeAfter: await loadToken() })
for await (const ev of stream) {
  await handle(ev.fullDocument)
  await saveToken(ev._id)
}

Basic full text search built into mongod

db.articles.createIndex({ title: 'text', body: 'text' }, { weights: { title: 5 } })
db.articles.find(
  { $text: { $search: 'oak table -pine "dining room"' } },
  { score: { $meta: 'textScore' }, title: 1 }
).sort({ score: { $meta: 'textScore' } }).limit(10)

Create a search index, then query with $search

db.products.createSearchIndex('default', { mappings: { dynamic: true } })
db.products.getSearchIndexes()
db.products.aggregate([
  { $search: { index: 'default', text: { query: 'oak tabel', path: ['name', 'description'], fuzzy: { maxEdits: 1 } } } },
  { $limit: 10 },
  { $project: { name: 1, score: { $meta: 'searchScore' } } }
])

Autocomplete

db.products.createSearchIndex('auto', { mappings: { dynamic: false, fields: { name: [{ type: 'autocomplete' }] } } })
db.products.aggregate([{ $search: { index: 'auto', autocomplete: { query: 'oa', path: 'name' } } }, { $limit: 5 }, { $project: { name: 1 } }])

A vector index and a semantic query

db.docs.createSearchIndex({
  name: 'vec',
  type: 'vectorSearch',
  definition: { fields: [
    { type: 'vector', path: 'embedding', numDimensions: 1024, similarity: 'cosine' },
    { type: 'filter', path: 'lang' }
  ] }
})
db.docs.aggregate([
  { $vectorSearch: { index: 'vec', path: 'embedding', queryVector: qv, numCandidates: 200, limit: 10, filter: { lang: 'en' } } },
  { $project: { title: 1, score: { $meta: 'vectorSearchScore' } } }
])

Hybrid search: combine vector and text results

db.docs.aggregate([
  { $rankFusion: {
      input: { pipelines: {
        vector: [{ $vectorSearch: { index: 'vec', path: 'embedding', queryVector: qv, numCandidates: 200, limit: 20 } }],
        text: [{ $search: { index: 'default', text: { query: 'refund policy', path: 'body' } } }, { $limit: 20 }]
      } },
      combination: { weights: { vector: 0.7, text: 0.3 } }
  } },
  { $limit: 10 }
])

GeoJSON points and a 2dsphere index

db.stores.insertOne({ name: 'Cluj', loc: { type: 'Point', coordinates: [23.5899, 46.7712] } })   // longitude first
db.stores.createIndex({ loc: '2dsphere' })
db.stores.find({ loc: { $near: { $geometry: { type: 'Point', coordinates: [23.6, 46.77] }, $maxDistance: 5000 } } })

Inside a shape, and distance as a field

db.stores.find({ loc: { $geoWithin: { $centerSphere: [[23.6, 46.77], 10 / 6378.1] } } })   // 10 km, radius in radians
db.stores.aggregate([
  { $geoNear: { near: { type: 'Point', coordinates: [23.6, 46.77] }, distanceField: 'meters', maxDistance: 20000, query: { open: true } } },
  { $limit: 5 }
])

Counts per category with $searchMeta

db.products.createSearchIndex('facets', { mappings: { dynamic: true, fields: { category: { type: 'token' } } } })
db.products.aggregate([
  { $searchMeta: {
      index: 'facets',
      facet: { operator: { text: { query: 'oak', path: 'name' } }, facets: { cats: { type: 'string', path: 'category' } } }
  } }
])

A time series collection

db.createCollection('metrics', {
  timeseries: { timeField: 'ts', metaField: 'meta', granularity: 'minutes' },
  expireAfterSeconds: 60 * 60 * 24 * 90
})
db.metrics.insertMany([
  { ts: new Date(), meta: { host: 'web1', metric: 'cpu' }, value: 41.2 },
  { ts: new Date(), meta: { host: 'web2', metric: 'cpu' }, value: 17.9 }
])

Granularity or custom bucket spans

db.createCollection('ticks', { timeseries: { timeField: 't', metaField: 'sym', bucketMaxSpanSeconds: 300, bucketRoundingSeconds: 300 } })
db.runCommand({ collMod: 'metrics', timeseries: { granularity: 'hours' } })     // can only grow

Secondary indexes

db.metrics.createIndex({ 'meta.host': 1, ts: -1 })
db.metrics.createIndex({ ts: -1 })

Downsample to five minute averages

db.metrics.aggregate([
  { $match: { 'meta.host': 'web1', ts: { $gte: ISODate('2026-09-29T00:00:00Z') } } },
  { $group: {
      _id: { $dateTrunc: { date: '$ts', unit: 'minute', binSize: 5 } },
      avg: { $avg: '$value' },
      max: { $max: '$value' }
  } },
  { $sort: { _id: 1 } }
])

Storage in 9.0

db.adminCommand({ renameCollection: 'shop.metrics', to: 'shop.metrics_2026' })

When not to use one

// frequent updates to single measurements
// documents looked up one by one by _id
// data without a real time dimension

The latest reading per series

db.metrics.aggregate([
  { $match: { ts: { $gte: new Date(Date.now() - 3600000) } } },
  { $group: { _id: '$meta.host', last: { $top: { sortBy: { ts: -1 }, output: { ts: '$ts', value: '$value' } } } } }
])

Move cold data to cheaper storage with Online Archive

atlas clusters onlineArchives create --clusterName Cluster0 --db shop --collection metrics \
  --dateField ts --archiveAfter 90

Enable authorization, then create the first user through the localhost exception

# /etc/mongod.conf
security:
  authorization: enabled

mongosh --host 127.0.0.1                  # on the server itself, before any user exists
use admin
db.createUser({ user: 'root', pwd: passwordPrompt(), roles: ['root'] })

Log in

mongosh "mongodb://db1.internal/shop?authSource=admin" -u app
db.auth('app', passwordPrompt())          // inside an open shell
db.runCommand({ connectionStatus: 1 }).authInfo.authenticatedUsers

Create, change and remove users

use admin
db.createUser({ user: 'app', pwd: passwordPrompt(), roles: [{ role: 'readWrite', db: 'shop' }] })
db.grantRolesToUser('app', [{ role: 'read', db: 'reports' }])
db.revokeRolesFromUser('app', [{ role: 'read', db: 'reports' }])
db.changeUserPassword('app', passwordPrompt())
db.getUsers()
db.dropUser('old_app')

Built-in roles

A custom role with exact privileges

db.createRole({
  role: 'orders_writer',
  privileges: [{ resource: { db: 'shop', collection: 'orders' }, actions: ['find', 'insert', 'update'] }],
  roles: []
})
db.grantRolesToUser('app', ['orders_writer'])
db.getRole('orders_writer', { showPrivileges: true })

Require TLS

net:
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/ssl/mongodb.pem
    CAFile: /etc/ssl/ca.pem
    disabledProtocols: TLS1_0,TLS1_1

Encryption at rest with the WiredTiger encrypted storage engine

mongod --enableEncryption --encryptionKeyFile /etc/mongodb/master.key --dbpath /var/lib/mongodb
# or KMIP: --kmipServerName kms.internal --kmipServerCAFile ca.pem

Auditing

auditLog:
  destination: file
  format: JSON
  path: /var/log/mongodb/audit.json
  filter: '{ atype: { $in: ["authenticate", "createUser", "dropCollection"] } }'

LDAP, Kerberos and OpenID Connect

mongosh "mongodb://db1.internal/?authMechanism=PLAIN&authSource=$external" -u ana
mongosh "mongodb://db1.internal/?authMechanism=GSSAPI&authSource=$external" -u ana@EXAMPLE.COM
mongosh "mongodb://db1.internal/?authMechanism=MONGODB-OIDC"

Queryable Encryption: query fields the server cannot read

const encryptedFields = { fields: [
  { path: 'ssn', bsonType: 'string', queries: { queryType: 'equality' } },
  { path: 'salary', bsonType: 'int', queries: { queryType: 'range', min: 0, max: 1000000 } }
] }
// the driver encrypts before sending; the server stores and compares ciphertext

Before a server faces a network

Allow an IP address on Atlas

atlas accessLists create 203.0.113.10 --type ipAddress --comment "office"
atlas accessLists list

Keep document contents out of the logs

security:
  redactClientLogData: true

Start three members, then initiate once

mongod --replSet rs0 --bind_ip localhost,db1.internal --dbpath /var/lib/mongodb --keyFile /etc/mongodb/keyfile
rs.initiate({
  _id: 'rs0',
  members: [
    { _id: 0, host: 'db1.internal:27017' },
    { _id: 1, host: 'db2.internal:27017' },
    { _id: 2, host: 'db3.internal:27017' }
  ]
})

Status

rs.status().members.map(m => ({ name: m.name, state: m.stateStr, health: m.health, lag: m.optimeDate }))

Add, remove, step down

rs.add('db4.internal:27017')
rs.add({ host: 'db5.internal:27017', priority: 0, votes: 0 })
rs.remove('db4.internal:27017')
rs.stepDown(60)                       // primary steps down for 60 seconds, triggers an election
rs.freeze(120)                        // this secondary will not seek election for 120 seconds

Change priorities, hide a member, delay one

cfg = rs.conf()
cfg.members[0].priority = 2                      // preferred primary
cfg.members[2].priority = 0
cfg.members[2].hidden = true                     // invisible to clients: analytics, backups
cfg.members[2].secondaryDelaySecs = 3600         // one hour behind, protects against mistakes
rs.reconfig(cfg)

Member roles

The oplog window and replication lag

rs.printReplicationInfo()
rs.printSecondaryReplicationInfo()

Resize the oplog without a restart

db.adminCommand({ replSetResizeOplog: 1, size: 16384 })          // MB, run on each member
db.adminCommand({ replSetResizeOplog: 1, minRetentionHours: 72 })

Read preference

db.orders.find().readPref('secondaryPreferred', [{ region: 'eu-west' }])
mongodb+srv://cluster0.example.net/shop?readPreference=secondaryPreferred&maxStalenessSeconds=120

Who is primary, from any member

db.hello().primary
db.hello().isWritablePrimary
rs.status().members.find(m => m.stateStr === 'PRIMARY').name

Pick the key, then shard

sh.enableSharding('shop')                                             // optional in recent versions
db.orders.createIndex({ customer_id: 1, created_at: 1 })
sh.shardCollection('shop.orders', { customer_id: 1, created_at: 1 })   // ranged
sh.shardCollection('shop.events', { device_id: 'hashed' })             // hashed: even writes

Test a candidate key on real traffic

db.adminCommand({ analyzeShardKey: 'shop.orders', key: { customer_id: 1 }, keyCharacteristics: true, readWriteDistribution: true })
db.adminCommand({ configureQueryAnalyzer: 'shop.orders', mode: 'full', samplesPerSecond: 10 })

Where the data is

sh.status()
db.orders.getShardDistribution()
db.getSiblingDB('admin').aggregate([{ $shardedDataDistribution: {} }])

Change the shard key online

db.adminCommand({ reshardCollection: 'shop.orders', key: { customer_id: 'hashed' } })
db.adminCommand({ refineCollectionShardKey: 'shop.orders', key: { customer_id: 1, created_at: 1, _id: 1 } })   // add suffix fields
db.adminCommand({ reshardCollection: 'shop.orders', key: { customer_id: 1 }, forceRedistribution: true })       // same key, spread again

Move or unshard a whole collection

db.adminCommand({ moveCollection: 'shop.audit', toShard: 'shard02' })
db.adminCommand({ unshardCollection: 'shop.logs', toShard: 'shard01' })

The balancer

sh.getBalancerState()
sh.stopBalancer()                  // before a manual backup of the cluster
sh.startBalancer()
db.getSiblingDB('config').settings.updateOne(
  { _id: 'balancer' },
  { $set: { activeWindow: { start: '01:00', stop: '05:00' } } },
  { upsert: true }
)

Remove a shard with the draining commands

db.adminCommand({ startShardDraining: 'shard03' })
db.adminCommand({ shardDrainingStatus: 'shard03' })
db.adminCommand({ commitShardRemoval: 'shard03' })

Targeted versus scatter gather

db.orders.find({ customer_id: cid })            // goes to one shard
db.orders.find({ status: 'paid' })              // asks every shard
db.orders.find({ status: 'paid' }).explain().queryPlanner.winningPlan.stage

Keep EU customers on EU shards

sh.addShardToZone('shard-eu-1', 'EU')
sh.addShardToZone('shard-us-1', 'US')
sh.shardCollection('shop.customers', { region: 1, _id: 1 })
sh.updateZoneKeyRange('shop.customers', { region: 'EU', _id: MinKey() }, { region: 'EU', _id: MaxKey() }, 'EU')
sh.updateZoneKeyRange('shop.customers', { region: 'US', _id: MinKey() }, { region: 'US', _id: MaxKey() }, 'US')

Dump and restore one database

mongodump --uri="$MONGODB_URI" --db=shop --gzip --archive=shop-2026-09-29.archive.gz
mongorestore --uri="$RESTORE_URI" --gzip --archive=shop-2026-09-29.archive.gz --nsInclude='shop.*'

One collection, a subset, or into another database

mongodump --uri="$MONGODB_URI" --db=shop --collection=orders --query='{"status":"paid"}' --out=dump/
mongorestore --uri="$MONGODB_URI" --nsFrom='shop.*' --nsTo='shop_copy.*' dump/
mongorestore --uri="$MONGODB_URI" --drop --nsInclude='shop.orders' dump/

Consistent dump of a running replica set

mongodump --uri="$MONGODB_URI" --oplog --gzip --archive=full.archive.gz
mongorestore --uri="$RESTORE_URI" --oplogReplay --gzip --archive=full.archive.gz

mongoexport to JSON or CSV

mongoexport --uri="$MONGODB_URI" --collection=orders --query='{"status":"paid"}' --out=paid.json
mongoexport --uri="$MONGODB_URI" --collection=orders --type=csv --fields=_id,status,total,created_at --out=orders.csv
mongoexport --uri="$MONGODB_URI" --collection=orders --jsonArray --pretty --limit=5

Inspect a BSON file

bsondump dump/shop/orders.bson | head -n 3
bsondump --type=debug dump/shop/orders.bson

Filesystem snapshot of a member

db.fsyncLock()          // flush and block writes on this member
// take the LVM, EBS or ZFS snapshot here
db.fsyncUnlock()

Managed backups with point in time restore

atlas backups snapshots list Cluster0
atlas backups restores start pointInTime --clusterName Cluster0 --pointInTimeUTCSeconds 1790678034 --targetClusterName Cluster0-restore

Choosing a method

Stream a collection from one cluster to another, with no file in between

mongodump --uri="$SOURCE_URI" --db=shop --collection=orders --archive | \
  mongorestore --uri="$TARGET_URI" --archive --nsInclude='shop.orders' --drop

Connections and operation counters

db.serverStatus().connections
db.serverStatus().opcounters

The WiredTiger cache

const c = db.serverStatus().wiredTiger.cache
({ usedGB: c['bytes currently in the cache'] / 2 ** 30, maxGB: c['maximum bytes configured'] / 2 ** 30, dirtyGB: c['tracked dirty bytes in the cache'] / 2 ** 30 })

Latency per collection

db.orders.aggregate([{ $collStats: { latencyStats: { histograms: false } } }]).next().latencyStats
db.adminCommand({ top: 1 }).totals['shop.orders']

mongostat and mongotop

mongostat --uri="$MONGODB_URI" 5                 # every 5 seconds
mongotop --uri="$MONGODB_URI" 10                 # time spent per collection

Logs from inside the shell

db.adminCommand({ getLog: 'global' }).log.slice(-5)
db.adminCommand({ getLog: 'startupWarnings' })
db.adminCommand({ setParameter: 1, logLevel: 1 })

What to alert on

Every database with its size, largest first

db.adminCommand({ listDatabases: 1 }).databases
  .sort((a, b) => b.sizeOnDisk - a.sizeOnDisk)
  .map(d => `${d.name}: ${(d.sizeOnDisk / 2 ** 30).toFixed(2)} GiB`)

Atlas metrics from the command line

atlas processes list
atlas metrics processes cluster0-shard-00-00.example.net:27017 --granularity PT1M --period PT1H --type CONNECTIONS,OPCOUNTER_QUERY

Read the running configuration

db.adminCommand({ getCmdLineOpts: 1 }).parsed
db.adminCommand({ getParameter: '*' })
db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })

Change a parameter at runtime

db.adminCommand({ setParameter: 1, cursorTimeoutMillis: 1200000 })
db.adminCommand({ setParameter: 1, transactionLifetimeLimitSeconds: 120 })

Production settings on Linux

# XFS for the data directory, noatime
# ulimit -n 64000 and ulimit -u 64000 for the mongod user (the packaged systemd unit sets them)
# 8.0 and newer: Transparent Huge Pages enabled (always); earlier versions: disabled
# vm.swappiness = 1, and NTP or chrony on every member

Rolling upgrade of a replica set

# 1. upgrade each secondary: stop mongod, install the new binaries, start, wait for SECONDARY
# 2. step down the primary, then upgrade it the same way
rs.stepDown()
# 3. when every member runs the new version and the application works:
db.adminCommand({ setFeatureCompatibilityVersion: '9.0', confirm: true })

Upgrade paths

Stable API: keep code working across upgrades

const client = new MongoClient(uri, { serverApi: { version: '1', strict: true, deprecationErrors: true } })

Control the service on Linux

sudo systemctl start mongod
sudo systemctl restart mongod
sudo systemctl status mongod
journalctl -u mongod --since "10 min ago"
tail -f /var/log/mongodb/mongod.log | jq -c 'select(.s == "W" or .s == "E")'

Rotate the log

db.adminCommand({ logRotate: 1 })
# mongod.conf, when logrotate moves the file:
systemLog:
  logRotate: reopen

Change an Atlas cluster tier without downtime

atlas clusters update Cluster0 --tier M30
atlas clusters watch Cluster0

The in-memory storage engine

storage:
  engine: inMemory
  inMemory:
    engineConfig:
      inMemorySizeGB: 8

The official driver

import { MongoClient, ObjectId } from 'mongodb'

const client = new MongoClient(process.env.MONGODB_URI, { maxPoolSize: 50 })
const orders = client.db('shop').collection('orders')

const recent = await orders.find({ status: 'paid' }).sort({ created_at: -1 }).limit(20).toArray()
const one = await orders.findOne({ _id: new ObjectId(req.params.id) })
await orders.updateOne({ _id: one._id }, { $set: { status: 'shipped' } })

Mongoose

import mongoose from 'mongoose'
await mongoose.connect(process.env.MONGODB_URI)
const Order = mongoose.model('Order', new mongoose.Schema({
  status: { type: String, enum: ['new', 'paid', 'shipped'], index: true },
  total: Number
}, { timestamps: true }))
const paid = await Order.find({ status: 'paid' }).sort({ createdAt: -1 }).limit(20).lean()

PyMongo, with the async client

import os
from bson import ObjectId
from pymongo import MongoClient, AsyncMongoClient

client = MongoClient(os.environ["MONGODB_URI"])
orders = client.shop.orders
recent = list(orders.find({"status": "paid"}).sort("created_at", -1).limit(20))
one = orders.find_one({"_id": ObjectId(order_id)})

aclient = AsyncMongoClient(os.environ["MONGODB_URI"])
doc = await aclient.shop.orders.find_one({"status": "new"})

Go driver v2

client, err := mongo.Connect(options.Client().ApplyURI(os.Getenv("MONGODB_URI")))
if err != nil { log.Fatal(err) }
defer client.Disconnect(context.Background())

orders := client.Database("shop").Collection("orders")
opts := options.Find().SetSort(bson.D{{Key: "created_at", Value: -1}}).SetLimit(20)
cur, err := orders.Find(ctx, bson.D{{Key: "status", Value: "paid"}}, opts)
var recent []Order
err = cur.All(ctx, &recent)

Java sync driver

MongoClient client = MongoClients.create(System.getenv("MONGODB_URI"));
MongoCollection<Document> orders = client.getDatabase("shop").getCollection("orders");
List<Document> recent = orders.find(Filters.eq("status", "paid"))
    .sort(Sorts.descending("created_at"))
    .limit(20)
    .into(new ArrayList<>());
orders.updateOne(Filters.eq("_id", new ObjectId(id)), Updates.set("status", "shipped"));

C# driver with typed models

var client = new MongoClient(Environment.GetEnvironmentVariable("MONGODB_URI"));
var orders = client.GetDatabase("shop").GetCollection<Order>("orders");
var recent = await orders.Find(o => o.Status == "paid")
    .SortByDescending(o => o.CreatedAt)
    .Limit(20)
    .ToListAsync();
await orders.UpdateOneAsync(o => o.Id == id, Builders<Order>.Update.Set(o => o.Status, "shipped"));

ObjectId from a string, safely

// Node.js
if (!ObjectId.isValid(id)) return res.status(400).end()
const doc = await orders.findOne({ _id: ObjectId.createFromHexString(id) })

Never build filters from raw request bodies

// { "email": { "$ne": null } } in a login body would match any user
const email = String(req.body.email)
const user = await users.findOne({ email })

Pool and timeout options in the connection string

mongodb+srv://cluster0.example.net/shop?maxPoolSize=50&minPoolSize=5&maxIdleTimeMS=60000&serverSelectionTimeoutMS=5000&timeoutMS=10000

Reuse the client across function invocations

let clientPromise
export async function handler(event) {
  clientPromise ??= new MongoClient(process.env.MONGODB_URI, { maxPoolSize: 5 }).connect()
  const client = await clientPromise
  return client.db('shop').collection('orders').findOne({ _id: event.id })
}

Codes to handle in application code

Catch duplicates in Node.js

try {
  await users.insertOne({ email })
} catch (e) {
  if (e.code === 11000) return res.status(409).json({ error: 'email already registered' })
  throw e
}

The messages and what they mean

Diagnose from the client machine

mongosh "$MONGODB_URI" --eval "db.runCommand({ ping: 1 })"
nslookup -type=SRV _mongodb._tcp.cluster0.example.net
nc -vz db1.internal 27017
curl -s https://checkip.amazonaws.com          # the public IP to add to the Atlas access list

Sort without an index on a large result

db.orders.find().sort({ note: 1 }).allowDiskUse(false)

Cursor timed out in a long loop

db.orders.find().forEach(d => slowWork(d))

Write concern not satisfied in time

db.orders.insertOne({ total: 10 }, { writeConcern: { w: 'majority', wtimeout: 2000 } })

Retry a transaction in Python

from pymongo.errors import PyMongoError
try:
    session.with_transaction(transfer)
except PyMongoError as e:
    if e.has_error_label("TransientTransactionError"):
        pass  # with_transaction already retried for 120 seconds; alert or queue the work
    raise

Versions and end of life, as of September 29, 2026

What each recent version added

Terms

The same statements side by side

MongoDB or a relational database

Server, shell and FCV versions

db.version()
version()
db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 }).featureCompatibilityVersion.version

Removed, deprecated and replaced

The same JSON query in MongoDB and PostgreSQL