Package org.hibernate.annotations.processing

Annotation Type HQL

@Target(METHOD)
@Retention(CLASS)
@Incubating
public @interface HQL

Identifies a method of an abstract class or interface as defining the signature of a method which is used to execute the given HQL query, with an implementation generated automatically by the Hibernate Metamodel Generator.

For example:

 public interface Books {
     @HQL("where isbn = :isbn")
     Book findBookByIsbn(String isbn);

     @HQL("where title like ?1 order by title offset ?3 fetch first ?2 rows only")
     List<Book> findBooksByTitleWithPagination(String title, int max, int start);

     @HQL("select isbn, title, author.name from Book order by isbn")
     List<BookSummary> summarizeBooksWithPagination(Page page);

     @HQL("where title like ?1")
     TypedQuery<Book> createBooksByTitleQuery(String title);
 }
 

The Metamodel Generator automatically creates an "implementation" of these methods in the static metamodel class Books_. The generated methods may be called according to the following protocol:

 Book book = Books_.findBookByIsbn(session, isbn);
 List<Book> books = Books_.findBooksByTitleWithPagination(session, pattern, 10, 0);
 

Notice the extra parameter of type EntityManager at the start of the parameter list.

Alternatively, the type to which the annotated method belongs may also declare an abstract method with no parameters which returns one of the types EntityManager, Session, StatelessSession, or Mutiny.Session, for example:

 EntityManager entityManager();
 

In this case:

• the generated method is no longer static,
• the generated method will use this method to obtain the session object, instead of having a parameter of type EntityManager, and
• the generated static metamodel class will actually implement the type which declares the method annotated @SQL.

Thus, the generated methods may be called according to the following protocol:

 Books books = new Books_(session);
 Book book = books.findBookByIsbn(isbn);
 List<Book> books = books.findBooksByTitleWithPagination(pattern, 10, 0);
 

This is reminiscent of traditional DAO-style repositories.

For a select query, the return type of an annotated method must be:

• an entity type, or Optional<E> where E is an entity type,
• List<E> or Stream<E> where E is an entity type,
• List<Object[]> or Stream<Object[]>
• a record type or JavaBean class with a constructor signature matching the types in the query select list, or List<R> where R is such a type,
• io.smallrye.mutiny.Uni, when used with Hibernate Reactive,
• Query,
• SelectionQuery,
• Query, or
• TypedQuery.

For an insert, update, or delete query, the return type of the annotated method must be int, boolean, or void.

The method parameters must match the parameters of the HQL query, either by name or by position:

• an ordinal query parameter of form ?n is matched to the nth parameter of the method, and
• a named query parameter of form :name is matched to the method parameter name.

As an exception, the method may have:

• a parameter of type EntityManager, Session, StatelessSession, or Mutiny.Session,
• a parameter with type Page, and/or
• a parameter with type Order<? super E>, List<Order<? super E>>, or Order<? super E>... (varargs) where E is the entity type returned by the query.

For example:

 @HQL("where title like :title)
 List<Book> findBooksByTitleWithPagination(String title, Page page, Order<Book> order);
 

As a further exception, a method might support key-based pagination. Then it must have:

• return type KeyedResultList, and
• a parameter of type KeyedPage.

Queries specified using this annotation are always validated by the Metamodel Generator, and so it isn't necessary to specify the CheckHQL annotation.

Since:

6.3

See Also:

SQL, Find

API Note:

Instantiations with select new are not currently type-checked at build time, and so use of this syntax is not recommended. Nor, however, is this syntax necessary. Hibernate is able to automatically match the elements of the select list with a constructor of the method return type, which is much less verbose and just as type safe.

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	value

Element Detail

value

String value