Annotation Interface NativeQuery

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

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 {

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

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

     @NativeQuery("delete from documents"
             + " where id in (select document_id from trash)")
     @QueryOptions(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.

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.

Any implementation of Jakarta Data backed by Jakarta Persistence must support the use of this annotation as a Jakarta Data query annotation. Thus, a repository method annotated @NativeQuery is treated by the Jakarta Data provider as a query method, and an implementation of the method is supplied by the Jakarta Data provider.

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 agrees with the convention for Javadoc links, that is: the concatenation of the fully qualified name of the type, with the string #, the name of the annotated member, and the raw types of the method parameters, enclosed in parentheses and separated by commas, for example, "org.example.Library#getBookWithIsbn(java.lang.String)".

A result set mapping may be specified by annotating the method with one or more EntityResult, ColumnResult, or ConstructorResult annotations.

@NativeQuery("select * from books where isbn = ?")
@EntityResult(entityClass = Book.class,
    fields = {@FieldResult(name = Book_.ISBN, column = "isbn_13"),
              @FieldResult(name = Book_.TITLE, column = "title_en")})
Book getBookWithIsbn(String isbn);

When more than one result mapping annotation is specified, each row of the mapped query result set is represented as an instance of Object[] whose elements are, in order:

1. entity results, in the order in which they are declared;
2. constructor results, in the order in which they are declared; and then
3. scalar results, in the order in which they are declared.

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.