# MongoDB Aggregation Examples

> Pipeline construction, stage ordering, joins, faceting and materialised views with the native driver. See [SKILL.md](../SKILL.md) for the decisions behind these.

**Core:** See [core.md](core.md). **Queries:** See [queries.md](queries.md). **Indexes:** See [indexes.md](indexes.md). **Advanced:** See [patterns.md](patterns.md).

---

## Pattern 1: Pipeline Construction and Stage Order

### Good Example -- Revenue Report

```typescript
import type { Document, ObjectId } from "mongodb";

const TOP_CUSTOMER_COUNT = 10;

type RevenueByCustomer = {
  _id: ObjectId;
  total: number;
  orderCount: number;
};

async function topCustomers(
  orders: Collection<OrderDoc>,
  tenantId: ObjectId,
  since: Date,
): Promise<RevenueByCustomer[]> {
  return orders
    .aggregate<RevenueByCustomer>([
      // 1. Narrow first. This is the only stage that can use an index.
      { $match: { tenantId, status: "complete", createdAt: { $gte: since } } },
      // 2. Shrink documents before they flow through the expensive stages.
      { $project: { customerId: 1, total: 1 } },
      // 3. Aggregate.
      {
        $group: {
          _id: "$customerId",
          total: { $sum: "$total" },
          orderCount: { $sum: 1 },
        },
      },
      { $sort: { total: -1 } },
      { $limit: TOP_CUSTOMER_COUNT },
    ])
    .toArray();
}

export { topCustomers };
```

**Why good:** `$match` first lets a compound index on `{ tenantId, createdAt }` do the narrowing, `$project` cuts each document to two fields before grouping, and the explicit generic types an output shape that no longer resembles `OrderDoc`

### Bad Example -- Matching After Grouping

```typescript
// BAD
[
  { $group: { _id: "$customerId", total: { $sum: "$total" } } },
  { $match: { status: "complete" } },
];
```

**Why bad:** the group has already read the entire collection, so no index is usable and the work is done before anything is filtered; worse, `status` does not exist in the grouped output, so the match silently returns nothing and the report shows zero rows rather than an error

### Good Example -- Allowing Disk Use on a Large Group

```typescript
const results = await orders
  .aggregate<RevenueByCustomer>(pipeline, { allowDiskUse: true })
  .toArray();
```

**Why good:** each stage is capped at 100 MB of memory, so a group or sort over a large dataset fails without this; spilling to disk is slower but completes

---

## Pattern 2: $lookup (Joins)

### Good Example -- Lookup with a Sub-Pipeline

```typescript
const RECENT_ORDER_LIMIT = 5;

type CustomerWithOrders = {
  _id: ObjectId;
  email: string;
  recentOrders: Array<{ _id: ObjectId; total: number; createdAt: Date }>;
};

const results = await customers
  .aggregate<CustomerWithOrders>([
    { $match: { tenantId } },
    {
      $lookup: {
        from: "orders",
        localField: "_id",
        foreignField: "customerId", // MUST be indexed
        as: "recentOrders",
        pipeline: [
          { $match: { status: "complete" } },
          { $sort: { createdAt: -1 } },
          { $limit: RECENT_ORDER_LIMIT },
          { $project: { total: 1, createdAt: 1 } },
        ],
      },
    },
  ])
  .toArray();
```

**Why good:** the sub-pipeline filters, sorts, limits and projects inside the lookup, so each customer carries five small documents instead of every order they have ever placed

### Bad Example -- Unbounded Lookup on an Unindexed Field

```typescript
// BAD
{
  $lookup: {
    from: "orders",
    localField: "_id",
    foreignField: "customerId", // no index
    as: "orders",               // every order, every field
  },
}
```

**Why bad:** without an index on `customerId` the lookup scans the orders collection once per input customer, so 1,000 customers means 1,000 scans; embedding every order in full can also push a result document past the 16 MB limit, at which point the pipeline fails outright

**Before using `$lookup` at all:** if these two collections are always read together, the data may belong in one document. A join you perform on every read is a modelling decision to revisit, not just a query to tune.

---

## Pattern 3: $facet for Several Answers in One Pass

### Good Example -- Results and Metadata Together

```typescript
const FACET_PAGE_SIZE = 20;

type SearchResult = {
  items: Array<WithId<ProductDoc>>;
  totalCount: Array<{ count: number }>;
  byCategory: Array<{ _id: string; count: number }>;
};

const [result] = await products
  .aggregate<SearchResult>([
    { $match: filter }, // runs once, shared by every facet below
    {
      $facet: {
        items: [{ $sort: { score: -1 } }, { $limit: FACET_PAGE_SIZE }],
        totalCount: [{ $count: "count" }],
        byCategory: [{ $group: { _id: "$category", count: { $sum: 1 } } }],
      },
    },
  ])
  .toArray();

const total = result.totalCount.at(0)?.count ?? 0;
```

**Why good:** one round trip and one shared `$match` instead of three queries repeating the same filter, so the counts cannot disagree with the page the way three separate queries can when data changes between them

**Note the shapes:** `$count` yields an array that is empty when nothing matched, which is why the total is read with `.at(0)?.count ?? 0` rather than indexed directly.

---

## Pattern 4: Date Grouping

### Good Example -- Daily Totals

```typescript
type DailyTotal = { _id: string; total: number };

const daily = await orders
  .aggregate<DailyTotal>([
    { $match: { tenantId, createdAt: { $gte: since } } },
    {
      $group: {
        // $dateToString groups in a named timezone, so "day" means the
        // user's day rather than the server's.
        _id: {
          $dateToString: {
            format: "%Y-%m-%d",
            date: "$createdAt",
            timezone: reportTimezone,
          },
        },
        total: { $sum: "$total" },
      },
    },
    { $sort: { _id: 1 } },
  ])
  .toArray();
```

**Why good:** the timezone is explicit, so a report does not silently shift by a day for users outside UTC, and sorting the formatted `YYYY-MM-DD` key sorts chronologically

---

## Pattern 5: $merge for Materialised Views

### Good Example -- Pre-Computing an Expensive Report

```typescript
// Runs on a schedule; readers query daily_revenue directly and pay nothing.
await orders
  .aggregate([
    { $match: { createdAt: { $gte: since } } },
    {
      $group: {
        _id: {
          tenantId: "$tenantId",
          day: { $dateToString: { format: "%Y-%m-%d", date: "$createdAt" } },
        },
        total: { $sum: "$total" },
      },
    },
    {
      $merge: {
        into: "daily_revenue",
        on: "_id",
        whenMatched: "replace",
        whenNotMatched: "insert",
      },
    },
  ])
  .toArray(); // the pipeline only runs when the cursor is consumed
```

**Why good:** `$merge` updates the target incrementally rather than replacing it, so readers never see an empty collection mid-refresh, and the expensive aggregation is paid once per schedule instead of once per reader

**The `toArray()` is load-bearing:** `aggregate()` returns a lazy cursor, so a pipeline ending in `$merge` writes nothing at all until the cursor is consumed.

---

## Pattern 6: Typing Aggregation Output

### Good Example -- Declaring the Output Shape

```typescript
type StatusBreakdown = { _id: OrderStatus; count: number };

const breakdown = await orders
  .aggregate<StatusBreakdown>([
    { $match: { tenantId } },
    { $group: { _id: "$status", count: { $sum: 1 } } },
  ])
  .toArray();
```

**Why good:** without the generic the cursor is typed as `Document`, so every field access is untyped and a renamed group key stays silent until it reaches a consumer

### Bad Example -- Reusing the Collection Type

```typescript
// BAD: the pipeline output is nothing like OrderDoc
const breakdown = await orders.aggregate<OrderDoc>(groupPipeline).toArray();
breakdown[0].total; // typed as number, actually undefined
```

**Why bad:** the type claims fields the grouped output never had, so reads are `undefined` with no compile error -- the exact failure the generic exists to prevent

**Aggregation output is not validated either.** The generic describes what the pipeline is expected to produce; nothing checks that it did.

---

## Performance Notes

| Concern                    | What to do                                                                        |
| -------------------------- | --------------------------------------------------------------------------------- |
| Index usage                | Only a leading `$match` (and a leading `$sort`) can use one. Put `$match` first.  |
| Document size mid-pipeline | `$project` or `$unset` early — every later stage carries whatever you left in.    |
| Memory                     | 100 MB per stage. Large `$group` or `$sort` needs `allowDiskUse: true`.           |
| Verifying a plan           | `aggregate(pipeline, { explain: true })` — same reasoning as `explain` on a find. |
| `$lookup` cost             | Index the `foreignField`, always. It runs per input document.                     |
| Repeated expensive reports | `$merge` into a collection on a schedule; read from that.                         |
| Result size                | Stream with `for await` rather than `toArray()` when the output is unbounded.     |

# MongoDB Core Examples

> Client lifecycle, typed collections, CRUD and the result shapes each operation returns, and error handling. See [SKILL.md](../SKILL.md) for the decisions behind these.

**Query patterns:** See [queries.md](queries.md). **Aggregation:** See [aggregation.md](aggregation.md). **Indexes:** See [indexes.md](indexes.md). **Advanced:** See [patterns.md](patterns.md).

---

## Pattern 1: Client and Pool Lifecycle

### Good Example -- One Client per Process

```typescript
import { MongoClient, ServerApiVersion } from "mongodb";
import type { Db } from "mongodb";

const POOL_SIZE_MAX = 20;
const POOL_SIZE_MIN = 2;
const SERVER_SELECTION_TIMEOUT_MS = 5_000;
const MAX_IDLE_TIME_MS = 60_000;

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} environment variable is required`);
  return value;
}

const client = new MongoClient(requireEnv("MONGODB_URI"), {
  maxPoolSize: POOL_SIZE_MAX,
  minPoolSize: POOL_SIZE_MIN,
  serverSelectionTimeoutMS: SERVER_SELECTION_TIMEOUT_MS,
  maxIdleTimeMS: MAX_IDLE_TIME_MS,
  retryWrites: true,
  retryReads: true,
  serverApi: {
    version: ServerApiVersion.v1,
    strict: true,
    deprecationErrors: true,
  },
});

let database: Db | undefined;

async function connectDatabase(): Promise<Db> {
  if (database) return database;

  // Operations auto-connect, so this call is optional. It exists to turn bad
  // credentials and DNS failures into a startup error instead of a runtime one.
  await client.connect();
  database = client.db(requireEnv("MONGODB_DB"));
  return database;
}

export { client, connectDatabase };
```

**Why good:** one client and one pool for the whole process, every numeric option is a named constant, the Stable API pins server behaviour across upgrades, `strict: true` rejects commands outside the versioned API rather than letting them break silently later

### Good Example -- Graceful Shutdown

```typescript
const SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM"] as const;

function registerShutdown(): void {
  for (const signal of SHUTDOWN_SIGNALS) {
    process.once(signal, async () => {
      // Waits for checked-out connections to return before closing the pool.
      await client.close();
      process.exit(0);
    });
  }
}

export { registerShutdown };
```

**Why good:** `close()` drains in-flight operations rather than severing them, and `once` avoids stacking a second handler if the signal repeats

### Bad Example -- A Client per Request

```typescript
// BAD: a new pool on every call
export async function getUser(id: string) {
  const client = new MongoClient(process.env.MONGODB_URI!);
  await client.connect();
  const user = await client.db("app").collection("users").findOne({ _id: id });
  await client.close();
  return user;
}
```

**Why bad:** each `MongoClient` opens its own pool, so 100 concurrent requests open 100 pools and the server hits its connection limit; the TLS and auth handshake is also paid per request, adding latency that profiling attributes to the query rather than to the connection

### Good Example -- Serverless Client Reuse

```typescript
// Serverless runtimes freeze and thaw the same process, so a client cached
// outside the handler survives between invocations and its pool is reused.
const SERVERLESS_POOL_SIZE = 5;

let cached: MongoClient | undefined;

async function getClient(): Promise<MongoClient> {
  if (cached) return cached;

  cached = new MongoClient(requireEnv("MONGODB_URI"), {
    maxPoolSize: SERVERLESS_POOL_SIZE,
    minPoolSize: 0,
    maxIdleTimeMS: MAX_IDLE_TIME_MS,
  });
  await cached.connect();
  return cached;
}

export { getClient };
```

**Why good:** module scope outlives the handler so warm invocations skip the handshake entirely, a small pool keeps total connections bounded when the platform scales to many instances, and `minPoolSize: 0` lets idle instances release sockets instead of holding them

**Why not `client.close()` here:** closing at the end of a handler discards the pool the next invocation would have reused, which turns every request back into a cold connect.

---

## Pattern 2: Typed Collections

### Good Example -- Document Types and the Driver's Helpers

```typescript
import type {
  Collection,
  ObjectId,
  OptionalUnlessRequiredId,
  WithId,
} from "mongodb";

type UserDoc = {
  _id: ObjectId;
  email: string;
  displayName: string;
  roles: string[];
  createdAt: Date;
};

function usersCollection(db: Db): Collection<UserDoc> {
  return db.collection<UserDoc>("users");
}

// Reads carry _id: WithId<UserDoc> is UserDoc with _id guaranteed present.
async function findByEmail(
  db: Db,
  email: string,
): Promise<WithId<UserDoc> | null> {
  return usersCollection(db).findOne({ email });
}

// Inserts may omit _id and let the server generate one. That is what
// OptionalUnlessRequiredId expresses, and insertOne accepts it directly.
async function createUser(
  db: Db,
  input: OptionalUnlessRequiredId<UserDoc>,
): Promise<ObjectId> {
  const { insertedId } = await usersCollection(db).insertOne(input);
  return insertedId;
}

export { createUser, findByEmail, usersCollection };
```

**Why good:** the generic checks filters, updates and projections against `UserDoc` so a misspelled field is a compile error rather than a query matching nothing, and the two helpers express the real difference between a document you read and one you are about to insert

### Good Example -- Typed Projections

```typescript
type UserSummary = { email: string; displayName: string };

// The projection changes the result shape, so the generic on project()
// re-types the cursor to match what actually comes back.
async function listSummaries(db: Db): Promise<UserSummary[]> {
  return usersCollection(db)
    .find({})
    .project<UserSummary>({ email: 1, displayName: 1, _id: 0 })
    .toArray();
}

export { listSummaries };
```

**Why good:** without the generic the results are still typed as full `UserDoc`, so code reads `createdAt` off an object that never contained it and gets `undefined` at runtime with no type error

### Bad Example -- Trusting the Generic as Validation

```typescript
// BAD: treating a compile-time type as a runtime guarantee
const user = await usersCollection(db).findOne({ _id: id });
sendEmail(user!.email.toLowerCase()); // throws if email is missing or not a string
```

**Why bad:** the driver never validates documents against the generic, so a record written by an older schema version, a migration, or another service can be missing `email` entirely; the type says otherwise and the failure is a runtime `TypeError`

### Good Example -- Validating at the Trust Boundary

```typescript
function toUserSummary(doc: WithId<UserDoc>): UserSummary {
  if (typeof doc.email !== "string" || typeof doc.displayName !== "string") {
    throw new Error(`User ${doc._id.toHexString()} is missing required fields`);
  }
  return { email: doc.email, displayName: doc.displayName };
}

export { toUserSummary };
```

**Why good:** the check runs once where documents enter application code, so downstream consumers get a type that has actually been verified, and a malformed record names itself in the error instead of surfacing as `undefined` three call frames away

---

## Pattern 3: CRUD and Result Shapes

### Good Example -- Insert

```typescript
const insertResult = await users.insertOne({
  email: "a@example.com",
  displayName: "A",
  roles: [],
  createdAt: new Date(),
});
// { acknowledged: true, insertedId: ObjectId(...) }

const manyResult = await users.insertMany(docs, { ordered: false });
// { acknowledged: true, insertedCount: n, insertedIds: { 0: ObjectId(...) } }
```

**Why good:** `ordered: false` lets the remaining documents insert when one fails, instead of stopping at the first error -- the right default for bulk imports where partial progress is useful

### Good Example -- Update, and Reading the Counts Correctly

```typescript
const result = await users.updateOne({ _id: id }, { $set: { displayName } });

if (result.matchedCount === 0) {
  throw new NotFoundError(`No user with id ${id.toHexString()}`);
}
// matchedCount 1 with modifiedCount 0 means the value was already correct.
// That is a successful update, not a missing document.
```

**Why good:** the not-found check uses `matchedCount`, which is the count that actually answers it, so re-submitting an unchanged form does not produce a spurious 404

### Good Example -- Returning the Updated Document

```typescript
// The findOneAnd* family is the only one that returns a document.
const updated = await users.findOneAndUpdate(
  { _id: id },
  { $set: { displayName }, $currentDate: { updatedAt: true } },
  { returnDocument: "after" },
);

if (!updated) throw new NotFoundError(`No user with id ${id.toHexString()}`);
```

**Why good:** one round trip instead of an update followed by a read, `returnDocument: "after"` returns the new state rather than the default pre-update state, and `$currentDate` timestamps from the server clock so it does not drift between application hosts

### Good Example -- Upsert

```typescript
const result = await counters.updateOne(
  { name: "signups" },
  { $inc: { value: 1 }, $setOnInsert: { createdAt: new Date() } },
  { upsert: true },
);

const wasCreated = result.upsertedCount === 1;
```

**Why good:** `$setOnInsert` applies only when the document is created, so `createdAt` is not overwritten on subsequent increments, and `upsertedCount` distinguishes creation from update without a second query

### Bad Example -- Expecting a Document Back

```typescript
// BAD
const user = await users.insertOne(doc);
console.log(user.email); // undefined
const updated = await users.updateOne(filter, update);
return updated.displayName; // undefined
```

**Why bad:** both return acknowledgements, so these reads are `undefined` rather than errors; the value flows onward and fails at whatever finally uses it, which is usually a serializer or a template far from the query

### Good Example -- Delete

```typescript
const { deletedCount } = await users.deleteOne({ _id: id });
if (deletedCount === 0) throw new NotFoundError(`No user with id ${id}`);

const { deletedCount: purged } = await sessions.deleteMany({
  expiresAt: { $lt: new Date() },
});
```

---

## Pattern 4: Error Handling

### Good Example -- Duplicate Key as an Expected Outcome

```typescript
import { MongoServerError } from "mongodb";

const DUPLICATE_KEY_CODE = 11000;

async function registerUser(db: Db, input: OptionalUnlessRequiredId<UserDoc>) {
  try {
    return await usersCollection(db).insertOne(input);
  } catch (error) {
    if (
      error instanceof MongoServerError &&
      error.code === DUPLICATE_KEY_CODE
    ) {
      throw new ConflictError(`Email ${input.email} is already registered`);
    }
    throw error;
  }
}

export { registerUser };
```

**Why good:** two concurrent registrations are a race the unique index is there to settle, so the duplicate is an expected result to translate rather than a crash, and unrecognised errors rethrow instead of being swallowed

### Good Example -- Distinguishing Connectivity from Query Errors

```typescript
import { MongoServerSelectionError } from "mongodb";

try {
  await connectDatabase();
} catch (error) {
  if (error instanceof MongoServerSelectionError) {
    // No reachable server within serverSelectionTimeoutMS: wrong URI, network,
    // firewall, or an IP not on the cluster's allow list.
    throw new Error(
      "Database unreachable — check MONGODB_URI and network access",
    );
  }
  throw error;
}
```

**Why good:** server selection failures are infrastructure problems with completely different remedies from query errors, and naming them stops an operator debugging a query that was never sent

### Bad Example -- Catching Everything

```typescript
// BAD
try {
  await users.insertOne(doc);
} catch {
  return null; // duplicate key, validation failure and network partition, indistinguishable
}
```

**Why bad:** unrelated failures collapse into one silent `null`, so a network partition looks exactly like a duplicate email and the caller cannot act correctly on either

# MongoDB Index Examples

> Index types, compound key ordering, and verifying with `explain` using the native driver. See [SKILL.md](../SKILL.md) for the decisions behind these.

**Core:** See [core.md](core.md). **Queries:** See [queries.md](queries.md). **Aggregation:** See [aggregation.md](aggregation.md). **Advanced:** See [patterns.md](patterns.md).

---

## Pattern 1: Creating Indexes

### Good Example -- Declared Once, Applied Deliberately

```typescript
import type { Collection, IndexDescription } from "mongodb";

const ORDER_INDEXES: IndexDescription[] = [
  { key: { tenantId: 1, createdAt: -1 }, name: "tenant_created" },
  { key: { customerId: 1 }, name: "customer" },
  { key: { reference: 1 }, name: "reference_unique", unique: true },
];

// Called from a migration or a controlled startup step — never a request path.
async function ensureOrderIndexes(orders: Collection<OrderDoc>): Promise<void> {
  await orders.createIndexes(ORDER_INDEXES);
}

export { ensureOrderIndexes, ORDER_INDEXES };
```

**Why good:** the full index set is one reviewable list rather than scattered calls, explicit names make `explain` output and drop operations legible, and `createIndexes` is idempotent so re-running it is safe

### Bad Example -- Creating Indexes in a Request Path

```typescript
// BAD
export async function listOrders(filter: Filter<OrderDoc>) {
  await orders.createIndex({ tenantId: 1 }); // every request
  return orders.find(filter).toArray();
}
```

**Why bad:** the call runs on every request, and the first build on a large collection contends with live traffic; a schema change that alters the index then conflicts with the existing one and starts throwing on a path that used to work

---

## Pattern 2: Compound Indexes and the ESR Rule

Order compound keys by how the query uses them: **E**quality first, then **S**ort, then **R**ange.

### Good Example -- ESR Applied

```typescript
// Query:
//   find({ tenantId, status: { $in: [...] } }).sort({ createdAt: -1 })
//        equality              range                 sort
await orders.createIndex(
  { tenantId: 1, createdAt: -1, status: 1 }, // E, S, R
  { name: "tenant_created_status" },
);
```

**Why good:** the equality field seeks to one section of the index, the sort field is then already in order so no in-memory sort is needed, and the range field filters what remains

### Bad Example -- Range Before Sort

```typescript
// BAD: R before S
await orders.createIndex({ tenantId: 1, status: 1, createdAt: -1 });
```

**Why bad:** a range on `status` leaves the index scattered across many ranges, so `createdAt` is no longer traversed in order and the server sorts in memory — the index exists, is used, and still does not remove the sort, which is why this looks fine in `explain` until you read the sort stage

### Good Example -- Sort Direction on Compound Keys

```typescript
// Serves sort({ tenantId: 1, createdAt: -1 }) and its exact inverse
// sort({ tenantId: -1, createdAt: 1 }) — a mixed sort is not covered.
await orders.createIndex({ tenantId: 1, createdAt: -1 });
```

**Why good:** an index can be walked forwards or backwards, so one index serves both a sort and its complete reversal, and knowing that avoids creating a second index that adds write cost for nothing

---

## Pattern 3: Unique and Partial Indexes

### Good Example -- Conditional Uniqueness

```typescript
// Enforce unique email among active users only, so soft-deleted rows
// do not block a re-registration.
await users.createIndex(
  { email: 1 },
  {
    name: "email_unique_active",
    unique: true,
    partialFilterExpression: { deletedAt: { $exists: false } },
  },
);
```

**Why good:** the constraint matches the rule the application actually has, and the partial index is smaller and cheaper to maintain than one covering every document

### Good Example -- Indexing a Sparse Field

```typescript
// Only some orders have an external reference; index only those.
await orders.createIndex(
  { externalRef: 1 },
  {
    name: "external_ref",
    partialFilterExpression: { externalRef: { $exists: true } },
  },
);
```

**Why good:** documents without the field are absent from the index entirely, keeping it small

**A partial index is only used when the query provably matches its filter.** A query without `externalRef: { $exists: true }` (or a condition implying it) falls back to a collection scan, silently.

---

## Pattern 4: TTL Indexes

### Good Example -- Expiring Sessions

```typescript
const SESSION_TTL_SECONDS = 60 * 60 * 24 * 7;

// The indexed field MUST hold a BSON Date. A number or an ISO string
// is ignored and nothing is ever deleted.
await sessions.createIndex(
  { expiresAt: 1 },
  { name: "session_ttl", expireAfterSeconds: SESSION_TTL_SECONDS },
);
```

**Why good:** expiry is enforced by the server rather than a cleanup job that can stop running, and the constant states the retention window in one place

### Good Example -- Per-Document Expiry

```typescript
// expireAfterSeconds: 0 deletes each document at the time its own field holds,
// which lets different documents expire on different schedules.
await tokens.createIndex(
  { expiresAt: 1 },
  { name: "token_ttl", expireAfterSeconds: 0 },
);

await tokens.insertOne({ value, expiresAt: new Date(Date.now() + ttlMs) });
```

**Why good:** one index serves many retention policies, so a short-lived token and a long-lived one coexist without a second index

**Deletion is not immediate.** The background task runs roughly every minute, so expired documents stay readable for a short window. Filter on `expiresAt` in queries where that matters rather than trusting the sweep.

---

## Pattern 5: Text Indexes

### Good Example -- Full-Text Search

```typescript
const TITLE_WEIGHT = 10;
const BODY_WEIGHT = 1;
const SEARCH_RESULT_LIMIT = 20;

await articles.createIndex(
  { title: "text", body: "text" },
  { name: "article_text", weights: { title: TITLE_WEIGHT, body: BODY_WEIGHT } },
);

type ScoredArticle = WithId<ArticleDoc> & { score: number };

const results = await articles
  .find({ $text: { $search: query } })
  .project<ScoredArticle>({ score: { $meta: "textScore" }, title: 1, body: 1 })
  .sort({ score: { $meta: "textScore" } })
  .limit(SEARCH_RESULT_LIMIT)
  .toArray();
```

**Why good:** weighting ranks a title match above a body match, and the score is both projected and sorted on, which are two separate steps — sorting without projecting it produces an error

**One text index per collection.** Adding a second requires dropping the first, so the field list has to be decided as a whole rather than extended later.

---

## Pattern 6: Geospatial Indexes

### Good Example -- Nearby Search

```typescript
const SEARCH_RADIUS_METRES = 5_000;
const NEARBY_LIMIT = 20;

// Coordinates are [longitude, latitude] — that order, always.
await venues.createIndex({ location: "2dsphere" }, { name: "venue_location" });

const nearby = await venues
  .find({
    location: {
      $near: {
        $geometry: { type: "Point", coordinates: [longitude, latitude] },
        $maxDistance: SEARCH_RADIUS_METRES,
      },
    },
  })
  .limit(NEARBY_LIMIT)
  .toArray();
```

**Why good:** `$near` returns results already ordered nearest-first so no sort stage is needed, and `$maxDistance` in metres bounds the scan

**The coordinate order is the usual defect here:** GeoJSON is `[longitude, latitude]` while most APIs and every map UI say "lat, lng". Reversed coordinates produce plausible-looking results in the wrong hemisphere rather than an error.

---

## Pattern 7: Verifying with explain

### Good Example -- Confirming the Index Is Used

```typescript
const plan = await orders
  .find({ tenantId, status: "complete" })
  .sort({ createdAt: -1 })
  .explain("executionStats");
```

Read three things from the output:

| Field                                             | Want           | A problem when                                                |
| ------------------------------------------------- | -------------- | ------------------------------------------------------------- |
| `winningPlan.stage`                               | `IXSCAN`       | `COLLSCAN` — no index is being used at all                    |
| `executionStats.totalDocsExamined` vs `nReturned` | Close together | Examined ≫ returned — the index narrows poorly                |
| A `SORT` stage in the plan                        | Absent         | Present — the sort is happening in memory, not from the index |

### Good Example -- Finding Unused Indexes

```typescript
// Every index costs write throughput and storage. One never read is pure cost.
const usage = await orders.aggregate([{ $indexStats: {} }]).toArray();
```

**Why good:** `accesses.ops` per index turns index cleanup into evidence rather than guesswork — but read it only from a server that has been up long enough to be representative, since the counters reset on restart

### Bad Example -- Assuming the Index Works

```typescript
// BAD
await orders.createIndex({ tenantId: 1, status: 1 });
// ...ship it, and find out at scale
```

**Why bad:** an unindexed or badly ordered query returns correct results at every size, so nothing fails in review or in tests — the defect only appears when the collection is large, which is exactly when it is hardest to fix

---

## Index Rules of Thumb

- Index every field you filter or sort on in a query that runs often; leave the rest unindexed.
- Prefer one well-ordered compound index over several single-field ones — the server generally uses one index per query.
- Do not index a low-cardinality field alone (a two-value status), but it can earn its place as a later key in a compound index.
- Every index slows writes and consumes storage. An index with no reads is pure cost.
- Build indexes before a collection grows, not after it has become a problem.
- `explain` before and after. An index you did not verify is a hypothesis.

# MongoDB Advanced Patterns

> Transactions, bulk writes, change streams, schema evolution and serverless usage with the native driver. See [SKILL.md](../SKILL.md) for the decisions behind these.

**Core:** See [core.md](core.md). **Queries:** See [queries.md](queries.md). **Aggregation:** See [aggregation.md](aggregation.md). **Indexes:** See [indexes.md](indexes.md).

---

## Pattern 1: Transactions

### Good Example -- Transfer with a Session

```typescript
import type { ClientSession, MongoClient, ObjectId } from "mongodb";

async function transfer(
  client: MongoClient,
  from: ObjectId,
  to: ObjectId,
  amount: number,
): Promise<void> {
  const session = client.startSession();

  try {
    await session.withTransaction(
      async () => {
        const accounts = client.db(DB_NAME).collection<AccountDoc>("accounts");

        const debited = await accounts.updateOne(
          { _id: from, balance: { $gte: amount } }, // the guard is in the filter
          { $inc: { balance: -amount } },
          { session },
        );

        // Throwing aborts the transaction: the credit below never happens,
        // and the debit above is rolled back.
        if (debited.matchedCount === 0) {
          throw new InsufficientFundsError(from);
        }

        await accounts.updateOne(
          { _id: to },
          { $inc: { balance: amount } },
          { session },
        );
      },
      {
        readConcern: { level: "snapshot" },
        writeConcern: { w: "majority" },
      },
    );
  } finally {
    await session.endSession();
  }
}

export { transfer };
```

**Why good:** the balance check lives in the filter so it is evaluated atomically with the write rather than in a read-then-write race, `withTransaction` commits on return and aborts on throw, `w: "majority"` means a committed transfer survives a failover, and the `finally` releases the session on every path

### Bad Example -- A Missing Session

```typescript
// BAD
await session.withTransaction(async () => {
  await accounts.updateOne(
    { _id: from },
    { $inc: { balance: -amount } },
    { session },
  );
  await accounts.updateOne({ _id: to }, { $inc: { balance: amount } }); // no session
});
```

**Why bad:** the credit runs outside the transaction and commits on its own, so if the transaction aborts the debit is rolled back and the credit is not — money is created, no error is raised, and the two accounts disagree

### Bad Example -- Side Effects Inside the Callback

```typescript
// BAD
await session.withTransaction(async () => {
  await orders.insertOne(order, { session });
  await sendConfirmationEmail(order); // not transactional, and retried
});
```

**Why bad:** the driver re-runs the callback on transient errors, so a retry sends a second email for one order; nothing outside the database can be rolled back, so it must not be inside the callback. Record the intent in the transaction and act on it after the commit.

### Good Example -- Parallel Work Is Not Allowed on One Session

```typescript
// BAD: a session is single-threaded
await Promise.all([
  accounts.updateOne(a, updateA, { session }),
  accounts.updateOne(b, updateB, { session }),
]);

// GOOD: sequential within the transaction
await accounts.updateOne(a, updateA, { session });
await accounts.updateOne(b, updateB, { session });
```

**Why bad:** operations on one session must be ordered; issuing them concurrently produces errors that appear intermittently under load and not at all in a test

### Good Example -- Not Using a Transaction

```typescript
// A single-document write is already atomic. A transaction around it
// adds coordination cost and buys nothing.
await accounts.updateOne(
  { _id: id, balance: { $gte: amount } },
  { $inc: { balance: -amount }, $push: { history: entry } },
);
```

**Why good:** the guard, the decrement and the history append apply as one atomic document update, which is both cheaper than a transaction and available on a standalone server

**Transactions require a replica set or sharded cluster.** A standalone server rejects them, which is how a transaction passes in staging and fails on a single-node development machine.

---

## Pattern 2: Bulk Writes

### Good Example -- Batched Mixed Operations

```typescript
import type { AnyBulkWriteOperation } from "mongodb";

const BULK_BATCH_SIZE = 1_000;

async function syncProducts(
  products: Collection<ProductDoc>,
  incoming: ProductInput[],
): Promise<number> {
  let modified = 0;

  for (let start = 0; start < incoming.length; start += BULK_BATCH_SIZE) {
    const batch = incoming.slice(start, start + BULK_BATCH_SIZE);

    const operations: AnyBulkWriteOperation<ProductDoc>[] = batch.map(
      (item) => ({
        updateOne: {
          filter: { sku: item.sku },
          update: { $set: item, $setOnInsert: { createdAt: new Date() } },
          upsert: true,
        },
      }),
    );

    // ordered: false lets the server apply operations in parallel and keep
    // going past a failure, rather than stopping at the first one.
    const result = await products.bulkWrite(operations, { ordered: false });
    modified += result.modifiedCount + result.upsertedCount;
  }

  return modified;
}

export { syncProducts };
```

**Why good:** one round trip per thousand documents instead of one per document, explicit batching keeps a single request from growing past the server's limits, and `ordered: false` means one bad record does not abandon the rest of the batch

### Bad Example -- A Round Trip per Document

```typescript
// BAD
for (const item of incoming) {
  await products.updateOne({ sku: item.sku }, { $set: item }, { upsert: true });
}
```

**Why bad:** network latency is paid once per document, so 10,000 items at 2 ms each spend 20 seconds waiting rather than working — the database is not the bottleneck, the round trips are

**Reading bulk errors:** with `ordered: false` a partial failure throws `MongoBulkWriteError`, whose `result` holds what did succeed and whose `writeErrors` names each failure by index. Discarding the error discards the record of what already applied.

---

## Pattern 3: Change Streams

### Good Example -- Reacting to Writes

```typescript
const changeStream = orders.watch([{ $match: { operationType: "insert" } }], {
  fullDocument: "updateLookup",
});

try {
  for await (const change of changeStream) {
    if (change.operationType === "insert") {
      await onOrderCreated(change.fullDocument);
    }
  }
} finally {
  await changeStream.close();
}
```

**Why good:** the pipeline filters server-side so uninteresting events never cross the network, and the `finally` closes the stream rather than leaving it open against the server

### Good Example -- Resuming After a Restart

```typescript
// Persist the resume token with the work it corresponds to, so a restart
// continues from the last processed change instead of replaying or skipping.
const resumeAfter = await loadResumeToken();
const stream = orders.watch([], resumeAfter ? { resumeAfter } : {});

for await (const change of stream) {
  await handle(change);
  await saveResumeToken(change._id);
}
```

**Why good:** without a stored token a restart resumes from now, silently losing every change that occurred while the process was down

**Change streams need a replica set,** and resumability is bounded by the oplog window — a process down longer than the oplog retains cannot resume and must fall back to a reconciliation pass.

---

## Pattern 4: Schema Evolution Without a Schema

### Good Example -- Versioned Documents

```typescript
const CURRENT_SCHEMA_VERSION = 2;

type UserDocV2 = {
  _id: ObjectId;
  schemaVersion: number;
  email: string;
  name: { first: string; last: string }; // v1 had a single `fullName`
};

// Read path tolerates both shapes; the migration runs in the background.
function normalizeUser(doc: WithId<Document>): UserDocV2 {
  if (doc.schemaVersion === CURRENT_SCHEMA_VERSION) return doc as UserDocV2;

  const [first = "", ...rest] = String(doc.fullName ?? "").split(" ");
  return {
    _id: doc._id,
    schemaVersion: CURRENT_SCHEMA_VERSION,
    email: String(doc.email),
    name: { first, last: rest.join(" ") },
  };
}

export { CURRENT_SCHEMA_VERSION, normalizeUser };
```

**Why good:** a stored version field makes "which shape is this?" answerable rather than inferred from which fields happen to be present, and the tolerant read path means the migration does not have to complete before the new code ships

### Good Example -- Server-Side Validation

```typescript
// MongoDB can enforce a schema even though the driver does not.
await db.command({
  collMod: "users",
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["email", "schemaVersion"],
      properties: {
        email: { bsonType: "string" },
        schemaVersion: { bsonType: "int" },
      },
    },
  },
  validationLevel: "moderate", // existing invalid documents are left alone
});
```

**Why good:** the guarantee lives with the data, so it holds for every writer including scripts and other services, and `moderate` applies it to new and valid-existing documents without rejecting a backlog that has not been migrated

---

## Pattern 5: Serverless and Edge

### Good Example -- Reusing the Client Across Invocations

```typescript
const SERVERLESS_POOL_SIZE = 5;
const MAX_IDLE_TIME_MS = 30_000;

let clientPromise: Promise<MongoClient> | undefined;

function getClient(): Promise<MongoClient> {
  // Caching the promise rather than the client means concurrent cold
  // invocations share one connect() instead of racing several.
  clientPromise ??= new MongoClient(requireEnv("MONGODB_URI"), {
    maxPoolSize: SERVERLESS_POOL_SIZE,
    minPoolSize: 0,
    maxIdleTimeMS: MAX_IDLE_TIME_MS,
  }).connect();

  return clientPromise;
}

export { getClient };
```

**Why good:** warm invocations reuse the pool and skip the handshake, caching the promise removes the race between simultaneous cold starts, and a small pool with `minPoolSize: 0` keeps total connections bounded when the platform scales out to many instances

### Bad Example -- Closing the Client per Invocation

```typescript
// BAD
export async function handler() {
  const client = await getClient();
  try {
    return await doWork(client);
  } finally {
    await client.close(); // discards the pool the next invocation would reuse
  }
}
```

**Why bad:** every invocation becomes a cold connect, so the platform's reuse of the process buys nothing and each request pays the full TLS and auth handshake

**Connection limits are the real constraint here.** Instances × `maxPoolSize` is the ceiling, and a platform that scales to 200 instances with a pool of 100 asks for 20,000 connections from a cluster that permits far fewer.

# MongoDB Query Examples

> Filters, projection, cursors, streaming, pagination and counting with the native driver. See [SKILL.md](../SKILL.md) for the decisions behind these.

**Core:** See [core.md](core.md). **Aggregation:** See [aggregation.md](aggregation.md). **Indexes:** See [indexes.md](indexes.md). **Advanced:** See [patterns.md](patterns.md).

---

## Pattern 1: Filters

### Good Example -- Typed Filter Construction

```typescript
import type { Filter } from "mongodb";

const MAX_RESULTS = 100;

type OrderQuery = {
  tenantId: ObjectId;
  status?: OrderStatus;
  minTotal?: number;
  since?: Date;
};

function buildOrderFilter(query: OrderQuery): Filter<OrderDoc> {
  const filter: Filter<OrderDoc> = { tenantId: query.tenantId };

  if (query.status !== undefined) filter.status = query.status;
  if (query.minTotal !== undefined) filter.total = { $gte: query.minTotal };
  if (query.since !== undefined) filter.createdAt = { $gte: query.since };

  return filter;
}

export { buildOrderFilter };
```

**Why good:** `Filter<OrderDoc>` checks every field name and operator against the document type, and the explicit `!== undefined` tests keep a legitimate `0` or empty string from being dropped the way a truthiness check would drop them

### Bad Example -- User Input Straight into a Filter

```typescript
// BAD: the request body becomes the filter
const orders = await collection
  .find({ tenantId, status: req.body.status })
  .toArray();
```

**Why bad:** a JSON body can supply an object rather than a string, so `{"status": {"$ne": null}}` turns the filter into an operator and returns every order in the tenant; the query is valid and nothing errors

### Good Example -- Coercing Before Filtering

```typescript
const ORDER_STATUSES = ["pending", "complete", "cancelled"] as const;
type OrderStatus = (typeof ORDER_STATUSES)[number];

function parseStatus(input: unknown): OrderStatus | undefined {
  if (typeof input !== "string") return undefined;
  return ORDER_STATUSES.find((status) => status === input);
}

export { ORDER_STATUSES, parseStatus };
```

**Why good:** the value reaching the filter is a primitive drawn from a known set, so an injected operator object cannot survive the parse

### Good Example -- ObjectId Validation

```typescript
import { ObjectId } from "mongodb";

const OBJECT_ID_PATTERN = /^[0-9a-fA-F]{24}$/;

function parseObjectId(input: string): ObjectId | undefined {
  // ObjectId.isValid() returns true for ANY 12-character string, so
  // "123456789012" passes it. Test the hex representation instead.
  if (!OBJECT_ID_PATTERN.test(input)) return undefined;
  return new ObjectId(input);
}

export { parseObjectId };
```

**Why good:** rejects the 12-character strings `ObjectId.isValid()` accepts, so a malformed path parameter becomes a 400 rather than a query that quietly matches nothing

---

## Pattern 2: Projection

### Good Example -- Fetching Only What Is Used

```typescript
type OrderListItem = { _id: ObjectId; total: number; createdAt: Date };

const items = await orders
  .find(filter)
  .project<OrderListItem>({ total: 1, createdAt: 1 })
  .limit(MAX_RESULTS)
  .toArray();
```

**Why good:** projection happens on the server, so large unused fields never cross the network, and the generic re-types the cursor to the shape actually returned

### Good Example -- Excluding Instead of Including

```typescript
// Inclusion and exclusion cannot be mixed in one projection, except for _id.
const user = await users.findOne(
  { _id: id },
  { projection: { passwordHash: 0 } },
);
```

**Why good:** an exclusion projection keeps returning new fields as the document evolves while guaranteeing the sensitive one is never among them, which an inclusion list would need updating to match

### Bad Example -- Filtering Fields in Application Code

```typescript
// BAD
const all = await orders.find(filter).toArray();
const items = all.map(({ _id, total, createdAt }) => ({
  _id,
  total,
  createdAt,
}));
```

**Why bad:** every field of every document is serialised, transferred and parsed before being discarded, so the cost is paid in full and only the memory afterwards is saved

---

## Pattern 3: Cursors and Streaming

### Good Example -- Streaming an Unbounded Read

```typescript
async function emailActiveUsers(users: Collection<UserDoc>): Promise<number> {
  let sent = 0;

  // for await pulls one batch at a time, so memory stays flat whether the
  // collection holds a thousand documents or ten million.
  for await (const user of users.find({ isActive: true })) {
    await sendDigest(user.email);
    sent += 1;
  }

  return sent;
}

export { emailActiveUsers };
```

**Why good:** the cursor is fully consumed so it closes on its own, and peak memory is one batch rather than the whole result set

### Good Example -- Closing a Cursor You Abandon

```typescript
const cursor = orders.find({ status: "pending" });

try {
  for await (const order of cursor) {
    if (await shouldStop(order)) break; // leaves the cursor open
  }
} finally {
  await cursor.close();
}
```

**Why good:** breaking out mid-iteration leaves an open server-side cursor holding resources until it times out; the `finally` releases it immediately and is harmless when the loop finished normally

### Good Example -- Batch Size for Slow Per-Document Work

```typescript
const SLOW_CONSUMER_BATCH_SIZE = 20;

const cursor = orders
  .find({ status: "pending" })
  .batchSize(SLOW_CONSUMER_BATCH_SIZE);
```

**Why good:** smaller batches shorten the pause when a batch is fetched and reduce the work discarded if the consumer stops early, which matters when each document triggers slow work

### Bad Example -- Buffering Everything

```typescript
// BAD
const everyone = await users.find({}).toArray();
for (const user of everyone) await sendDigest(user.email);
```

**Why bad:** the entire collection is materialised before the first email is sent, so memory scales with the data and the process dies once the collection outgrows the heap -- which it will not do in development

---

## Pattern 4: Pagination

### Good Example -- Keyset Pagination

```typescript
const PAGE_SIZE = 25;

type Page<T> = { items: T[]; nextCursor: string | undefined };

// Requires an index on the sort key. _id is monotonic enough for most feeds;
// use a compound key when sorting on something else.
async function pageOrders(
  orders: Collection<OrderDoc>,
  after: ObjectId | undefined,
): Promise<Page<WithId<OrderDoc>>> {
  const filter: Filter<OrderDoc> = after ? { _id: { $lt: after } } : {};

  const items = await orders
    .find(filter)
    .sort({ _id: -1 })
    .limit(PAGE_SIZE)
    .toArray();

  const last = items.at(-1);
  return {
    items,
    nextCursor:
      items.length === PAGE_SIZE ? last?._id.toHexString() : undefined,
  };
}

export { pageOrders };
```

**Why good:** every page costs the same because the index seeks straight to the cursor position, and `nextCursor` is `undefined` on a short page so the caller knows the feed ended without an extra count query

### Bad Example -- Deep Offset Pagination

```typescript
// BAD
const items = await orders
  .find(filter)
  .sort({ createdAt: -1 })
  .skip(page * PAGE_SIZE) // page 500 walks 12,500 documents to discard them
  .limit(PAGE_SIZE)
  .toArray();
```

**Why bad:** the server walks and discards every skipped document, so cost grows with page depth and the last pages time out; results also shift when a document is inserted between requests, so items can be seen twice or missed entirely

---

## Pattern 5: Counting

### Good Example -- Choosing the Right Count

```typescript
// Accurate, but scans the index or collection to answer.
const pending = await orders.countDocuments({ status: "pending" });

// Reads collection metadata: constant time, but approximate, and it takes
// no filter. Fine for a dashboard total, wrong for anything that must reconcile.
const approximateTotal = await orders.estimatedDocumentCount();
```

**Why good:** the choice is made explicitly on whether the number must be exact, rather than reaching for whichever is faster and discovering the imprecision later

### Good Example -- Existence Without Counting

```typescript
// findOne with a projection stops at the first match; counting does not.
const exists =
  (await users.findOne({ email }, { projection: { _id: 1 } })) !== null;
```

**Why good:** counting scans every match to produce a number the caller then compares to zero, while this stops as soon as one document is found

---

## Pattern 6: Distinct and Sorting

### Good Example -- Distinct Values

```typescript
const statuses = await orders.distinct("status", { tenantId });
```

**Why good:** the deduplication happens on the server, so only the distinct values cross the network rather than every document

**Limitation:** the result must fit in a single 16 MB reply. For a high-cardinality field use a `$group` pipeline, which streams instead.

### Good Example -- Sorting on an Indexed Field

```typescript
const recent = await orders
  .find({ tenantId })
  .sort({ createdAt: -1 }) // needs an index whose keys match this sort
  .limit(PAGE_SIZE)
  .toArray();
```

**Why good:** a sort backed by an index reads in order and stops at the limit; an unindexed sort loads every match into memory first and fails outright once that exceeds the server's sort limit