Annotation Interface Projection

              @Retention(RUNTIME)
                @Target(TYPE) public @interface Projection
            

Declares a Java record as a projection for query results in Jakarta NoSQL.

This annotation allows Jakarta NoSQL to map query results to Java record types without requiring explicit selection of attributes in the query string, provided that:

• Each projection component matches a property returned by the query by name, or
• The component is annotated with Column to map to a different or nested path.

If the FROM clause is omitted in the query, the optional from() attribute can be used to specify the source entity class. If both the query and the annotation define an entity, the query takes precedence.

The target class must be a record with components that match the query result set either by name or by explicit column mapping using @Column.

This mapping is read-only and is only applicable for query results. It does not affect inserts, updates, or write operations.

Examples:

Using implicit mapping where component names match entity properties:

@Projection
public record TechProductView(String name, double price) {}

List<TechProductView> techProducts = template
    .typedQuery("FROM Product WHERE category = 'TECH'", TechProductView.class)
    .result();

Using the from attribute to specify the source entity when omitted from the query:

@Projection(from = Product.class)
public record PromotionalProduct(String name, double price, String category) {}

List<PromotionalProduct> promotions = template
    .typedQuery("WHERE price < 100", PromotionalProduct.class)
    .result();

Mapping nested or renamed attributes using Column:

@Projection(from = Order.class)
public record OrderSummary(
    String id,
    @Column("user.name") String customerName,
    @Column("user.address.city") String city,
    @Column("total") BigDecimal amount
) {}

You can also override simple field names with @Column even when they are not nested:

@Projection(from = Product.class)
public record ProductBonus(
    @Column("price") BigDecimal bonusAmount
) {}

Since:

1.1.0

See Also:

• Column

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
Class<?>	from	Specifies the source entity class that this projection is based on.

Element Details

from

                          Class<?> from
                        

Specifies the source entity class that this projection is based on. This is used when the query string does not explicitly include a FROM clause.

When this attribute is present, Jakarta NoSQL will infer the entity in the query and automatically inject the FROM clause during query execution.

Note: The specified class must be annotated with @Entity.

This enables simpler query definitions such as:

@Entity
public class Product {
    @Id
    private String id;
    @Column
    private String name;
    @Column
    private double price;
    @Column
    private ProductType type;
}

@Projection(from = Product.class)
public record PromotionalProduct(String name, double price, ProductType type) {}

List<PromotionalProduct> results = template
    .typedQuery("WHERE price < 100", PromotionalProduct.class)
    .result();

You may also use query parameters as usual:

List<PromotionalProduct> results = template
    .typedQuery("WHERE price < :maxPrice", PromotionalProduct.class)
    .bind("maxPrice", 100)
    .result();

Returns:

the source entity class, which must be annotated with @Entity

Default:

void.class