Module jakarta.persistence

Package jakarta.persistence

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 EntityManager.createNamedQuery(String, Class).

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)
        }
)

The NamedNativeQuery annotation can be applied to an entity class or mapped superclass.

Since:

1.0

See Also:

• SqlResultSetMapping

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String	name	The name used to identify the query in calls to EntityManager.createNamedQuery(java.lang.String).
String	query	The native SQL query string.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
ConstructorResult[]	classes	Specifies the result set mapping to constructors.
ColumnResult[]	columns	Specifies the result set mapping to scalar values.
EntityResult[]	entities	Specifies the result set mapping to entities.
QueryHint[]	hints	Query properties and hints.
Class<?>	resultClass	The class of each query result.
String	resultSetMapping	The name of a SqlResultSetMapping, as defined in metadata.

Element Details

name

String name

The name used to identify the query in calls to EntityManager.createNamedQuery(java.lang.String).

query

String query

The native SQL query string.

hints

QueryHint[] hints

Query properties and hints. (May include vendor-specific query hints.)

Default:

{}

resultClass

Class<?> resultClass

The class of each query result. If a result set mapping is specified, the specified result class must agree with the type inferred from the result set mapping. If a resultClass is not explicitly specified, then it is inferred from the result set mapping, if any, or defaults to Object or Object[]. The query result class may be overridden by explicitly passing a class object to EntityManager.createNamedQuery(String, Class).

Default:

void.class

resultSetMapping

String resultSetMapping

The name of a SqlResultSetMapping, as defined 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.

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:

{}