liveBook · Manning

Projection

As explained in Clean Applications with Hexagonal Architecture

A projection is a read-only view containing selected data from a domain model rather than the domain entity itself.

A display query rarely needs the entire aggregate that enforces business rules. A projection is a read-only view shaped around the data the caller needs, rather than the domain entity itself. It can be a DTO returned by a query or a stored, query-specific view maintained from updates or events. section 4.6.3 section 11.9

Keep reads for display separate from reads for mutation. A command handler can load an aggregate with readById and apply domain rules; a query handler can use findById or findByAuthor to retrieve a DTO or projection. Repository interfaces can expose these distinctions even when one adapter implements them. section 5.3.2

Listing 4.22 GetArticleByIdHandler implementing the use case directly
@ApplicationService
@RequiredArgsConstructor
final class GetArticleByIdHandler implements GetArticleByIdUseCase {
 
  private final ArticleRepository articleRepository; #A
 
  @Override
  public Either<Error, ArticleDTO>
    handle(final GetArticleByIdQuery query) {
    return this.articleRepository.findById(query.articleId()) #B
      .map(ArticleDTO::from); #C
  }
 
}

This query handler fetches an article and maps it to ArticleDTO. Another repository design can return the DTO directly from findById. section 4.6.3 section 5.3.2

A stored projection is useful when a query needs data owned by another context. For example, an article view may need an author’s display name while the article store holds only the author ID. A consumer-owned view can contain just the fields needed for that query, potentially combining data from several owners. The source context remains authoritative. section 11.6 section 11.9

Figure 11.2 The author service’s events feed WriteFlow’s author directory through a projection. The query reads the directory rather than calling the author service. The diagram shows one source context; others can feed the view when the query needs their data.

The author service’s events feed a local directory that the query can read without calling the service on each request. section 11.6

Choose the read strategy for each query:

  • Ask the owning service when the value must be current, accepting its latency and availability coupling. section 11.7
  • Use a replica when a broader local copy of published data meets the query’s response-time needs and the query can tolerate lag. section 11.6 section 11.7
  • Consider a projection when repeated filtering, joining, aggregation, or ordering makes requests too slow or complex. Moving that work to update processing may help, but measure the result. section 11.7

A local projection requires update processing, drift checks, and a way to rebuild or reconcile it. Its lag must be acceptable to the query. A stale view may shape what is displayed, but must not decide whether an action is allowed. An output port lets the query handler request the data it needs while an adapter hides the selected read strategy. section 11.9 section 11.7

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Explains repository conventions and read-strategy selection, including freshness, performance, ownership, and maintenance trade-offs.
Examples
Uses an article-by-ID DTO and an event-fed author directory supplying display names.
What you can do after
Evaluate read strategies for a query by weighing freshness, request-time work, and local-copy maintenance.
How it connects
Connects projections to command-query separation, repositories, aggregates, output ports, and CQRS.

Also explained in

Compare how 2 books explain projection →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.