Introduction to MongoDB

Nothing was created beforehand. The store database and the products collection come into existence on the first insert, and the third document has a field the others lack. That flexibility is the main attraction of MongoDB and, used carelessly, its main hazard.

How MongoDB terms map to relational ones

Documents and BSON

Documents are stored in BSON, a binary encoding of JSON with more data types: dates, 32- and 64-bit integers, 128-bit decimals, binary data and ObjectId, among others. Types matter in queries: the string "42" does not match the number 42.

Rules worth knowing from the start:

• Every document has an _id field that is unique within its collection. If you do not supply one, the driver generates an ObjectId.
• A single document can be at most 16 MB.
• Field names are case-sensitive. price and Price are different fields.

Embed or reference

In a relational design, a product's stock levels would be rows in another table. Here they are embedded in the product document, so one read returns everything. Embedding suits data that belongs to its parent and is read with it. Use a reference (store the other document's _id) when the related data is large, shared by many parents or grows without bound; an array that keeps growing will eventually hit the document size limit and makes every update more expensive.

Model around how the application reads and writes the data. That is the opposite of the relational habit of normalising first.

Reading and changing data

find takes a filter and, optionally, a projection listing the fields to return:

db.products.find(
  { price: { $lt: 100 }, tags: "peripherals" },
  { _id: 0, sku: 1, name: 1, price: 1 }
)

[
  { sku: 'KB-101', name: 'Mechanical keyboard', price: 89 },
  { sku: 'MS-220', name: 'Wireless mouse', price: 24.5 }
]

Conditions in a filter are combined with AND. tags: "peripherals" matches documents whose tags array contains that value. Nested fields use dot notation, as in { "stock.retail": { $lte: 5 } }.

Updates use operators that describe the change. Without an operator such as $set, you would be supplying a replacement document, which updateOne rejects:

db.products.updateOne(
  { sku: "MS-220" },
  { $inc: { "stock.retail": -1 }, $set: { onSale: true } }
)

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

Always check matchedCount. A filter with a misspelt field name is not an error; it matches nothing and the update silently does nothing.

deleteOne and deleteMany take the same kind of filter. deleteMany({}) removes every document in the collection, so write the filter first and test it with find.

A write to a single document is atomic, including changes to its embedded fields and arrays.

Aggregation

For anything beyond simple filtering, MongoDB uses an aggregation pipeline: a list of stages, each transforming the output of the one before. This counts products and averages the price per tag:

db.products.aggregate([
  { $unwind: "$tags" },
  { $group: { _id: "$tags", products: { $sum: 1 }, avgPrice: { $avg: "$price" } } },
  { $sort: { _id: 1 } }
])

[
  { _id: 'displays', products: 1, avgPrice: 229 },
  { _id: 'peripherals', products: 2, avgPrice: 56.75 },
  { _id: 'usb', products: 1, avgPrice: 89 },
  { _id: 'wireless', products: 1, avgPrice: 24.5 }
]

$match filters, $group aggregates, $project reshapes, $sort and $limit do what their names say, and $lookup performs a left outer join to another collection.

Indexes

Without an index, a query scans every document in the collection. MongoDB creates an index on _id automatically; you add the others:

db.products.createIndex({ sku: 1 }, { unique: true })
db.products.find({ sku: "KB-101" }).explain("executionStats")

In the explain output, a winning plan containing IXSCAN used an index and COLLSCAN scanned the whole collection. Compare totalDocsExamined with the number of documents returned to see how much work a query did. Indexes can cover several fields, array elements, text and geospatial data. Each one speeds up reads and adds cost to writes.

Schema validation

"Schemaless" means MongoDB does not require a schema, not that you should go without one. A collection can carry a validator, written as JSON Schema, that rejects documents which do not conform:

db.runCommand({
  collMod: "products",
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["sku", "name", "price"],
      properties: {
        sku:   { bsonType: "string" },
        name:  { bsonType: "string" },
        price: { bsonType: ["double", "int", "decimal"], minimum: 0 }
      }
    }
  }
})

After this, inserting a product without a price fails with MongoServerError: Document failed validation. For money, prefer the decimal type (Decimal128("89.00") in mongosh) over the default floating-point number.

Replication, sharding and transactions

• Replica sets keep copies of the data on several servers. One member, the primary, accepts writes; the others replicate from it, and one is elected primary automatically if the current primary fails. Production deployments run as a replica set.
• Sharding splits a large collection across several replica sets according to a shard key, so data size and write load can grow beyond one server.
• Multi-document transactions with ACID guarantees are supported on replica sets (since MongoDB 4.0) and sharded clusters (since 4.2). They cost more than single-document writes, and a design that needs them constantly is often better served by embedding or by a relational database.

Editions and licence

Since October 2018 the server has been published under the Server Side Public License (SSPL). The source code is available and the Community Edition is free to use, but the SSPL is not approved by the Open Source Initiative, so MongoDB is "source-available", not open source in that sense. For most users this changes nothing. It matters if you plan to offer MongoDB itself as a hosted service to others. The official drivers are under the Apache License 2.0.

Official drivers exist for the common languages, including JavaScript, Python, Java, C#, Go, PHP, Ruby, Rust, C and C++.

When MongoDB fits and when it does not

It is a reasonable choice when:

• Records are naturally hierarchical or vary in shape: product catalogues, content, user profiles, event data.
• You read and write whole objects more often than you join across them.
• The structure is still changing, or you expect to need horizontal scaling.

Look at a relational database instead when the data is highly interconnected, when you rely on joins and constraints across many entities, or when ad hoc reporting across everything is the main workload.

Common mistakes

• No indexes. Queries work on a small collection and slow down as it grows. Check explain() for COLLSCAN.
• Treating flexibility as "no design needed". Inconsistent field names and types accumulate. Add validation early.
• Unbounded arrays. Embedding every comment or log entry in one parent document.
• Mixing types. Storing a price as a string in some documents and a number in others; range queries and sorts then misbehave.
• Exposing an unsecured server. A self-managed installation has access control turned off until you enable it. Do that before the server listens on anything but localhost.
• Using the old shell. Tutorials that start with the mongo command predate its replacement by mongosh.

Further reading

• Introduction to MongoDB (MongoDB Manual)
• MongoDB CRUD Operations
• Data Modeling
• Aggregation Operations

When should I embed documents vs use references in MongoDB?

Twelve common MongoDB relationships, from user addresses to org charts, each with an embed, reference or hybrid verdict, the document shape and the reason.

#data-modeling#nosql#schema-design