A MongoDB install has a server, mongod, which runs in the background, owns a data directory, and listens on port 27017, and a client that connects to it. mongosh is the interactive client. It's a full JavaScript environment, so everything you type is JavaScript: queries are method calls like db.users.find(), and you can use variables, loops, and functions. Your own programs connect the same way through an official driver for their language.

A connection is described by a connection string, a URL such as mongodb://localhost:27017/shop: the scheme, the host and port, and optionally the database to start in. Plain mongosh means mongodb://127.0.0.1:27017/test. The prompt shows the current database, test> to begin with. test is just a default name and doesn't exist until you write to it. A remote or password-protected server adds a username and options to the same URL, for example mongodb://app:secret@db.example.com:27017/shop?authSource=admin.

mongod

The MongoDB server process; it owns the data files and listens on port 27017.

mongosh

The MongoDB Shell, an interactive JavaScript client for talking to a server.

Connection string

A URL like mongodb://host:27017/db that tells a client where and how to connect.

Most of what you type is JavaScript, but a handful of shell helpers are special words the shell understands directly. show dbs lists databases with their size on disk, use shop switches to a database, and show collections lists the collections in the current one. db is a variable that always holds the current database, so db on its own prints its name and db.users refers to the users collection in it. There's no need to create either first: MongoDB creates databases and collections the first time you write to them.

The shell has built-in help at every level. help lists the helpers, db.help() lists database methods, and db.users.help() lists collection methods. When a query returns more than 20 documents, mongosh prints the first batch of 20 and waits. Type it (short for iterate) to see the next batch. The three databases you'll see in show dbs, admin, config, and local, belong to MongoDB itself; leave them alone.

Shell helper

A mongosh shortcut that is not JavaScript, such as show dbs or use.

db

The shell variable that holds the current database.

Batch

The 20 documents mongosh prints at a time; type it for the next batch.

The data is nested three levels deep. A database is a separate container, usually one per application. Inside it, a collection plays the part of a table, and a document plays the part of a row. A document is a set of field–value pairs written like a JavaScript object: { name: "Alice", age: 34 }. Unlike rows in a table, two documents in the same collection don't need the same fields, and a value can itself be an array or another document. So a user can carry a list of interests or a nested address without extra tables.

Every document has an _id field that uniquely identifies it in its collection. If you don't supply one, MongoDB generates an ObjectId: a 12-byte value that's unique across machines and starts with the time it was created. Documents are stored as BSON, a binary form of JSON with more types: separate integer and floating-point numbers, a real date type, Decimal128 for money, and ObjectId itself. The shell shows these as ISODate(...), ObjectId(...), and so on. db.createCollection() makes an empty collection, which is only needed when you want to set options such as validation (covered at the Advanced level).

Collection

A group of documents in a database; MongoDB's equivalent of a table.

Document

A record made of field-value pairs; MongoDB's equivalent of a row.

ObjectId

The default _id value: 12 bytes, unique, and starting with its creation time.

insertOne(doc) stores a single document and returns its insertedId. insertMany([doc, doc, ...]) stores several in one round trip, which is much faster than a loop of insertOne calls, and returns every generated id. The documents don't need identical fields: notice below that Dave has no email at all. In MongoDB a missing field and a field set to null are different things, and queries can tell them apart.

The one rule every document must obey is a unique _id. Insert a document whose _id already exists and the server rejects it with a duplicate key error (code 11000). By default insertMany is ordered: it stops at the first error, and documents after the failure are not inserted. Pass { ordered: false } to insert everything that's valid and report the failures at the end. Either way, documents inserted before the error stay inserted, because each document insert is atomic on its own.

insertMany

Inserts an array of documents in one call; ordered by default.

Duplicate key error

Error 11000: a document reused a value that must be unique, such as _id.

Ordered insert

An insertMany that stops at the first error; ordered: false continues past it.

find() takes up to two documents. The first is the filter, which describes what to match. {} matches everything, and { city: "London" } matches documents whose city equals London. The second is the projection, which picks the fields to return: { name: 1, age: 1 } includes just those (plus _id unless you add _id: 0), and { interests: 0 } returns everything except that field. findOne() returns the first match as a single document, not a list.

find() returns a cursor, a pointer into the results that fetches documents in batches as you read them, which is why a huge collection doesn't flood your memory. Cursor methods shape the results: .sort({ age: -1 }) sorts descending (1 is ascending), .limit(2) caps the count, and .skip(2) skips some first, which is how pages are built. Without .sort(), documents come back in whatever order is cheapest, so never rely on it. countDocuments(filter) counts matches without returning them.

Filter

A document describing which documents to match; {} matches all.

Projection

A document choosing which fields to return: 1 includes, 0 excludes.

Cursor

A handle on query results that fetches them in batches as you iterate.

An update takes a filter and an update document made of operators. $set sets fields, $inc adds to a number, and $unset removes a field. The operator matters: { $set: { city: "Madrid" } } changes one field and leaves the rest alone. updateOne changes the first match and updateMany changes every match. The result reports matchedCount (how many the filter found) and modifiedCount (how many actually changed). If they differ, the value was already what you set. replaceOne swaps a whole document for a new one, keeping only its _id.

deleteOne removes the first matching document and deleteMany removes them all. The dangerous one is deleteMany({}): an empty filter matches everything, so it empties the collection without asking. db.collection.drop() removes the collection itself, including its indexes. As with SQL, the safe habit is to run the filter with find() first and look at what it matches, then turn it into an update or delete.

Update operator

A $-prefixed instruction such as $set, $inc, or $unset.

matchedCount / modifiedCount

How many documents the filter found vs how many actually changed.

drop()

Removes a whole collection, including its documents and indexes.

Beyond simple equality, a filter uses query operators, which start with a dollar sign and sit inside the field's value. Comparison: $gt, $gte, $lt, $lte, and $ne (not equal), so { age: { $gte: 30, $lt: 50 } } is a range. Set membership: $in and $nin match any, or none, of a list. Putting several fields in one filter means and; for or, use $or with an array of conditions: { $or: [ { city: "Rome" }, { age: { $lt: 20 } } ] }.

Two situations need care. First, a missing field and a null field are different: { email: null } matches both documents where email is null and documents with no email field, while { email: { $exists: false } } matches only the missing ones. Second, text patterns use regular expressions: { name: /^c/i } means starts with c, ignoring case. A regex anchored with ^ can use an index; one that isn't has to scan every value. For real word search, MongoDB has text indexes, and Atlas has a full search engine.

Query operator

A $-prefixed condition inside a filter, such as $gt, $in, or $or.

$exists

Matches documents that have (true) or lack (false) a field.

Regular expression

A text pattern such as /^c/i used to match string values.

Arrays are first-class. A filter on an array field matches if any element matches, so { interests: "chess" } finds everyone with chess among their interests. $all requires every listed value, $size matches an exact length, and $elemMatch requires one element to meet several conditions at once, which matters for arrays of documents. Embedded documents are reached with dot notation: { "address.city": "London" } looks inside the address field. The quotes are required whenever a field name contains a dot.

Arrays have their own update operators, so you never have to read, modify, and write back the whole list. $push appends a value, $addToSet appends only if the value isn't already there, $pull removes every matching value, and $pop removes the first or last element. $push with $each adds several values at once. These operators are atomic on a single document, so two users updating the same list at the same moment can't overwrite each other's changes.

Dot notation

A path like "address.city" that reaches inside embedded documents and arrays.

$elemMatch

Requires a single array element to satisfy all of several conditions.

$addToSet

Adds a value to an array only if it is not already present.

Pass { upsert: true } to updateOne and it becomes insert-or-update. If the filter matches, the update is applied as usual. If it doesn't, MongoDB builds a new document from the filter's equality fields plus the update, and reports its id as upsertedId. $setOnInsert sets fields only when an upsert inserts, which is perfect for values like a creation date that should never change afterwards. Upserts are the natural way to keep a counter or a last seen record without first checking whether it exists.

Other useful operators: $mul multiplies a number, $min and $max only change a value if the new one is lower or higher, $rename renames a field, and $currentDate stores the server's current time. findOneAndUpdate updates a document and returns it in one atomic step, before the change by default or after it with { returnDocument: "after" }. That's how you hand out the next number in a sequence without two clients ever getting the same one.

Upsert

An update that inserts a new document when nothing matches ({ upsert: true }).

$setOnInsert

Sets fields only when an upsert creates a new document.

findOneAndUpdate

Updates one document and returns it atomically, before or after the change.

For anything beyond fetching documents (totals, averages, counts per category), MongoDB uses the aggregation pipeline. aggregate() takes an array of stages, and documents flow through them in order, each stage transforming what it receives. $match filters (it takes the same filter language as find), $group combines documents that share a key, $sort orders them, $project reshapes each document, and $count counts what's left. Put $match as early as possible, since everything after it then has less work to do, and it can use an index.

$group is the heart of most reports. Its _id is the grouping key: "$status" means one group per distinct status, and null means one group for everything. The other fields are accumulators that compute a value per group: { $sum: "$amount" } adds up amounts, { $sum: 1 } counts documents, and $avg, $min, $max, and $push do what they say. A dollar sign in front of a field name, as in "$amount", means the value of that field, not the text "amount".

Pipeline

An array of stages that documents pass through in order.

$group

Combines documents sharing a key (_id) and computes accumulators per group.

Accumulator

A per-group calculation such as $sum, $avg, $min, $max, or $push.

MongoDB encourages you to embed data that's read together, but separate collections that refer to each other by _id are common too, like the orders above, each holding a userId. The $lookup stage is MongoDB's join. For each input document it finds the documents in another collection whose field matches (localField equal to foreignField), and puts them in a new array field (as). It's always an array, even when there's exactly one match, and it's empty when there's none, like a SQL left join.

$unwind deconstructs an array: a document with a three-element array becomes three documents, one per element. After a $lookup that finds one user per order, $unwind: "$user" turns the one-element array into a plain embedded document, so later stages can use "$user.name". Unwinding is also how you count or group by the elements of an array, for example how many users are interested in each hobby. By default $unwind drops documents whose array is empty; preserveNullAndEmptyArrays: true keeps them.

$lookup

A pipeline stage that joins in matching documents from another collection as an array.

$unwind

Turns each element of an array into its own document.

Reference

Storing another document's _id in a field, to be joined with $lookup.

Without a suitable index, a query does a collection scan (COLLSCAN): it reads every document and tests each one. An index is a sorted structure (a B-tree) of one or more fields' values, pointing to the documents, so the server can find matches directly. That's an index scan (IXSCAN). Every collection has an index on _id automatically. createIndex({ userId: 1 }) adds one on userId (1 ascending, -1 descending), and { unique: true } makes the index enforce uniqueness, the right way to stop two users registering the same email.

explain("executionStats") runs the query and reports how. Look at the winning plan's stage, and compare totalDocsExamined with nReturned: examining 200,000 documents to return 200 is the sign of a missing index. A compound index such as { status: 1, orderedAt: -1 } serves queries that filter on status and sort by orderedAt, and also queries on status alone, but not queries on orderedAt alone. The field order matters. Indexes cost memory and slow down writes a little, so add them for the queries you actually run.

COLLSCAN

A collection scan: every document is read to find the matches.

IXSCAN

An index scan: the server uses an index to go straight to matches.

Compound index

An index on several fields; it serves queries on its leading fields.

MongoDB doesn't require a schema, but you can add one. A validator attached to a collection is checked on every insert and update, and documents that fail are rejected, giving back the guarantees a SQL table has, only where you want them. The usual form is $jsonSchema: required lists fields that must be present, and properties gives each field's bsonType (such as "string", "int", "double", "date") plus rules like minimum, enum, or pattern.

Set the validator with createCollection for a new collection, or with db.runCommand({ collMod: ... }) for an existing one. validationLevel: "moderate" applies the rules only to documents that already pass, which is useful when tightening an old collection. validationAction: "warn" logs violations instead of rejecting them, a good way to find out what a new rule would break. The error message is long but precise: it names each rule a document broke and the value it considered.

Validator

Rules attached to a collection that every insert and update must pass.

$jsonSchema

The validator format that describes required fields, types, and value rules.

bsonType

A field's required BSON type, such as string, int, double, or date.

Embedding puts related data inside the document that owns it: an order holds its line items as an array, a user holds their address. One read returns everything, and a single-document update is atomic, so the order and its items can never be out of step. Embed when the data is read together, belongs to one parent, and stays bounded in size. A document can be at most 16 MB, so an ever-growing list, such as every page view a user has ever made, must not be embedded.

Referencing stores another document's _id instead, as the orders collection does with userId. Use it when the related data is shared by many documents (one product in thousands of orders), when it's large or unbounded, or when it's often read on its own. You join references with $lookup or a second query. A useful rule of thumb: design for how the data is read. Data that's always displayed together belongs together, and duplicating a small, rarely changing value, such as a product name on an order line, is often better than a join on every read.

Embedding

Storing related data inside the parent document, read and updated in one operation.

Referencing

Storing another document's _id and joining when needed.

16 MB limit

The maximum size of one document, which rules out embedding unbounded lists.

A replica set is a group of mongod servers holding copies of the same data: one primary takes writes, and secondaries copy them and take over if the primary fails. Production MongoDB always runs as a replica set, and Atlas does this for you. Some features only exist on a replica set, transactions among them. A standalone server, like the one this guide installed, rejects them. For learning, start mongod with --replSet rs0 (or add replication.replSetName: rs0 to mongod.conf), run rs.initiate() once, and you have a one-member set. The prompt then shows rs0 [direct: primary].

A single-document write is always atomic, which is why good embedding removes most of the need for transactions. When you must change several documents together, such as moving stock between two warehouses, start a session, call startTransaction(), do the work through the session's database handle, then commitTransaction() or abortTransaction(). Nothing is visible outside the transaction until it commits. Keep transactions short: by default MongoDB aborts any that run longer than 60 seconds.

Replica set

A group of servers holding copies of the same data, with one primary taking writes.

Primary

The replica set member that accepts writes; secondaries replicate from it.

Transaction

Several operations that commit together or not at all; needs a replica set.

A fresh install has access control disabled: anyone who can reach the port can read and delete everything, which is only safe because the server listens on 127.0.0.1. To lock it down, first create an administrator in the admin database, then enable authorization, by setting security.authorization: enabled in mongod.conf and restarting. The localhost exception makes this possible: on a server with authorization on and no users yet, a connection from the same machine may create the first user, and nothing else.

A user is created in one database, its authentication database, and is granted roles. Built-in roles cover most needs: read and readWrite on one database, dbAdmin for indexes and statistics, userAdminAnyDatabase to manage users, and root for everything. Give each application its own user with the smallest role that works, the principle of least privilege, so a bug or a leaked password in a reporting tool can't delete your data. Connect with mongosh -u name -p --authenticationDatabase shop, or put the username in the connection string.

Access control

Requiring every connection to log in, set by security.authorization.

Role

A named set of privileges, such as read, readWrite, or root.

Localhost exception

Lets a local connection create the first user when none exist yet.

Store dates as real Date values, not strings. new Date("2025-03-01") creates one, the shell shows it as ISODate(...), and it's stored in UTC. Real dates compare and sort correctly, work with range queries like { joined: { $gte: new Date("2024-01-01") } }, and can be grouped by month in a pipeline. A date stored as the string "2025-03-01" does none of that reliably. An ObjectId also carries its creation time: getTimestamp() reads it back, so _id order is roughly insertion order.

Numbers come in several types. The shell's default is a 64-bit floating-point double, which can't represent some decimals exactly (0.1 + 0.2 isn't quite 0.3), so money should use Decimal128, written NumberDecimal("19.99") in the shell. Whole numbers can be stored as NumberInt (32-bit) or NumberLong (64-bit) when a validator or another program expects integers. Types matter in matching: the number 42 and the string "42" are different values, and $type finds documents where a field has a given type.

ISODate

The shell's display of a BSON Date, stored in UTC.

Decimal128

An exact decimal type for money, written NumberDecimal("19.99").

$type

A query operator that matches fields of a given BSON type.

$addFields (also called $set in a pipeline) adds computed fields while keeping the rest of the document. Combined with expression operators it can do arithmetic ($multiply, $subtract), string work ($concat, $toUpper), conditionals ($cond), and date work. $dateToString formats a date, so grouping by { $dateToString: { format: "%Y-%m", date: "$orderedAt" } } gives one row per month, the most common sales report there is.

$bucket sorts documents into ranges: give it the field, the boundaries (for example ages 0, 30, 50, 120), and an output per bucket. Each boundary starts a bucket, and the last one only closes the final bucket. $facet runs several sub-pipelines over the same input in one pass and returns all their results together, which is how a search page shows result counts by category, price range, and brand at once. Aggregations can end with $out or $merge to write their results into a collection, which works as a stored report you refresh on a schedule.

$addFields

Adds computed fields to each document, keeping the existing ones.

$dateToString

Formats a date as text, often used to group by day or month.

$bucket

Groups documents into ranges defined by a list of boundaries.

These tools come in the MongoDB Database Tools package. It's included with the Linux mongodb-org package and Homebrew's formula, and it's a separate download on Windows. They run from your terminal, not inside mongosh. mongodump --db=shop writes a BSON dump, one .bson file per collection plus its indexes and options, into a dump/ folder. mongorestore loads it back, and --nsFrom/--nsTo let you restore into a different database name, which is the easy way to test a backup. --gzip compresses the dump.

mongoexport writes one collection as JSON (one document per line, or --jsonArray) or as CSV with --type=csv --fields=..., for spreadsheets and other programs. mongoimport reads JSON or CSV back in; with --headerline a CSV's first row becomes the field names. Export loses some type detail, since CSV has no dates or ObjectIds, so use mongodump for backups and export/import for exchanging data. As with any database, a backup you have never restored is only a hope: restore into a scratch database now and then.

mongodump

Writes a database or collection to BSON files for backup.

mongorestore

Loads a mongodump back into a server, optionally under a new name.

mongoexport

Writes a collection as JSON or CSV for use outside MongoDB.