Annotation Interface StaticNativeQuery

@Target(METHOD)
@Retention(RUNTIME)
public @interface StaticNativeQuery

Specifies a query expressed in the native SQL dialect of the database. This annotation may be applied to:

• any method of any class or interface belonging to the persistence unit, or
• a query method of a Jakarta Data repository with an implementation backed by Jakarta Persistence.

The return type of the method must agree with the type returned by the query. The parameter types of the method must agree with the types of the query parameters. It is not usually possible to determine if such agreement exists without executing the native SQL query.

 interface Library {

     @StaticNativeQuery("select * from books where title like ?")
     @ReadQueryOptions(cacheStoreMode = CacheStoreMode.BYPASS)
     List<Book> findBooksByTitle(String title);

     @StaticNativeQuery("select * from books where isbn = ?")
     Book getBookWithIsbn(String isbn);

     @StaticNativeQuery("delete from documents"
             + " where id in (select document_id from trash)")
     @WriteQueryOptions(timeout = 30_000)
     int emptyTrash();
 }

A method return type agrees with the type returned by a SQL statement that returns a result set if either:

• it is exactly R, List<R>, or Stream<R> where the query return type is assignable to R, or
• the method is a Jakarta Data repository method, and its return type is a legal query method return type for the given query, as specified by Jakarta Data.

A method return type agrees with the type returned by a SQL statement that returns a row count if the return type is void, int, or long.

A method parameter type agrees with a query parameter type if it is a type that could be assigned to the corresponding query parameter by passing an instance of the type to setParameter(). In making this determination, method parameters are correlated with query parameters by position or by name, depending on whether the query uses positional or named parameters.

When this annotation is applied to a method of a class or interface belonging to the persistence unit, a reference to a query declared using this annotation may be obtained from the static metamodel class of the annotated class or interface.

List<Book> books =
        em.createQuery(Library_.findBooksByTitle("%Jakarta%"))
          .getResultList();

Book book =
        em.createQuery(Library_.getBookWithIsbn(isbn))
          .getSingleResult();

int deleted =
        em.createQuery(Library_.emptyTrash())
          .executeUpdate();

In addition, the query is treated as a named query, where the query name is the concatenation of the unqualified name of the type, with the string ".", and the name of the annotated member, for example, "Library.getBookWithIsbn".

If a SqlResultSetMapping exists with the same name as the query, it is used to map the result set of the query. If the @SqlResultSetMapping annotation occurs on the same method as @StaticNativeQuery annotation, name defaulting rules conspire to ensure that no name needs to be explicitly specified.

@StaticNativeQuery("select * from books where isbn = ?")
@SqlResultSetMapping(entities =
        @EntityResult(entityClass = Book.class,
                fields = {@FieldResult(name = "isbn", column = "isbn_13"),
                          @FieldResult(name = "title", column = "title_en"})
Book getBookWithIsbn(String isbn);

An implementation of Jakarta Data backed by Jakarta Persistence must treat this annotation as a Jakarta Data query annotation.

The parameter types of the annotated method must be basic types. If this annotation occurs on a generic method, on a method with a parameter type which is not a basic type, or on a method with a return type or parameter type involving a type variable, the behavior is undefined.

Since:

4.0

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	value	The query string in the native SQL dialect of the database.

Element Details

value

String value

The query string in the native SQL dialect of the database.