Annotation Interface NamedQuery

@Repeatable(NamedQueries.class) @Target(TYPE) @Retention(RUNTIME) public @interface NamedQuery
Declares a named query written in the Jakarta Persistence Query Language. Query names are scoped to the persistence unit. The query should be a SELECT query.

This annotation may be applied to any class or interface belonging to the persistence unit. 

@NamedQuery(name = "findAllCustomersWithName",
            query = "SELECT c FROM Customer c WHERE c.name LIKE :custName")
@Entity
class Customer { ... }

A named query may be executed by calling EntityHandler.createNamedQuery(String, Class). 

List<Customer> customers =
        em.createNamedQuery("findAllCustomersWithName", Customer.class)
            .setParameter("custName", "Smith")
            .getResultList();

Alternatively, a reference to a named query may be obtained via the static metamodel. 

List<Customer> customers =
        em.createQuery(Customer_._findAllCustomersWithName_)
            .setParameter("custName", "Smith")
            .getResultList();
Since:
1.0
See Also:
API note:
A named UPDATE or DELETE statement is usually declared using NamedStatement. For backward compatibility, this annotation may be used instead, but this usage is no longer encouraged.

  • Element Details

    • name

      String name
      (Required) The name used to identify the query in calls to EntityHandler.createNamedQuery(String).

    • query

      String query
      (Required) The query string in the Jakarta Persistence query language.

    • resultClass

      Class<?> resultClass
      (Optional) The class of each query result.

      When the result class is explicitly specified, either:

      1. the select list of the query contains only a single item, which must be assignable to the result class,
      2. the result class is Object[].class, or
      3. the result class is a non-abstract class or record type with a constructor with the same number of parameters as the query has items in its select list, and the constructor parameter types must exactly match the types of the corresponding items in the select list.

      In the first case, each query result is returned directly to the caller. In the second case, each query result is packaged in an array with the array elements corresponding by position with the items of the query select list. In the third case, each query result is automatically packaged in a new instance of the result class by calling the matching constructor.

      If the result class of a named query is not specified: it defaults to Object if the query has a single item in its select list or to Object[] if the query has multiple items in its select list. When generating the canonical static metamodel for a named query, the generator is permitted to infer a more precise type from the items in the select list.

      The result class may be overridden by explicitly passing a class object to EntityHandler.createNamedQuery(String, Class).

      Since:
      3.2
      Default:
      void.class

    • lockMode

      LockModeType lockMode
      (Optional) The lock mode type to use in query execution. If a lockMode other than LockModeType.NONE is specified, the query must be executed in a transaction and the persistence context joined to the transaction.
      Since:
      2.0
      See Also:
      Default:
      NONE

    • lockScope

      PessimisticLockScope lockScope
      (Optional) The pessimistic lock scope to use in query execution if a pessimistic lock mode is specified via lockMode().
      Since:
      4.0
      Default:
      NORMAL

    • hints

      QueryHint[] hints
      (Optional) Query properties and hints. May include vendor-specific query hints.
      See Also:
      Default:
      {}

    • entityGraph

      String entityGraph
      (Optional) The name of a named entity graph interpreted as a load graph and applied to the entity returned by the query. The named EntityGraph may be overridden by calling TypedQuery.setEntityGraph(EntityGraph).
      Since:
      4.0
      Default:
      ""