NestJS Enterprise Backend APIs · Lección

Consultas y proyecciones de modelos de lectura

Separe las lecturas mediante handlers de QueryBus respaldados por proyecciones desnormalizadas y optimizadas.

Lección 2 de 413 pasos

Consultas y proyecciones de modelos de lectura es una lección gratuita de NestJS Enterprise Backend APIs en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de NestJS Enterprise Backend APIs, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de NestJS Enterprise Backend APIs incluye 4 lecciones en total.

Partes de esta lección aún no han sido traducidas y se muestran en inglés.

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?

Responde en la lección interactiva

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 para empezar

Aprende TypeScript con un tutor de IA — gratis

Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.

Cursos: 20
Lecciones: 76

Empezar a aprender gratis Ver el curso completo

Preguntas frecuentes

¿La lección «Consultas y proyecciones de modelos de lectura» es gratis?

Sí — el texto completo de «Consultas y proyecciones de modelos de lectura» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de NestJS Enterprise Backend APIs, actualiza a CoddyKit PRO. El curso de NestJS Enterprise Backend APIs incluye 4 lecciones en total.

¿Qué aprenderé en «Consultas y proyecciones de modelos de lectura»?

Separe las lecturas mediante handlers de QueryBus respaldados por proyecciones desnormalizadas y optimizadas. Practicas NestJS Enterprise Backend APIs con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar NestJS Enterprise Backend APIs?

No se requiere experiencia previa. NestJS Enterprise Backend APIs en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Consultas y proyecciones de modelos de lectura»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de NestJS Enterprise Backend APIs?

Sí. Cada lección de NestJS Enterprise Backend APIs incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Comandos, handlers y el bus de comandos
Consultas y proyecciones de modelos de lectura
Eventos de dominio y AggregateRoot
Sagas para flujos de trabajo prolongados

← Volver a NestJS Enterprise Backend APIs