Interface TypedQuery<T>

Type Parameters:
T - the type of the result objects
All Superinterfaces:
Query
public interface TypedQuery<T> extends Query
A type-safe variant of Query that maps query results directly to the target type T. This type can be either:
  • An entity class annotated with @Entity
  • A projection class annotated with Projection

One of the key benefits of using TypedQuery is that the FROM clause can be omitted when the provider is able to infer the source entity from the T type:

  • If T is an entity, the FROM clause is optional.
  • If T is a projection with the @Projection(from = ...) annotation, the entity source is inferred from it.

This simplifies queries significantly and avoids boilerplate.

Important: When using a FROM clause explicitly in the query string, the entity specified in the query must match the class provided as T. For example, the following is invalid and must raise an error:

// Assuming Cat and Dog are both entities
template.typedQuery("FROM Cat", Dog.class); //Must fail

This validation ensures consistency between the declared return type and the query structure.

Examples:

Using entity type with inferred FROM clause:

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

Using projection type with inferred FROM clause:

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

List<PromotionalProduct> promos = template
    .typedQuery("WHERE price < 100", PromotionalProduct.class)
    .result();
Since:
1.1.0

  • Method Details

    • result

      List<T> result()
      Executes the SELECT query and returns the results as a List of type T.

      This method can only be used with SELECT queries. It throws an UnsupportedOperationException if called for a non-select query such as UPDATE or DELETE.

      List<TechProductView> results = template
    .typedQuery("FROM Product WHERE category = 'TECH'", TechProductView.class)
    .result();
      Specified by:
      result in interface Query
      Returns:
      list of results or an empty list
      Throws:
      UnsupportedOperationException - if the query is not a SELECT

    • stream

      Stream<T> stream()
      Executes the SELECT query and returns the results as a Stream of type T.

      This is useful for processing large result sets in a streaming fashion. It throws an UnsupportedOperationException if the query is not a SELECT.

         Stream<TechProductView> stream = template
        .typedQuery("FROM Product WHERE active = true", TechProductView.class)
        .stream();
    stream.forEach(System.out::println);

}
      Specified by:
      stream in interface Query
      Returns:
      stream of results
      Throws:
      UnsupportedOperationException - if the query is not a SELECT

    • singleResult

      Optional<T> singleResult()
      Executes the SELECT query and returns a single result wrapped in an Optional.

      If no result is found, returns Optional.empty(). If more than one result is found, the behavior is provider-specific and may result in an exception.

      Optional<Product> product = template
    .typedQuery("WHERE id = :id", Product.class)
    .bind("id", "p-42")
    .singleResult();
      Specified by:
      singleResult in interface Query
      Returns:
      optional containing the result or empty
      Throws:
      UnsupportedOperationException - if the query is not a SELECT

    • bind

      TypedQuery<T> bind(String name, Object value)
      Binds a named parameter to the query. 
      TypedQuery<Product> query = template.typedQuery("SELECT * FROM Book WHERE title = :title", Product.class)
                      .bind("title", "Effective Java");
      Specified by:
      bind in interface Query
      Parameters:
      name - the parameter name (without :)
      value - the value to bind
      Returns:
      this query instance for fluent chaining
      Throws:
      NullPointerException - if the name is null

    • bind

      TypedQuery<T> bind(int position, Object value)
      Binds a positional parameter to the query. Positions are 1-based. 
      TypedQuery<Product> query = template.query("SELECT * FROM Person WHERE age > ?1", Product.class)
                      .bind(1, 30);
      Specified by:
      bind in interface Query
      Parameters:
      position - the parameter position (starting at 1)
      value - the value to bind
      Returns:
      this query instance for fluent chaining
      Throws:
      IllegalArgumentException - if position is less than 1