NestJS Enterprise Backend APIs · Lezione

Query e proiezioni dei read model

Separi le letture con handler di QueryBus basati su proiezioni denormalizzate ottimizzate.

Lezione 2 di 413 passaggi

Query e proiezioni dei read model è una lezione NestJS Enterprise Backend APIs gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento NestJS Enterprise Backend APIs, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso NestJS Enterprise Backend APIs include 4 lezioni in totale.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

Why a Separate Read Side?

In CQRS (Command Query Responsibility Segregation) you split the system into a write side (commands that mutate state) and a read side (queries that return data). The two have fundamentally different needs.

The write model is optimized for consistency and business invariants — normalized aggregates.
The read model is optimized for fast, shape-perfect reads — denormalized projections tailored to each screen or endpoint.

A projection is a precomputed, query-friendly view of your data, usually built by listening to domain events. Instead of joining six tables at request time, the query handler reads one already-shaped row.

Queries Are Not Commands

A query is a plain DTO describing what the caller wants to read. It carries no behavior and must never mutate state. In @nestjs/cqrs, queries flow through the QueryBus to a matching @QueryHandler.

Keep queries free of domain rules. Their only job is to name an intent and carry parameters (ids, filters, paging). All the heavy lifting lives in the handler against the read model.

export class GetOrderSummaryQuery {
  constructor(
    public readonly orderId: string,
    public readonly tenantId: string,
  ) {}
}

export class ListCustomerOrdersQuery {
  constructor(
    public readonly customerId: string,
    public readonly page = 1,
    public readonly pageSize = 20,
  ) {}
}

The QueryBus and QueryHandler

A @QueryHandler(SomeQuery) class implements IQueryHandler<SomeQuery, Result> and exposes an execute() method. Register handlers in the module's providers, then dispatch with queryBus.execute(new SomeQuery(...)).

Notice the handler reads directly from a projection table (here order_summary) — no aggregate rehydration, no event replay at request time.

import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { OrderSummaryView } from './order-summary.view';
import { GetOrderSummaryQuery } from './get-order-summary.query';

@QueryHandler(GetOrderSummaryQuery)
export class GetOrderSummaryHandler
  implements IQueryHandler<GetOrderSummaryQuery, OrderSummaryView> {
  constructor(
    @InjectRepository(OrderSummaryView)
    private readonly repo: Repository<OrderSummaryView>,
  ) {}

  async execute(query: GetOrderSummaryQuery): Promise<OrderSummaryView> {
    const row = await this.repo.findOne({
      where: { orderId: query.orderId, tenantId: query.tenantId },
    });
    if (!row) throw new Error('Order summary not found');
    return row;
  }
}

Designing the Projection Shape

A projection is denormalized on purpose. You duplicate data so the read is a single-row, single-table lookup. Design the shape around the consumer (the endpoint or UI), not around your domain model.

Flatten relationships: store the customer name inside the order summary row.
Precompute totals, counts, and labels so the API does zero arithmetic.
Add the indexes the query needs (e.g., (tenantId, customerId, placedAt)).

This entity maps to a read-only table that the write side never touches directly.

import { Entity, PrimaryColumn, Column, Index } from 'typeorm';

@Entity('order_summary')
@Index(['tenantId', 'customerId', 'placedAt'])
export class OrderSummaryView {
  @PrimaryColumn('uuid')
  orderId: string;

  @Column('uuid')
  tenantId: string;

  @Column('uuid')
  customerId: string;

  @Column()
  customerName: string; // denormalized copy

  @Column('int')
  lineItemCount: number; // precomputed

  @Column('numeric', { precision: 12, scale: 2 })
  totalAmount: string;

  @Column()
  status: string;

  @Column('timestamptz')
  placedAt: Date;
}

Building Projections from Events

Projections are kept up to date by projectors — event handlers that translate domain events into upserts on the read table. In @nestjs/cqrs a projector is an @EventsHandler.

Each event mutates exactly the columns it affects. The projector is the only writer of the projection table, which keeps ownership clear and avoids contention with the command side.

import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { OrderPlacedEvent } from '../events/order-placed.event';
import { OrderSummaryView } from './order-summary.view';

@EventsHandler(OrderPlacedEvent)
export class OrderPlacedProjector
  implements IEventHandler<OrderPlacedEvent> {
  constructor(
    @InjectRepository(OrderSummaryView)
    private readonly repo: Repository<OrderSummaryView>,
  ) {}

  async handle(event: OrderPlacedEvent): Promise<void> {
    await this.repo.upsert(
      {
        orderId: event.orderId,
        tenantId: event.tenantId,
        customerId: event.customerId,
        customerName: event.customerName,
        lineItemCount: event.lines.length,
        totalAmount: event.total,
        status: 'PLACED',
        placedAt: event.occurredAt,
      },
      ['orderId'],
    );
  }
}

Incremental Updates per Event

Most events do not rebuild the whole row — they patch a slice of it. An OrderShippedEvent only flips the status and stamps a ship date. Keep projectors small and event-specific.

Because the projector owns the table, an UPDATE by primary key is cheap and contention-free. Idempotency matters here — replaying the same event must not corrupt the row (more on that soon).

import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { OrderShippedEvent } from '../events/order-shipped.event';
import { OrderSummaryView } from './order-summary.view';

@EventsHandler(OrderShippedEvent)
export class OrderShippedProjector
  implements IEventHandler<OrderShippedEvent> {
  constructor(
    @InjectRepository(OrderSummaryView)
    private readonly repo: Repository<OrderSummaryView>,
  ) {}

  async handle(event: OrderShippedEvent): Promise<void> {
    await this.repo.update(
      { orderId: event.orderId },
      { status: 'SHIPPED' },
    );
  }
}

Eventual Consistency Is the Trade-off

When the read model is updated asynchronously after the command commits, the projection is eventually consistent. For a brief window the query may return stale data — for example, an order that was just placed might not yet appear in its summary list.

Embrace it for dashboards, lists, reports, and search where small lag is fine.
Mitigate it in the UI: optimistic updates, or return the new id from the command and let the client poll the read side.
For strict read-your-writes needs, query the write model directly or update the projection synchronously inside the same transaction.

Document the consistency guarantee per endpoint so consumers know what to expect.

Idempotent Projectors

Event delivery is usually at-least-once, so a projector may receive the same event twice. Make handlers idempotent so reprocessing is harmless.

Use upsert / UPDATE by key rather than blind INSERT.
Track the last processed event position (a checkpoint) per projection and skip anything you've already seen.
Avoid relative math like count = count + 1 unless you also dedupe by event id.

This small helper shows the dedupe idea in pure TypeScript: a checkpoint set guards against double application.

type Event = { id: string; type: string; orderId: string };

class IdempotentProjection {
  private processed = new Set<string>();
  private rows = new Map<string, { orderId: string; status: string }>();

  apply(event: Event): boolean {
    if (this.processed.has(event.id)) return false; // already seen
    this.processed.add(event.id);
    const row = this.rows.get(event.orderId) ?? { orderId: event.orderId, status: 'NEW' };
    if (event.type === 'OrderShipped') row.status = 'SHIPPED';
    this.rows.set(event.orderId, row);
    return true;
  }

  status(orderId: string): string | undefined {
    return this.rows.get(orderId)?.status;
  }
}

const p = new IdempotentProjection();
const e = { id: 'evt-1', type: 'OrderShipped', orderId: 'ord-9' };
console.log(p.apply(e)); // true  -> applied
console.log(p.apply(e)); // false -> duplicate ignored
console.log(p.status('ord-9')); // SHIPPED

Paging and Filtering on the Read Side

List endpoints belong entirely to the read model. Because the projection is already flat and indexed, paging and filtering are simple WHERE + LIMIT/OFFSET (or keyset) queries — no joins, no N+1.

Return a small page DTO with the items plus total count. Keep sorting on indexed columns so the database can satisfy the order without a filesort.

@QueryHandler(ListCustomerOrdersQuery)
export class ListCustomerOrdersHandler
  implements IQueryHandler<ListCustomerOrdersQuery> {
  constructor(
    @InjectRepository(OrderSummaryView)
    private readonly repo: Repository<OrderSummaryView>,
  ) {}

  async execute(q: ListCustomerOrdersQuery) {
    const [items, total] = await this.repo.findAndCount({
      where: { customerId: q.customerId },
      order: { placedAt: 'DESC' },
      take: q.pageSize,
      skip: (q.page - 1) * q.pageSize,
    });
    return { items, total, page: q.page, pageSize: q.pageSize };
  }
}

Wiring It in the Controller

Controllers stay thin: translate the HTTP request into a query and hand it to the QueryBus. No business logic, no repository access in the controller.

This keeps the transport layer decoupled from how reads are served. You could later swap the projection store (Postgres → Elasticsearch) without touching the controller.

import { Controller, Get, Param, Query } from '@nestjs/common';
import { QueryBus } from '@nestjs/cqrs';
import { GetOrderSummaryQuery } from './get-order-summary.query';
import { ListCustomerOrdersQuery } from './list-customer-orders.query';

@Controller('orders')
export class OrdersQueryController {
  constructor(private readonly queryBus: QueryBus) {}

  @Get(':id/summary')
  getSummary(@Param('id') id: string, @Query('tenantId') tenantId: string) {
    return this.queryBus.execute(new GetOrderSummaryQuery(id, tenantId));
  }

  @Get()
  list(@Query('customerId') customerId: string, @Query('page') page = 1) {
    return this.queryBus.execute(
      new ListCustomerOrdersQuery(customerId, Number(page)),
    );
  }
}

Rebuilding Projections

A huge advantage of event-sourced read models: you can rebuild a projection from scratch by replaying the event stream. This lets you change the read shape, fix a projector bug, or add a brand-new view without migrating old data manually.

Truncate (or version) the projection table.
Replay every relevant event through the projector in order.
Track a checkpoint so you can resume and switch reads over when caught up.

Strategies like blue/green projections build the new version alongside the old, then flip readers atomically — zero-downtime read-model migrations.

Quick Check: Serving a Fast List Read

You need a high-traffic endpoint that lists a customer's orders with customer name, total, and item count per row. The data is spread across normalized orders, order_lines, and customers tables. Reads vastly outnumber writes and small staleness is acceptable.

What is the most appropriate CQRS approach?

Rispondi nella lezione interattiva

Recap

You separated reads from writes with the query side of CQRS:

Queries are behavior-free DTOs dispatched via the QueryBus to @QueryHandler classes.
Projections are denormalized, indexed read tables shaped for the consumer, owned and updated by projectors (@EventsHandler) reacting to domain events.
Async projection brings eventual consistency — great for lists/dashboards; handle read-your-writes deliberately when needed.
Projectors must be idempotent (upsert by key, checkpoints) because delivery is at-least-once.
Read models can be rebuilt or migrated by replaying events, enabling blue/green, zero-downtime view changes.

The payoff: reads become single-row, single-table lookups — fast, scalable, and decoupled from your write-side aggregates.

Gratis per iniziare

Impara TypeScript con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 20
Lezioni: 76

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Query e proiezioni dei read model» è gratuita?

Sì — il testo completo di «Query e proiezioni dei read model» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso NestJS Enterprise Backend APIs, passa a CoddyKit PRO. Il corso NestJS Enterprise Backend APIs include 4 lezioni in totale.

Cosa imparerò in «Query e proiezioni dei read model»?

Separi le letture con handler di QueryBus basati su proiezioni denormalizzate ottimizzate. Eserciti NestJS Enterprise Backend APIs con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare NestJS Enterprise Backend APIs?

Non è richiesta alcuna esperienza precedente. NestJS Enterprise Backend APIs su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Query e proiezioni dei read model»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione NestJS Enterprise Backend APIs?

Sì. Ogni lezione NestJS Enterprise Backend APIs include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a NestJS Enterprise Backend APIs