MongoDB در عمق: مدل‌سازی سند تا شاردینگMongoDB In Depth: Document Modelling to Sharding

If your brain is relational — years of thinking in tables, foreign keys and JOIN — your first encounter with MongoDB usually goes one of two ways. Either you think "it's just a JSON store, this is easy" and six months later you are staring at 12 MB documents and 40-second queries; or you decide it isn't serious, rebuild your normalised model verbatim inside MongoDB, and then wonder why it is slower than PostgreSQL.

Both mistakes share a root cause: MongoDB is not a database without a schema; it is a database that moved the schema out of the engine and into your code and your access patterns. That is also exactly what an interviewer is testing — not whether you memorised operator names, but whether you can make decisions about the shape of data.

ACID fundamentals live in tx-acid, distributed-systems theory in distributed-systems-theory, Redis/Cassandra/ClickHouse in nosql-specialized, and Spring Data basics in spring-data-tx; we reference them here rather than repeating them.

1. The document model from zero

The vocabulary

• document: the smallest unit of data — a key/value structure that can nest and contain arrays. Roughly "a row", except this row can hold other tables inside it.
• field: a key/value pair inside a document. A column belongs to the table; a field belongs to the document.
• collection: a container of documents (a table, but with no column definitions up front). database: a container of collections.
• namespace: the full name db.collection; maximum 255 bytes.

The same data, two shapes

In the relational world one order means two tables:

CREATE TABLE orders (
  id          bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  customer_id bigint      NOT NULL,
  status      text        NOT NULL,
  created_at  timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE order_items (
  order_id bigint NOT NULL REFERENCES orders(id),
  sku      text   NOT NULL,
  qty      integer NOT NULL,
  price    numeric(12,2) NOT NULL
);

CREATE TABLE orders (
  id          NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  customer_id NUMBER       NOT NULL,
  status      VARCHAR2(32) NOT NULL,
  created_at  TIMESTAMP WITH TIME ZONE DEFAULT SYSTIMESTAMP NOT NULL
);
CREATE TABLE order_items (
  order_id NUMBER        NOT NULL REFERENCES orders(id),
  sku      VARCHAR2(64)  NOT NULL,
  qty      NUMBER(10)    NOT NULL,
  price    NUMBER(12,2)  NOT NULL
);

In MongoDB the same order is one document:

{
  _id: ObjectId("66f0a1b2c3d4e5f601020304"),
  customerId: ObjectId("66f0a1b2c3d4e5f6010202aa"),
  status: "PAID",
  createdAt: ISODate("2026-08-10T09:14:22.000Z"),
  total: NumberDecimal("1450000.00"),
  items: [
    { sku: "KB-87", qty: 1, price: NumberDecimal("1200000.00") },
    { sku: "MP-01", qty: 2, price: NumberDecimal("125000.00") }
  ]
}

One diagram, two philosophies — یک نمودار، دو فلسفه: Relational splits one concept across tables; the document model keeps it in one place.

flowchart LR
  subgraph Relational["Relational: JOIN at read time"]
    O[(orders row)] --- I1[(order_items row)]
    O --- I2[(order_items row)]
    O --- C[(customers row)]
  end
  subgraph Document["Document: assembled at write time"]
    D["order document<br/>items: [ ... ]<br/>customer: {id, name}"]
  end
  Relational -->|"one read replaces N joins"| Document

The real difference in one sentence: relationally, normalisation is the default and JOIN pays the read cost; in the document model, pre-building the read shape is the default and denormalisation pays the write-and-sync cost. Neither is inherently better; the question is which cost is cheaper in your system.

Do not shrug off one of those rows: MongoDB has no equivalent of FOREIGN KEY ... ON DELETE CASCADE. Delete a referenced document and the referrer keeps a dead id, silently. Integrity moved into your code. If your data graph is full of strict references, you may have picked the wrong tool.

2. BSON, _id and ObjectId

MongoDB stores and transports data as BSON (Binary JSON), which adds three things JSON lacks: real types (it distinguishes int32/int64/double/decimal128 and adds date and binData), length prefixes (fast traversal, skip over unwanted fields), and stable field order.

Limits worth memorising: document size 16 MB · nesting depth 100 levels · at most 64 indexes per collection · at most 32 fields in a compound index · at most one text index per collection. In practice the 16 MB number is a design ceiling, not a technical one: if a document reaches one megabyte, your model is already wrong.

_id and ObjectId

Every document has exactly one _id; if you don't supply one the driver or the server generates an ObjectId. _id always carries an undroppable unique index and is immutable after insert. Its twelve bytes:

| 4 bytes: timestamp (seconds) | 5 bytes: random per process | 3 bytes: counter |

Three practical consequences: insertion time is essentially free ({ $toDate: "$_id" }); sorting by _id is approximately chronological but only to second precision; and an ObjectId is guessable, so if your security depends on unguessable identifiers use a UUIDv4 in binData instead (appsec-owasp).

3. What "schemaless" actually means

Day-one flexibility is year-two chaos unless you contain it. The containment tool is schema validation, inside the database itself:

db.createCollection("orders", {
  validator: { $jsonSchema: {
    bsonType: "object",
    required: ["customerId", "status", "createdAt", "items"],
    properties: {
      customerId: { bsonType: "objectId" },
      status:     { enum: ["NEW", "PAID", "SHIPPED", "CANCELLED"] },
      total:      { bsonType: "decimal" },
      items: { bsonType: "array", minItems: 1, maxItems: 500,
        items: { bsonType: "object", required: ["sku", "qty", "price"] } }
    } } },
  validationLevel: "moderate",
  validationAction: "error"
})

validationLevel has three settings: "strict" (the default) checks everything; "moderate" checks only new documents and existing documents that were already valid — precisely the gradual-migration tool; and "off". validationAction is either "error", which rejects, or "warn", which only logs so you can first measure how much of your data is out of spec. Apply the same options to an existing collection with collMod.

4. CRUD and query operators

db.orders.updateOne({ _id: id },
  { $set: { status: "PAID" }, $currentDate: { paidAt: true } })

// append to an array while bounding its size and order
db.orders.updateOne({ _id: id },
  { $push: { events: { $each: [{ t: new Date(), type: "PAID" }],
                       $sort: { t: -1 }, $slice: 50 } } })

// atomically claim a job in a single round trip
db.jobs.findOneAndUpdate(
  { status: "READY", runAt: { $lte: new Date() } },
  { $set: { status: "RUNNING", lockedAt: new Date() } },
  { sort: { runAt: 1 }, returnDocument: "after" })

db.orders.find({ status: "PAID", createdAt: { $gte: ISODate("2026-08-01") } },
               { _id: 0, status: 1, total: 1, "items.sku": 1 })   // projection
         .sort({ createdAt: -1 }).limit(20)

5. The heart of the chapter: data modelling

This is where a senior interview is won or lost, and every modelling question has one answer: build the model from the access pattern, not from the entities. Relationally you normalise first and write whatever query you need later; normalisation buys you unknown queries. Here it is the reverse. Answer three questions before writing a line of code: which data is always read together? what is the read/write ratio and which side is critical? and does this set have a bound?

one-to-few (small and bounded: a user's addresses, an order's line items) → embed; one read, no $lookup, atomic updates. one-to-many (large but still bounded: a post's comments) → reference from child to parent ({ _id: c1, postId: p1, body: ... }), and if needed keep the few most recent in the parent as a subset. one-to-squillions (unbounded growth: device logs) → always reference from child to parent, because the parent's array would otherwise grow without limit; this is where the bucket pattern or a time series collection enters.

You can draw this on a whiteboard in the interview — می‌توانی این را در مصاحبه روی تخته بکشی: The embed-versus-reference decision, reduced to four questions.

flowchart TD
  A[Data accessed together?] -->|No| R[Reference]
  A -->|Yes| B[Is the child set bounded?]
  B -->|Unbounded growth| R
  B -->|Bounded| C[Document stays well under 16MB?]
  C -->|No| R
  C -->|Yes| D[Child written far more often than parent is read?]
  D -->|Yes| R
  D -->|No| E[Embed]
  R --> F[Need parent fields on read?]
  F -->|Yes, few and stable| G[Extended reference: duplicate a few fields]
  F -->|No| H[Plain ObjectId reference]

Denormalisation: copying with your eyes open

Copying is neither a sin nor a default; it is a trade. Ask three questions first. How often does it change? (a product name inside an order line must never change — the ideal copy; a user's name inside 10,000 comments — an expensive one). What happens if it drifts? ("an old name in a list" is survivable; "wrong stock level" is not). What is the sync path? (a batch job, a change stream, or nothing). Ownerless denormalisation is silent debt, so at minimum make the copy explicit — customer: { _id, name, snapshotAt }.

6. Schema design patterns

The patterns have names, and saying the name earns credit in an interview.

Extended Reference — instead of a $lookup per row, copy a few slow-changing fields next to the id: customer: { _id, name, tier }.

Subset — the document is bloated by a big array but 95% of reads only want the first few elements: keep the hot few inside, the rest in a separate collection, and bound them automatically with $push + $slice.

Computed — instead of recomputing a total on every read, update it on write:

db.customers.updateOne({ _id: cid },
  { $inc: { "stats.orderCount": 1, "stats.lifetimeValue": 1450000 },
    $max: { "stats.lastOrderAt": new Date() } })

Bucket — one document per sensor reading means billions of tiny documents each paying _id and index overhead; instead gather one interval's readings into a bucket:

{ _id: { sensor: "s-42", hour: ISODate("2026-08-13T09:00:00Z") },
  count: 60, sum: 1342.5, min: 20.1, max: 24.8,
  samples: [ { t: 0, v: 22.4 }, { t: 60, v: 22.5 } ] }

// since 5.0 the engine does exactly this itself, with columnar compression:
db.createCollection("readings", {
  timeseries: { timeField: "ts", metaField: "sensor", granularity: "minutes" },
  expireAfterSeconds: 2592000 })

Outlier — 99.9% of posts have under 100 comments but one viral post breaks the embedded model: flag the document with hasExtras: true and put the overflow in a separate collection.

Polymorphic — CreditCard, Wallet and BankTransfer are all "payment methods" sharing 70% of their fields; keep them in one collection with a type discriminator.

Attribute — products have dozens of different specs and the 64-index ceiling forbids one index each; instead of { ram: "16GB", weight: "1.2kg" } write { specs: [ { k: "ram", v: "16GB" } ] } so that one index on { "specs.k": 1, "specs.v": 1 } covers them all.

Schema Versioning — every document carries a version field; code reads all live versions and always writes the newest. It is the expand-contract pattern from cicd-pipelines, without ALTER TABLE.

7. The aggregation pipeline, stage by stage

$match filters with find syntax and uses an index when it is the first stage. $project selects or builds fields; $set/$addFields add without removing the rest. $group aggregates, with _id as the grouping key and null meaning "everything in one group"; accumulators are $sum, $avg, $min, $max, $push, $addToSet. $sort is free when aligned with an index, otherwise a blocking sort. $lookup is a left outer join whose output is an array, and $unwind expands an array into multiple documents. $facet runs sub-pipelines in parallel over the same input (perfect for "results + total count + category counts" in one round trip), $bucket builds histograms, $unionWith is UNION ALL, $setWindowFields is the window-function equivalent, and $out/$merge write output — $merge being the basis of materialized views.

A real example: top ten customers of the last 30 days

SELECT o.customer_id,
       SUM(i.qty * i.price) AS revenue,
       COUNT(DISTINCT o.id)  AS orders
FROM orders o
JOIN order_items i ON i.order_id = o.id
WHERE o.status = 'PAID'
  AND o.created_at >= now() - INTERVAL '30 days'
GROUP BY o.customer_id
ORDER BY revenue DESC
FETCH FIRST 10 ROWS ONLY;

SELECT o.customer_id,
       SUM(i.qty * i.price) AS revenue,
       COUNT(DISTINCT o.id)  AS orders
FROM orders o
JOIN order_items i ON i.order_id = o.id
WHERE o.status = 'PAID'
  AND o.created_at >= SYSTIMESTAMP - INTERVAL '30' DAY
GROUP BY o.customer_id
ORDER BY revenue DESC
FETCH FIRST 10 ROWS ONLY;

And the same thing in MongoDB — note that because the line items are embedded, no join is needed for them at all:

db.orders.aggregate([
  { $match: { status: "PAID",
              createdAt: { $gte: new Date(Date.now() - 30*24*3600*1000) } } },
  { $project: { customerId: 1,
                orderRevenue: { $sum: { $map: {
                  input: "$items", as: "it",
                  in: { $multiply: ["$$it.qty", "$$it.price"] } } } } } },
  { $group: { _id: "$customerId",
              revenue: { $sum: "$orderRevenue" }, orders: { $sum: 1 } } },
  { $sort: { revenue: -1 } },
  { $limit: 10 },
  { $lookup: { from: "customers", localField: "_id",
               foreignField: "_id", as: "customer" } },
  { $unwind: "$customer" },
  { $project: { _id: 0, name: "$customer.name", revenue: 1, orders: 1 } }
])

8. Indexes: where performance lives

db.orders.createIndex({ email: 1 },
  { unique: true, partialFilterExpression: { email: { $type: "string" } } })
db.sessions.createIndex({ lastSeenAt: 1 }, { expireAfterSeconds: 3600 })

The ESR rule

Field order in a compound index is not arbitrary. MongoDB's official guideline is ESR: Equality first, Sort second, Range last. The reason is that an equality predicate narrows the scan to one contiguous, narrow band of the index, and inside that band the following fields are still in order; put a range field before the sort field and the ordering inside the band is destroyed, forcing MongoDB into a blocking sort.

db.orders.find({ tenantId: t, status: "PAID", total: { $gte: 100000 } })
         .sort({ createdAt: -1 })

db.orders.createIndex({ tenantId: 1, status: 1, createdAt: -1, total: 1 })
//                     └──── E ─────────────┘  └── S ───┘    └─ R ─┘

Two companion rules. Prefix: an index on {a,b,c} serves queries on {a}, {a,b} and {a,b,c}, but not {b} or {b,c} — so before creating a new index, check whether an existing one is already a suitable prefix. Direction only matters for multi-field sorts: for sort({ createdAt: -1 }) alone, { createdAt: 1 } is fine because the index can be walked backwards, but for sort({ a: 1, b: -1 }) the index must be exactly {a:1,b:-1} or its full inverse.

Covered queries and explain()

If every field in the filter and the projection lives in the index and _id is excluded from the projection, the document is never read at all:

db.orders.createIndex({ status: 1, createdAt: -1, total: 1 })
db.orders.find({ status: "PAID" }, { _id: 0, createdAt: 1, total: 1 })
         .explain("executionStats")   // verbosity: queryPlanner | executionStats | allPlansExecution

The golden ratio is totalKeysExamined ≈ totalDocsExamined ≈ nReturned. Wherever those three diverge, you have a missing index.

9. Replica sets: staying available

A replica set is a group of mongod processes holding the same data: the primary (the only node accepting writes), secondaries (which read the oplog and replay it), and optionally an arbiter (no data, votes only).

The oplog is a capped collection in the local database recording every change idempotently, so replaying it twice changes nothing. It defaults to 5% of free disk (minimum 990 MB, maximum 50 GB) and is resizable with replSetResizeOplog. The oplog window — how many hours of history fit — decides how far a secondary can fall behind and still catch up without an initial sync, how long a change stream has to resume, and how far back oplog-based backups can recover.

Failover: when heartbeats stop, eligible secondaries hold an election. — وقتی ضربان قلب قطع شود، secondaryهای واجد شرایط انتخابات برگزار می‌کنند.

stateDiagram-v2
  [*] --> Primary
  Primary --> Unreachable: node crashes / network partition
  Unreachable --> Election: no heartbeat for electionTimeoutMillis (10s)
  Election --> NewPrimary: majority of votes to most up-to-date member
  NewPrimary --> Rollback: old node returns with un-replicated writes
  Rollback --> Secondary: writes rolled back to a file, node rejoins
  NewPrimary --> Primary: steady state

Heartbeats go out every 2 seconds, and if none is answered within electionTimeoutMillis (default 10 seconds) an election begins. A replica set has at most 50 members and 7 voting members; the winner needs a majority of votes, which is why the voting count should be odd. Drivers observe the failover and, because retryWrites is on by default, retry a failed write once automatically — your application usually sees a few seconds of latency, not an error.

10. Write concern, read concern and read preference

Together these three tune one thing: how much latency you will pay for durability and freshness.

write concern ("when is a write finished?"): w: 1 means only the primary acknowledged (fastest, but losable in a failover); w: "majority" means a majority of data-bearing voting members did; w: <n> or w: "<tag>" names a count or a tag; and j: true requires the journal to hit disk before acknowledgement.

read concern ("how certain?"): "local" (the default) may still be rolled back; "available" is like local but in a sharded cluster may return orphaned documents; "majority" returns only durable data; "linearizable" is the strongest and most expensive; "snapshot" is for transactions.

read preference ("from which node?"): primary (default), primaryPreferred, secondary, secondaryPreferred, nearest — with tag sets to steer to a data centre and maxStalenessSeconds (minimum 90) to avoid badly lagging nodes.

The popular belief that you should "read from secondaries to offload the primary" is usually wrong: secondaries replay the same write load, so there is no free capacity; their reads can be seconds behind; and in a sharded cluster the default read concern may return orphans. Scaling reads is the job of sharding and caching (caching), not read preference — except for analytics where freshness doesn't matter.

11. Multi-document transactions

Since 4.0 on replica sets and 4.2 on sharded clusters, MongoDB has multi-document ACID transactions. They exist — which is not the same as saying you should always use them.

try (ClientSession session = mongoClient.startSession()) {
    TransactionOptions options = TransactionOptions.builder()
            .readConcern(ReadConcern.SNAPSHOT).writeConcern(WriteConcern.MAJORITY).build();

    session.withTransaction(() -> {   // retries transient errors for you
        accounts.updateOne(session, Filters.eq("_id", "A"), Updates.inc("balance", -100));
        accounts.updateOne(session, Filters.eq("_id", "B"), Updates.inc("balance",  100));
        return null;
    }, options);
}

The facts: they require a replica set (they do not work on a standalone mongod — which is why Testcontainers starts one); the default time limit is 60 seconds (transactionLifetimeLimitSeconds); the official guidance is not to modify more than about 1000 documents in one transaction; two transactions touching the same document produce a WriteConflict that withTransaction retries for you; and holding a snapshot costs WiredTiger memory, so never put a network call inside a transaction.

12. Sharding: scaling out

A sharded cluster: routers, config metadata, and shards that are themselves replica sets. — یک sharded cluster: مسیریاب، متادیتای config، و shardهایی که خودشان replica set هستند.

flowchart TD
  App[Application driver] --> M1[mongos router]
  App --> M2[mongos router]
  M1 --> CFG[(config servers<br/>replica set)]
  M2 --> CFG
  M1 --> S1[Shard A<br/>replica set]
  M1 --> S2[Shard B<br/>replica set]
  M2 --> S3[Shard C<br/>replica set]
  CFG -. chunk map .-> M1
  CFG -. chunk map .-> M2

Each shard is itself a full replica set holding part of the data; the config servers are a replica set holding the data map, and the balancer runs on their primary; mongos is a stateless router and the only thing your application talks to.

Shard key: four criteria

High cardinality (country for a single-country service means effectively one shard) · even frequency (if one customer is 40% of traffic, customerId alone is not enough) · non-monotonic (an ascending key such as a timestamp or an ObjectId sends every new write to the last range and therefore to one hot shard) · and the criterion people forget: the key must appear in most read queries.

The middle ground used most often in practice is a compound key starting with a high-cardinality field and continuing with an ordered one, such as { tenantId: 1, createdAt: 1 }.

Chunks, the balancer and zones

Data is split into chunks (called "ranges" in newer docs) with a default size of 128 MB, and the balancer starts a migration once two shards differ in size for a collection by more than the threshold (three times the range size, i.e. 384 MB). A jumbo chunk is a range that cannot be split because all its documents share the same shard-key value — a direct symptom of low cardinality. With zones (sh.addShardToZone and sh.updateZoneKeyRange) you can require a region's data to live physically on that region's shards: the direct answer to data residency.

If a query carries the shard key, mongos knows exactly where to go (targeted); otherwise it broadcasts to every shard and merges the results (scatter-gather) — meaning your latency equals the slowest shard, and adding shards doesn't help.

Changing the key after you got it wrong: since 4.4, refineCollectionShardKey can append field(s) as a suffix to the existing key (raising cardinality without immediately redistributing); since 5.0, reshardCollection replaces the key entirely; and since 8.0 you can reshard on the same key with the forceRedistribution option to spread data onto newly added shards.

db.adminCommand({ reshardCollection: "app.orders", key: { tenantId: 1, orderId: 1 } })

13. Change streams

A change stream gives you a live, resumable feed of changes for a collection, a database or the whole cluster. Underneath it is the oplog, but with a safe API instead of reading the oplog directly.

const cs = db.orders.watch(
  [ { $match: { operationType: { $in: ["insert", "update"] },
                "fullDocument.status": "PAID" } } ],
  { fullDocument: "updateLookup", resumeAfter: savedToken })

// see the pre-change version (since 6.0) — enable it on the collection first
db.runCommand({ collMod: "orders", changeStreamPreAndPostImages: { enabled: true } })
db.orders.watch([], { fullDocumentBeforeChange: "whenAvailable" })

The resume token lives in each event's _id field and must be persisted after successful processing. An update event carries only the delta (updateDescription) by default; "updateLookup" attaches the full current document, which is not necessarily the version as of the change.

14. Operations: the part that wakes you up

db.setProfilingLevel(1, { slowms: 100, sampleRate: 0.2 })
db.system.profile.find({ millis: { $gt: 200 } }).sort({ ts: -1 }).limit(20)
db.currentOp({ "secs_running": { $gt: 5 }, "op": { $ne: "none" } })

Level 0 is off, 1 records only operations slower than slowms (default 100 ms), 2 records everything (development only); output lands in the capped system.profile collection. The working set is the set of documents and index entries you touch regularly: if it fits in RAM MongoDB is fast, otherwise every query waits on disk. The WiredTiger cache defaults to max(50% × (RAM − 1 GB), 256 MB).

In mongod.conf, set three basics explicitly: storage.wiredTiger.engineConfig.cacheSizeGB, operationProfiling.slowOpThresholdMs, and security.authorization: enabled (plus net.tls.mode: requireTLS).

You have three real backup options: mongodump/mongorestore (fine for small databases and moving data, but slow at scale), volume-level snapshots (the production standard at scale; must include the journal, and must be coordinated on a sharded cluster), and a PITR tool that combines snapshots with the oplog.

mongodump --uri="mongodb://user@rs0/app?replicaSet=rs0" --oplog \
          --archive=/backup/app-$(date +%F).archive --gzip
mongorestore --uri="mongodb://user@rs0/?replicaSet=rs0" \
             --archive=/backup/app-2026-08-13.archive --gzip --oplogReplay

A backup you have never restored is not a backup. --oplog only makes sense on a replica set and is not sufficient for a sharded cluster. More important than the tool is measuring real RTO and RPO: rehearse a full restore on production-sized data once and write down how long it took.

An architectural (not technical) note: the Community edition has shipped under SSPL since 2018, which is not an OSI-approved licence. For internal use it is usually a non-issue, but if you intend to sell MongoDB itself "as a service", have the licence text reviewed by legal.

mongosh cheat sheet

The signs that the working set no longer fits in RAM come from serverStatus: growing bytes read into cache, emergency eviction kicking in, and rising I/O at the OS level. Alongside that, measure total index size with db.collection.stats().indexSizes; the rule of thumb is that the active indexes must fit in memory. Remedies in order of cost: drop unused indexes, shrink documents with the subset pattern, archive cold data, add RAM, and finally shard.

15. Spring Data MongoDB in practice

spring.data.mongodb:
  uri: mongodb://app:secret@mongo-a:27017,mongo-b:27017/shop?replicaSet=rs0&w=majority
  auto-index-creation: false

@Document(collection = "orders")
@CompoundIndex(name = "tenant_created", def = "{'tenantId': 1, 'createdAt': -1}")
public class Order {
    @Id private String id;                         // maps to _id
    private String tenantId;
    @Field("cust") private CustomerRef customer;   // extended reference
    private OrderStatus status;
    private List<OrderItem> items;                 // embedded
    private BigDecimal total;                      // maps to decimal128
    @CreatedDate private Instant createdAt;
    @LastModifiedDate private Instant updatedAt;
    @Version private Long version;                 // optimistic locking
}

public record CustomerRef(String id, String name, String tier) {}
public record OrderItem(String sku, int qty, BigDecimal price) {}

The auditing fields require a @Configuration class annotated with @EnableMongoAuditing.

public interface OrderRepository extends MongoRepository<Order, String> {

    List<Order> findByTenantIdAndStatusOrderByCreatedAtDesc(
            String tenantId, OrderStatus status, Pageable pageable);

    @Aggregation(pipeline = {
        "{ $match: { tenantId: ?0, status: 'PAID' } }",
        "{ $group: { _id: '$customer.id', revenue: { $sum: '$total' } } }",
        "{ $sort: { revenue: -1 } }",
        "{ $limit: ?1 }" })
    List<CustomerRevenue> topCustomers(String tenantId, int limit);
}

MongoTemplate for the precise work:

public void markPaid(String orderId, Instant paidAt) {
    Query q = Query.query(Criteria.where("_id").is(orderId)
                                  .and("status").is(OrderStatus.NEW));
    Update u = new Update()
            .set("status", OrderStatus.PAID).set("paidAt", paidAt)
            .push("events").slice(-50).each(new StatusEvent(OrderStatus.PAID, paidAt));

    if (template.updateFirst(q, u, Order.class).getMatchedCount() == 0) {
        throw new IllegalStateException("order not in NEW state: " + orderId);
    }
}

For pipelines that must be built dynamically, Aggregation.newAggregation(match(...), group(...), sort(...), limit(...)) does what @Aggregation does with a typed API, executed via template.aggregate(agg, "orders", CustomerRevenue.class).

Transactions stay disabled until you declare this bean, and the same MongoDatabaseFactory must be given to both the transaction manager and the MongoTemplate:

@Bean
MongoTransactionManager transactionManager(MongoDatabaseFactory factory) {
    return new MongoTransactionManager(factory);
}

Testing with Testcontainers — MongoDBContainer starts a single-member replica set, so transactions and change streams work in tests too, and @ServiceConnection (Spring Boot 3.1+) sets spring.data.mongodb.uri for you so @DynamicPropertySource is no longer needed (basics in testing):

@SpringBootTest
@Testcontainers
class OrderRepositoryTest {

    @Container @ServiceConnection
    static MongoDBContainer mongo = new MongoDBContainer("mongo:8.0");

    @Autowired OrderRepository orders;

    @Test
    void findsPaidOrdersOfTenant() {
        orders.save(newOrder("t1", OrderStatus.PAID));
        assertThat(orders.findByTenantIdAndStatusOrderByCreatedAtDesc(
                "t1", OrderStatus.PAID, PageRequest.of(0, 10))).hasSize(1);
    }
}

One last note: the old @DBRef issues an extra query per reference and is highly N+1-prone; @DocumentReference is the more flexible replacement. But the senior advice is simpler — model the reference explicitly: store the id and control loading in your service or with $lookup, so the cost is visible in your code rather than hidden behind an annotation.

16. MongoDB or a relational database?

The right question is not "which is better", it is what is my dominant access shape?

In most real systems the answer is "both": a catalogue service on MongoDB and an accounting service on PostgreSQL is entirely sensible, provided the data boundaries are clear (polyglot persistence in ms-data). And keep the big anti-pattern in mind: if your model is ten collections wired together with $lookup and every business operation needs a multi-document transaction, you have built a weaker relational database. The converse holds too: unstructured JSON in a jsonb column queried through a thousand operators usually means you needed a document database.