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("from Book where isbn = :isbn")
    Book findBookByIsbn(String isbn);

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

    @HQL("from Book 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 jakarta.persistence.EntityManager, org.hibernate.Session, org.hibernate.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,
• java.util.List,
• org.hibernate.query.Query,
• org.hibernate.query.SelectionQuery,
• jakarta.persistence.Query, or
• jakarta.persistence.TypedQuery.

For an insert, update, or delete query, the return type of the annotated method must be int 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.

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