We closed module 2 with biblioredb in very good shape: seven tables, foreign keys that prevent orphans, management reports that add up. That is the core of the system and it is going to stay that way. But as soon as BiblioRed's management approved the new members' portal, four needs appeared that the relational schema does not accommodate comfortably: readers want to publish reviews, the catalog wants to show covers, synopses and tags for materials that are no longer only books, the team wants to record every search made in the finder, and marketing wants to recommend titles based on what similar readers have read.

Back in lesson 01-02 we already hinted at the decision: that part of the system would go to MongoDB. In this lesson we justify the why properly. We are going to see what "NoSQL" really means —and what it does not mean—, which four characteristics every database in this family shares, how it scales horizontally through partitioning and replication, what price you pay for it, and we will take our first practical steps with MongoDB by creating BiblioRed's reviews collection.

By the end you will know why this movement exists, not just how a query is written in it. And —just as important— you will be able to say when it is not a good idea to use it.

1. Where BiblioRed's relational schema gets stuck
2. What "NoSQL" means and what it does not mean
3. Characteristic 1: flexible schema (schema-on-read)
4. Characteristic 2: aggregate orientation
5. Characteristic 3: horizontal versus vertical scaling
6. Characteristic 4: distribution
7. How it really scales (I): partitioning or sharding
8. How it really scales (II): replication
9. What you pay in exchange
10. First steps with MongoDB: installation and mongosh
11. MongoDB's hierarchy compared with the relational one
12. BSON, JSON and the _id field
13. First operations: insertOne, insertMany, find
14. When NOT to use NoSQL
15. Common mistakes and tips
16. Exercises
17. Conclusion

Before talking about technology, let's look at the real problem. There are three concrete situations.

BiblioRed no longer lends only books. The catalog holds books, DVDs, magazines and audiobooks, and every type of material has metadata of its own:

With the relational model there are three classic ways out, and none of them is pleasant:

1. One wide table with every column. materials would have isbn, issn, director, narrator, duration, pages, codec… and in each row most of them would be NULL. In a magazine row, 70% of the columns are dead weight. The schema stops describing reality and becomes a union of incompatible realities.
2. One table per type. books, dvds, magazines, audiobooks. Clean on paper, but any search query ("everything by Jules Verne") needs a UNION of four tables, and adding a fifth type of material —comics, planned for 2027— means a new table and touching every query.
3. Entity-attribute-value (EAV). An attributes (material_id, key, value) table with value as text. Flexible, yes, but you lose typing, you lose constraints, and a complete record requires pivoting twenty rows. It is the solution most often regretted in the history of database design.

The first version of reviews was: text and a score from 1 to 5. In the first quarter the product team asked for, in this order:

• adding free-form tags written by the reader ("historical fiction", "gift idea");
• allowing readers to vote whether a review was helpful, storing who voted;
• allowing a librarian to reply to a review;
• adding spoiler: yes/no and hiding the text by default when it is one.

In the relational world, each of those changes is an ALTER TABLE or a new table, with its migration, its deployment window and its coordination with the application team. Four schema changes in three months on a table that does not yet have a stable shape.

Every time a member searches the catalog, opens a record or filters by author, the portal wants to log the event. The team's estimates:

Seventeen million rows a year, written continuously, which are almost never read row by row (they are read in aggregate: "most frequent searches of the month"), which need no foreign keys and which lose almost all their value after two years. Putting them in the same transactional database as the loans means growing the indexes, stretching the backups and competing for the cache of a database that has to answer fast at the front desk.

None of the three situations is a failure of the relational model: it is a poor fit. The relational model shines with homogeneous data, heavily related to each other and with strict integrity rules —exactly what loans are—. These three situations are something else.

The name is, honestly, bad. It was born in 2009 as the hashtag of a technical meetup in San Francisco and it stuck. The reading that has ended up prevailing is "not only SQL": not instead of SQL, but in addition to SQL.

What it does mean in practice:

• A set of databases that do not use the relational model of tables, rows and columns as their main structure.
• Systems designed from day one to be distributed across several machines.
• Alternative data models: documents, key-value pairs, column families, graphs.

What it does not mean, and it is worth dismantling this right away:

A useful way of seeing it: NoSQL databases deliberately give up some of the relational model's guarantees in exchange for something concrete —scaling, flexibility or efficiency in one kind of query—. The question you should always ask is not "is it modern?", but "what does this product give up, and is the trade worth it to me?".

It is the difference you notice most on day one.

• Schema-on-write (relational): the schema is defined before writing. The server rejects any data that does not fit. It is the CREATE TABLE of lesson 02-02 and the constraints of 02-06.
• Schema-on-read (document): you write whatever, and interpretation happens on reading. It is the application that knows which fields it expects.

Look at it with BiblioRed's catalog. Two documents from the same collection:

They coexist in the catalog collection with no NULLs, no UNION, no new table. When comics arrive in 2027, you insert documents with "type": "comic" and fields illustrator and volume_number. No ALTER TABLE, no migration, no deployment window.

Now the small print, which matters a great deal:

The schema has not disappeared. It has moved house: from the CREATE TABLE to the application code. And there, nobody checks it automatically.

If one developer writes "duration" in some documents and "duration_min" in others, MongoDB happily accepts both and the error shows up months later, in a report that returns half the data. That is why in lesson 03-03 we will look at schema validation ($jsonSchema), which lets you voluntarily recover part of that safety net.

This concept is the one that really explains NoSQL, and it is underrated because it sounds abstract. Let's take it slowly.

An aggregate is a set of data that the application treats as a unit: it is read together, written together and, normally, deleted together.

At BiblioRed, a review record is an aggregate: when the portal shows a review, it shows at the same time its text, its score, its tags, who wrote it and how many helpful votes it has. It never shows "the tags" on their own.

In the relational model, that aggregate is scattered across several tables because normalization demands it (we will study it formally in module 5). Rebuilding it requires a JOIN:

Three tables, a JOIN and an explosion of rows (one row per tag) that the application has to fold back together in memory. In the document model, the aggregate is the document:

A single read, a single object, zero JOINs. That is the core of the proposition.

And here comes the consequence that almost nobody explains at the start: if the data is read together, it can also be stored together on disk. And if it is together on disk, it can be moved whole to another machine. The aggregate is the natural unit of distribution, and that is why aggregate orientation and horizontal scaling are the same idea seen from two angles.

It is also the natural boundary of atomicity: in MongoDB, writing a complete document is atomic with no need for a transaction. Everything that fits inside the aggregate is updated in one piece. Everything left outside is not.

When a system falls short there are two roads.

• Vertical scaling (scale up): a bigger machine. More CPU, more RAM, faster disks. It is the first thing anyone does and it works surprisingly well for a long time.
• Horizontal scaling (scale out): more machines, each with a part of the work.

The classic relational model scales vertically with ease, and horizontally with difficulty: a JOIN between two tables living on different machines requires moving data over the network, and a transaction touching several machines requires two-phase commit protocols, which are slow and fragile. NoSQL databases eliminate the two problematic operations by design —the server-side JOIN and the general distributed transaction— and in exchange they distribute without friction.

A warning against the exaggeration of sales presentations: BiblioRed has 12,000 members and 17 million events a year. That fits comfortably in a single well-configured PostgreSQL machine. The reason BiblioRed is going to use MongoDB is not volume, it is the heterogeneity of the catalog and the rate of change of the review service. Being honest about the real motive is part of the craft.

The fourth characteristic is a consequence of the third: these systems were designed on the assumption that they are going to live on several machines, not as an extension bolted on afterwards.

That implies three things that are taken for granted in NoSQL and that in a classic relational database are projects:

1. Adding a node is a routine operation, not a migration.
2. A node going down is not the service going down, if there are replicas.
3. Data is placed automatically: the system decides which node each piece of data goes to and rebalances by itself.

The two mechanisms that make this possible are partitioning and replication. They are different, they solve different problems and they are used at the same time. Let's take them in turn.

Partitioning (or sharding) means splitting the data set across several nodes, so that each node stores only a part. Goal: spread out volume and spread out write load.

The key piece is the shard key: the field whose value decides which shard each document lives in.

How an operation works:

• Writing an event for member 15 → the router works out that 15 falls in shard A → it writes only there. The other two shards never even hear about it, and that is why writes spread out.
• Read filtered by member_id: 15 → the router goes straight to shard A. That is a targeted query and it is fast.
• Read without filtering by the key (for example, "events from the last day") → the router has to ask all three shards and merge the results. That is a scatter-gather query, and it is expensive.

Hence the most important practical rule of partitioning:

Choosing the shard key is choosing which queries will be fast. A bad key turns every query into a scatter-gather one and makes the system slower than a single machine.

What characterizes a good shard key:

Two distribution strategies:

• By range: shard A stores member_id 1–4000, shard B 4001–8000. Advantage: range queries go to few shards. Risk: imbalance if the values are not well spread.
• By hash: a hash function is applied to the key and the result decides the shard. Advantage: very even distribution. Drawback: range queries become scatter-gather, because contiguous values end up in different shards.

And a note of realism: BiblioRed is not going to partition anything. Its volumes fit amply on a single node. Partitioning is studied to understand NoSQL's architectural proposition and to recognize when it will be needed, not because it has to be switched on from day one. Switching it on without needing it adds operational complexity in exchange for nothing.

Replicating means keeping complete copies of the same data set on several nodes. Goal: surviving failures and, secondarily, spreading read load.

The dominant model is primary-secondaries. In MongoDB it is called a replica set:

The rules of the game:

1. Every write goes to the primary. There is only one, and that is why there are no write conflicts.
2. The primary records every change in an operation log (the oplog), and the secondaries apply it in the same order. They run a few milliseconds behind.
3. The nodes send each other heartbeats every few seconds. If the primary stops answering, the secondaries elect a new primary by vote and the service carries on. This process is called failover and it usually takes between 5 and 15 seconds.
4. For there to be a majority in the vote you want an odd number of nodes. Three is the minimum sensible configuration.

What BiblioRed gains from this: if the server hosting the reviews shuts down at three in the morning, the portal stops working for a few seconds and then carries on. With a single machine, it stops working until somebody turns up.

And here a nuance appears that is worth planting now, although we will develop it in lesson 03-04: if the application reads from a secondary, it may read slightly stale data. A review Marta Alsina has just published might not appear to Iván Pereda for a few milliseconds. That phenomenon is called eventual consistency, and it is the counterpart of distribution. In 03-04 we will study it alongside the CAP theorem and the contrast between ACID and BASE.

None of these advantages is free. These are the four bills, and you have to look at them before signing.

In module 2 we crossed seven tables in a single query. In a document database, if the information you need is in two collections, you have three options and all three have a cost:

1. Duplicating the data inside the document (the usual choice).
2. Running two queries from the application and combining them in memory.
3. Using $lookup, MongoDB's operation resembling a LEFT JOIN, which exists but is slow and is not meant to be used everywhere (in lesson 03-03 we will see it as an anti-pattern when it is overused).

The whole of module 2 closed by explaining that the database is the last line of defense. In MongoDB that line does not exist: you can store a review with book_id: 9999 without anyone objecting, even though that book does not exist. Responsibility passes entirely to the application.

Look at the review document in section 4: it stores "book_title": "The Map of Time" and "name": "Marta Alsina". That is information that also lives in books and in members. It is duplicated on purpose, so that the review can be rendered without having to fetch anything else.

And that duplication has consequences: if Marta gets married and changes her surname, there are 34 reviews of hers with the old surname. Do they all have to be updated? Sometimes yes (a display name) and sometimes no (the name at the time of the review is a legitimate historical fact). It is a conscious design decision, and we will deal with it thoroughly in 03-03.

Summarized in a table, so it is clear who does what:

The operational conclusion: NoSQL does not remove work, it moves it from the database to the code. If the team is disciplined and code reviews are taken seriously, the deal works out. If not, it works out very badly.

Let's get practical. You need a MongoDB server and its command-line client, mongosh.

It is the cleanest route: it does not clutter the system and it is deleted whole when you are done.

This is the manufacturer's own managed cloud service and it has a free tier that is enough for the course. They give you a connection string and you connect with:

When you go in you will see something like this:

That test> is the prompt: you are in the test database. And here comes the nicest detail about mongosh: it is a complete JavaScript interpreter. You can declare variables, use loops and call functions. It is not a separate language like SQL: they are calls to object methods.

The mental correspondence you need is this one:

A practical detail that surprises people coming from SQL: databases and collections create themselves. There is no CREATE DATABASE and no CREATE TABLE. It is enough to select a database and insert; MongoDB materializes it on the first document written.

bibliored does not appear. That is normal: it will appear after the first insert.

Documents are written looking like JSON, but MongoDB stores them internally in BSON (Binary JSON). The differences matter:

Practical consequence: use the native types. A date stored as the string "2026-03-14" cannot be compared by range or grouped by month reliably; stored as an ISODate it can.

Watch out too for the 16 MB per document limit. It sounds enormous —it is about 8,000 pages of text— but it is the limit that makes it unfeasible, for example, to put a popular book's 40,000 search events inside its document. We will come back to this limit in 03-03, because it is the criterion that governs the decision to embed or reference.

Every document has an _id field that acts as the primary key:

• It is mandatory: if you do not supply it, MongoDB generates it.
• It is unique within the collection, with an automatically created index that cannot be dropped.
• It is immutable: it cannot be modified afterwards.
• It can be of any type: ObjectId, string, number, even a document.

By default it is an ObjectId, a 12-byte identifier generated on the client (not on the server) that contains the creation timestamp, a process identifier and a counter. That makes it unique with no coordination between machines, which is exactly what a distributed system needs —unlike PostgreSQL's SERIAL, which demands a central counter—.

When you have a natural identifier with meaning of its own, use it as the _id: you save yourself an index. In BiblioRed's catalog we will use codes such as "MAT-0331".

At last we create BiblioRed's reviews collection. All the data is fictional.

Read it slowly, because there are three new things compared with an SQL INSERT:

1. We have not created anything beforehand. Neither the bibliored database nor the reviews collection. They exist as of this line.
2. member is a nested document. In SQL that would be two columns or a separate table; here it is an object inside the object.
3. tags is an array. The relational model does not allow multiple values in a cell —first normal form forbids it, and we will see it in 05-02—. The document model does, and that is one of its deepest differences.

Notice that the third document has a field, librarian_reply, that the others do not have. Nobody objected. That is schema-on-read in action: when the product team asked for librarian replies, there was no ALTER TABLE; documents with that field simply started being written.

find is the equivalent of SELECT. It takes a filter document: each field is a condition and they are combined with a logical AND.

That last query deserves a moment's attention. In SQL, to query tags you would need a review_tags table, a JOIN and a DISTINCT. Here it is an equality filter on an array, and MongoDB automatically understands that it has to look inside. It is a perfect example of what aggregate orientation buys you.

The complete query operators ($gt, $in, $regex, projection, sorting, updates with $set and $push, and the aggregation pipeline) we will see in the next lesson, 03-02, alongside the other three NoSQL families.

This section is the most honest one in the lesson and probably the most useful in your career. These are the signs that the right answer is a relational database:

1. The data is heavily related and the queries are unpredictable. If tomorrow somebody might ask for "loans by members of the North branch, of books in Catalan published after 2015, whose author has another book on hold", you want SQL. That is exactly the terrain where the relational model has no rival.
2. You need transactions over several entities as the rule, not the exception. Recording a loan touches loans and copies at the same time and has to be all or nothing. It is a textbook relational case.
3. Integrity is a requirement, not a preference. Money, fines, legal histories, regulated data. If an orphan is unacceptable, you want the server to prevent it, not an if in the code.
4. The volume fits on one machine. Which is almost always. A single PostgreSQL instance on ordinary hardware handles hundreds of gigabytes and thousands of transactions per second without breaking a sweat. If that is your scale, horizontal scaling only brings you complexity.
5. The team has no experience operating distributed systems. A badly operated cluster is less reliable than a well-operated machine. Technology does not make up for a lack of practice.
6. Reporting and analysis are the main use. BI tools, dashboards and analysts speak SQL. Taking the data into a document model only to have to get it back out again is working against yourself.
7. "Because it is what everyone is doing". It is the worst possible motive and, statistically, one of the most frequent.

The default advice, which we will repeat with more arguments in lesson 03-04: start relational and add NoSQL when you have a concrete reason you can write in one sentence. BiblioRed can write it: "the catalog is heterogeneous by material type, the reviews change shape every month and the activity log is a high volume of writes that needs no referential integrity". That is a reason. "We want to modernize" is not.

Mistake 1: believing NoSQL means "schemaless" and designing nothing. The schema always exists; only who polices it changes. Write the expected schema of each collection in the project documentation from day one, even though the server does not require it. In 03-03 you will see how to get the server to police it too, with $jsonSchema.

Mistake 2: migrating the whole relational database to MongoDB "to unify things". It is the decision that has produced the most regret in the last decade. BiblioRed does not move loans or members: that is where the relational model wins. Only what fits badly is moved.

Mistake 3: adopting NoSQL "for performance" without having measured. Many problems blamed on "the relational database being slow" are really a missing index or a badly written query. Before changing technology, measure and optimize what you have (module 6, lesson 03).

Mistake 4: storing dates and numbers as text strings. { date: "14/03/2026" } and { score: "5" } work when inserting and ruin any later comparison, sort or aggregation. Use ISODate(...) and real numbers. It is the most common mistake and the most expensive to fix after the fact.

Mistake 5: choosing the shard key with the first idea that comes to mind. It is the hardest decision in the whole system to reverse. Before choosing it, write down the application's five most frequent queries and check which ones would be targeted and which scatter-gather.

Tip 1: use a natural identifier as the _id when one exists. "MAT-0331" is more readable than an ObjectId in error logs and it saves you an extra index.

Tip 2: name your fields with a convention and stick to it. Choose snake_case or camelCase, write it in the team handbook and do not mix them. With no CREATE TABLE to keep order, the convention is your only defense against duration / duration_min / durationMin in the same collection.

Tip 3: in mongosh you have full JavaScript. To generate test data, a loop is enough:

Tip 4: learn to read the acknowledged: true result. It means the server has confirmed the write. When we look at writeConcern in 03-04, you will understand what level of confirmation lies behind that true and why it can be tuned.

BiblioRed wants to store an audiobook and a magazine in the catalog. Justify in three or four sentences why this fits better in a document collection than in the books table of module 2's relational schema, and then write the two inserts in mongosh against a catalog collection, using a natural _id in the style of "MAT-0801". The audiobook is a version of "The Map of Time" narrated by Àlex Roure, 14 h 20 min long, in MP3 format. The magazine is "Vallmar Cultural", ISSN 2604-1188, issue 42, volume 7, published monthly.

For BiblioRed's activity log (17 million events a year, queried almost always as "activity of one specific member" and occasionally as "most frequent searches of the month"), assess these three shard key candidates and pick one, justifying the decision with the four criteria from section 7:

• (a) event_date
• (b) event_type (possible values: search, record, filter, download)
• (c) member_id

On the reviews collection you created in section 13, write the find queries that answer these three questions, and also say what the approximate SQL equivalent of each would be:

1. All the reviews written by member 14.
2. All the reviews flagged as spoilers.
3. All the reviews from branch 3 about book 412.

Solution 1

Justification. An audiobook and a magazine share only a handful of fields with a book (title, language, publication_year) and differ in everything else: narrator, duration and audio_format versus issn, issue, volume and frequency. In the books table you would have to add seven columns that would be NULL in the vast majority of rows, or create two new tables that would force a UNION in every search query. In a document collection, each material carries only the fields it makes sense for it to carry, and adding the "comic" type in 2027 will require no schema change and no migration.

Notice that insertedIds returns the strings we supplied ourselves, not ObjectIds: when you provide an _id, MongoDB respects it.

Solution 2

Decision: member_id. It meets the four criteria and, above all, the fourth: the usual query ("activity of member 14") becomes a query targeted at a single shard. The monthly frequent-searches query will indeed be scatter-gather, but it is occasional, it runs off peak and it is aggregate by nature, so its cost is acceptable.

An even better improvement would be a composite key { member_id: 1, event_date: 1 }: it distributes by member and, within each member, keeps events ordered by date, which speeds up queries of the type "this member's activity over the last month".

And the realistic reminder: with 17 million documents a year, BiblioRed does not need to partition yet. The exercise is there so you know which key you would choose the day it becomes necessary, not so you switch it on tomorrow.

Solution 3

An important detail about the third one: putting two fields in the filter document is equivalent to AND. There is no explicit $and operator in the normal case; conjunction is the default behavior.

In this lesson we have crossed the border between the course's two worlds:

• BiblioRed's relational schema does not fail, it stops fitting in three concrete cases: a catalog with different metadata per material type, a review service whose shape changes every month and an activity log of 17 million events a year that needs no referential integrity.
• "NoSQL" means not only SQL: databases that do not use the relational model as their main structure and that are born distributed. It does not mean "no query language", nor "no schema", nor "a replacement for relational".
• Flexible schema (schema-on-read): the schema does not disappear, it moves from the server to the application code, gaining agility and losing a safety net.
• Aggregate orientation: the unit of data that is read and written together is stored together. From that come both the absence of JOINs and the ease of distributing.
• Horizontal scaling instead of vertical: more machines rather than a bigger one, with a practically unlimited ceiling and roughly linear cost, in exchange for operational complexity.
• Partitioning: each node stores part of the data; the shard key must have high cardinality, even distribution, no monotonic growth and presence in the frequent queries. Replication: each node stores a complete copy; the primary accepts the writes, the secondaries follow the oplog and elect a new primary if the current one goes down.
• The price: no server-side JOIN, no declarative referential integrity, deliberate data duplication and consistency moved to the application. NoSQL does not remove work: it moves it from the database to the code.
• MongoDB in practice: server → database → collection → document; databases and collections that create themselves; BSON with native types (use ISODate, not strings) and a 16 MB per document limit; the _id, mandatory, unique, immutable and generated on the client as an ObjectId. With insertOne, insertMany and find we have already created and queried the reviews collection, with nested documents, arrays and fields that only some documents have.
• When not to use it: heavily related data with unpredictable queries, routine multi-entity transactions, integrity as a requirement, volumes that fit on one machine, a team with no mileage in distributed systems, analytical workloads… or fashion as the only argument.

In the next lesson, 03-02, Types of NoSQL Databases, we go down into the detail of the four families. We will come back to the landscape we only glimpsed in 01-02, but this time with real operation: complete queries and updates in MongoDB —including the first aggregation pipeline as the equivalent of the GROUP BY from lesson 02-05—, caching and expiration in Redis, wide rows and CQL in Cassandra, and multi-hop traversals in Cypher over Neo4j to solve the "readers like you also read" that BiblioRed's recommendation engine needs.