A Repository interface exposes methods like findActiveCustomersInRegion(region) instead of letting callers build SQL WHERE clauses themselves. What is this technique called, and what problem does it prevent?

## What the technique is Query encapsulation means the Repository interface exposes **methods named after what the caller wants** (`findActiveCustomersInRegion(region)`, `findOverdueInvoices()`, `findByEmail(email)`) rather than exposing a generic mechanism for callers to build arbitrary queries themselves (e.g., a method that accepts a raw SQL string, or an open-ended `find(String whereClause)`). The method signature and name communicate the business intent; the query logic that satisfies it — a SQL `WHERE` clause, a MongoDB filter document, an in-memory `Stream.filter()` — lives entirely inside the implementation, invisible to the caller. Two callers asking `findActiveCustomersInRegion("EU")` get the same guaranteed behavior no matter which concrete Repository implementation is wired in. The method's parameter list is also part of the encapsulation: `region` arrives as a typed value the implementation controls how to bind, not as a fragment of text the caller assembled by hand. ## The problem it solves The problem this solves has two faces. 1. **Coupling.** If callers were allowed to pass raw query fragments, every call site would need to know the underlying schema and query dialect, and any schema change (renaming a column, changing a join) would force edits across the codebase instead of inside one Repository implementation. Query encapsulation keeps that knowledge in exactly one place. 2. **Second, security** — and just as important in production systems. Allowing callers to construct query strings (especially by string concatenation with user input) is the textbook opening for SQL injection. By accepting typed method parameters (`region: String`, `since: Instant`) and having the implementation bind them as query parameters — not string-interpolate them — the Repository closes off an entire class of injection vulnerabilities at the architecture level, not just by code-review vigilance. This is a **structural guarantee rather than a discipline-dependent one**: a reviewer doesn't need to re-verify every call site for correct escaping, because the interface's shape makes the unsafe path unreachable in the first place. ## The trade-off The trade-off is that a fully encapsulated, method-per-query Repository doesn't scale well as query variety grows. A reporting screen with five independently toggleable filters (status, region, date range, tag, assignee) would need 2^5 combinations if you tried to give each combination its own named method, which is obviously unworkable. Real systems handle this with a middle ground: a **Specification or Criteria object** (as in Spring Data's `JpaSpecificationExecutor`, or a hand-rolled `CustomerQuery` builder) that lets callers compose filter predicates through a typed, safe API without falling back to raw strings. This preserves encapsulation — callers still can't inject arbitrary SQL — while avoiding combinatorial method explosion. The cost is a more complex Repository implementation and a slightly leakier abstraction, since the specification objects usually mirror the query capabilities of the underlying store fairly closely. ## Failure modes Failure modes show up in a few recognizable ways. - Teams that resist adding a Specification mechanism sometimes cave to pressure by adding a **generic `findByCriteria(Map<String, Object> filters)` escape hatch**, which silently reintroduces the coupling and validation problems the pattern was meant to prevent — now any caller can pass arbitrary keys the implementation must defensively interpret, and typos become runtime bugs instead of compile errors. - Another common failure is **method names that don't actually match their query semantics after a refactor** — `findActiveCustomersInRegion` that quietly starts including recently-deactivated customers because someone changed the underlying filter without renaming the method, breaking the intention-revealing contract callers relied on. - A third failure mode is **performance**: an encapsulated method can hide an expensive full-table scan behind an innocent-looking name, and because callers can't see the query, they have no signal to know they should be worried about calling it in a loop (the classic N+1 problem when a `findById` is called per-item instead of a single `findByIdIn(ids)`). - A fourth, quieter failure is **interface bloat that outlives its usefulness**: methods added for a single one-off report five years ago linger in the interface indefinitely because nobody is confident enough to delete a public method they can't prove is unused, and the Repository slowly becomes a junk drawer of narrowly-scoped queries. ## A real-world instance A concrete real-world instance: Spring Data JPA's derived query methods let you declare `findByStatusAndRegion(Status status, String region)` directly as an interface method with no method body — Spring parses the method name at startup and generates the corresponding JPQL query automatically, which is query encapsulation taken to its logical extreme (the method signature *is* the query specification). When query needs outgrow what a derived method name can express, the same library offers `@Query` with named parameters, or `Specification<T>` composition, as the escape valves — illustrating exactly the encapsulation-versus-flexibility trade-off in a widely used production framework.