Annotates a repository method returning entities as a parameter-based automatic query method.
The Find
annotation indicates that the annotated repository method executes a query to retrieve entities
based on its parameters and on the arguments assigned to its parameters. The method return type identifies the entity
type returned by the query. Each parameter of the annotated method must either:
- have exactly the same type and name (the parameter name in the Java source, or a name assigned by
@By
) as a persistent field or property of the entity class, or - be of type
Limit
,Sort
,Order
, orPageRequest
.
The query is inferred from the method parameters which match persistent fields of the entity.
There is no specific naming convention for methods annotated with @Find
; they may be named arbitrarily,
and their names do not carry any semantic meaning defined by the Jakarta Data specification.
For example, consider an interface representing a garage:
@Repository interface Garage { @Find List<Car> getCarsWithModel(@By("model") String model); }
The @Find
annotation indicates that the getCarsWithModel(model)
method retrieves Car
instances with the given value of the model
field.
A method annotated with @Find
must return one of the following types:
- an entity type
E
, when the method returns a single instance, Optional<E>
, when the method returns at most a single instance,- an entity array type
E[]
, List<E>
,Stream<E>
, orPage<E>
orCursoredPage<E>
.
An automatic query method annotated Find
returns an entity instance for every record which satisfies the
parameter-based conditions.
- If the return type of the annotated method is
E
orOptional<E>
and more than one record satisfies the query conditions, the method must throwNonUniqueResultException
. - If the return type of the annotated method is
E
and no record satisfies the query conditions, the method must throwEmptyResultException
.
Annotations such as @Find
, @Query
, @Insert
, @Update
, @Delete
, and
@Save
are mutually-exclusive. A given method of a repository interface may have at most one @Find
annotation, lifecycle annotation, or query annotation.