Module jakarta.data
Package jakarta.data.repository

Annotation Interface Select

@Documented @Repeatable(List.class) @Retention(RUNTIME) @Target({METHOD,RECORD_COMPONENT}) public @interface Select

Determines the attribute or attributes of an entity which are returned by a parameter-based or annotated query method. The subset of entity attributes is referred to as a projection.

This annotation may be applied to a repository method annotated @Find or to a component of a record type.

  • At most one @Select annotation may be applied to a @Find method that returns an entity attribute type.
  • Multiple @Select annotations may be applied to a @Find method which returns a record type, one annotation for each component of the record type. The number and order of @Select annotations must match the number and order of record components.
  • At most one @Select annotation may be applied to a component of a record type. When applied to a record component, the Select annotation affects:
    • every @Find method which returns the record type and which does not have a @Select annotation, and
    • every @Query method which returns the record type and does not have an explicit SELECT clause.

This annotation must not be used in other locations; in particular, it must not be used on repository methods annotated jakarta.persistence.query.StaticNativeQuery.

Sort criteria for a repository method that returns a projection can include any of the returned entity attributes that are of sortable type.

Since:
1.1
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Select.List
    Enables multiple Select annotations on a repository Find method that returns a Java record type.

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    value
    Name of an entity attribute that has a single-valued basic type.

  • Element Details

    • value

      String value

      Name of an entity attribute that has a single-valued basic type. Multiple-valued types such as collections, arrays, and associations cannot be retrieved independently of the entity.

      The Select annotation can be used with repository methods that return a single entity attribute or multiple entity attributes.

      Method that returns Single Entity Attributes

      Place the Select annotation on a repository find method and assign the annotation value to be the name of a single entity attribute. The result type that is used in the method return type must be the type of the entity attribute.

      For example, to return only the price attribute of the Car entity that has the supplied vin attribute value,

      
 @Repository
 public interface Cars extends BasicRepository<Car, String> {
     @Find
     @Select(_Car.PRICE)
     Optional<Float> getPrice(@By(_Car.VIN) String vehicleIdNum);
 }

      Method that returns Java Records

      A repository method can return a projection by having the result type be a Java record. The Select annotation can be used in the following ways to accommodate this.

      Annotating a Repository Method

      Place one or more Select annotations on a repository find method and assign the annotation values to be the names of entity attributes, corresponding to the order and types of the components of the Java record that is used for the result type.

      For example, to return only the model, make, and year attributes of a Car entity that has the supplied vin attribute value,

      
 @Repository
 public interface Cars extends BasicRepository<Car, String> {
     record ModelInfo(String model,
                      String manufacturer,
                      int designYear) {}

     @Find
     @Select(_Car.MODEL)
     @Select(_Car.MAKE)
     @Select(_Car.YEAR)
     Optional<ModelInfo> getModelInfo(@By(_Car.VIN) String vehicleIdNum);
 }
      Annotating a Record Component

      Place the Select annotation on each record component of the Java record that is used as the result type of the repository method. Assign the annotation value to be the name of an entity attribute that has the same type as the record component.

      
 @Repository
 public interface Cars extends BasicRepository<Car, String> {
     record ModelInfo(@Select(_Car.MODEL) String model,
                      @Select(_Car.MAKE) String manufacturer,
                      @Select(_Car.YEAR) int designYear) {}

     @Find
     Optional<ModelInfo> getModelInfo(@By(_Car.VIN) String vehicleIdNum);
 }

      For more concise code, the Select annotation can be omitted from a record component that has the same name as the entity attribute, such as model in the above example.

      The examples above use the static metamodel, to avoid hard coding String values for the entity attribute names.