findFirst3By

FindFirst3By is a derived query method name used in Spring Data repositories to retrieve up to the first three entities that match the given criteria. It is part of Spring Data JPA (and other Spring Data modules) and relies on the method name to generate the corresponding query automatically from the domain model and repository interface.

How it works: The segment after By encodes property-based conditions, connected with And or Or. The number 3 after First or Top indicates a limit of three results. The method returns a list of the domain type, with up to three items depending on how many matches exist. To ensure deterministic results, you should specify an Order By clause or pass a Sort to guarantee which records are considered “first.”

Examples: List<User> findFirst3ByStatusOrderByCreatedDateDesc(String status); This returns up to three users with the given status, ordered by createdDate in descending order. Another example: List<Product> findTop3ByCategoryAndInStockTrueOrderByPriceAsc(String category); This yields up to three products in the specified category that are in stock, ordered by price ascending.

Return type and alternatives: The typical return type is List<T>. If fewer than three matches exist, the list simply contains fewer elements. You can also use Top3/First3 in combination with Order By to control ordering, or use a Pageable parameter to apply paging, including a limit of three (e.g., PageRequest.of(0, 3)).

Limitations: The result’s order should be explicitly defined to be deterministic. The method name approach depends on property names existing in the domain model and the repository interface being properly configured. Related methods include findTop3By, findFirst2By, and variations using First/Top with different counts.