Annotation Interface NamedNativeQuery

@Repeatable(NamedNativeQueries.class) @Target(TYPE) @Retention(RUNTIME) public @interface NamedNativeQuery
Declares a named native SQL query and, optionally, the mapping of the result of the native SQL query. Query names are scoped to the persistence unit. A named query may be executed by calling EntityHandler.createNamedQuery(String, Class). The SQL query should return a result set.

In simple cases, a resultClass() specifies how the native SQL query result set should be interpreted, for example: 

@NamedNativeQuery(
        name = "findWidgets",
        query = "SELECT o.id, o.quantity, o.item " +
                "FROM Order o, Item i " +
                "WHERE (o.item = i.id) AND (i.name = 'widget')",
        resultClass = com.acme.Order.class
)

In more complicated cases, a result set mapping is needed, which may be specified using either a separate annotation: 

@NamedNativeQuery(
        name = "OrderItems",
        query = "SELECT o.id, o.quantity, o.item, i.id, i.name, i.description " +
                "FROM Order o, Item i " +
                "WHERE (o.quantity > 25) AND (o.item = i.id)",
        resultSetMapping = "OrderItemResults"
)
@SqlResultSetMapping(
        name = "OrderItemResults",
        entities = {
                @EntityResult(entityClass=com.acme.Order.class),
                @EntityResult(entityClass=com.acme.Item.class)
        }
)
or using the elements of this annotation: 
@NamedNativeQuery(
        name = "OrderItems",
        query = "SELECT o.id, o.quantity, o.item, i.id, i.name, i.description " +
                "FROM Order o, Item i " +
                "WHERE (o.quantity > 25) AND (o.item = i.id)",
        resultSetMapping = "OrderItemResults",
        entities = {
                @EntityResult(entityClass=com.acme.Order.class),
                @EntityResult(entityClass=com.acme.Item.class)
        }
)

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

Since:
1.0
See Also:
API note:
A named native SQL statement which returns a row count is usually declared using NamedNativeStatement. For backward compatibility, this annotation may be used instead, but this usage is no longer encouraged.

  • Element Details

    • name

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

    • query

      String query
      The native SQL query string.

    • resultClass

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

      When the result class is explicitly specified and the result set mapping is not, either:

      • the result class is an entity class and is interpreted as a managed entity result with implicit field mappings determined by the names of the columns in the result set and the object/relational mapping of the entity,
      • the result class is the class of a basic type and the result set must have a single column which is interpreted as a scalar result,
      • the result class is a non-abstract class or record type with a constructor with the same number of parameters as the result set has columns, and is interpreted as a constructor result including all the columns of the result set, or
      • the result class is Object[].class and each query result is packaged in an array of type Object[], with the array elements corresponding by position with the columns of the select list and column values obtained according to the default type mappings defined by the JDBC specification.

      Otherwise, if a result set mapping is specified, an explicitly specified result class must agree with the type inferred from the result set mapping.

      If the result class is not explicitly specified, then:

      • it is inferred from the result set mapping, if any, or
      • it defaults to Object if the result set has a single column or Object[] if the result set has multiple columns.

      When neither result class nor result set mapping is specified, column values are obtained according to the default type mappings defined by the JDBC specification.

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

      Default:
      void.class

    • resultSetMapping

      String resultSetMapping
      The name of a result set mapping declared in metadata. The named result set mapping is used to interpret the result set of the native SQL query.

      Alternatively, the elements entities(), classes(), and columns() may be used to specify a result set mapping. These elements may not be used in conjunction with resultSetMapping.

      See Also:
      Default:
      ""

    • entities

      EntityResult[] entities
      Specifies the result set mapping to entities. May not be used in combination with resultSetMapping().
      Since:
      3.2
      Default:
      {}

    • classes

      ConstructorResult[] classes
      Specifies the result set mapping to constructors. May not be used in combination with resultSetMapping().
      Since:
      3.2
      Default:
      {}

    • columns

      ColumnResult[] columns
      Specifies the result set mapping to scalar values. May not be used in combination with resultSetMapping().
      Since:
      3.2
      Default:
      {}

    • hints

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