Annotation Interface SqlResultSetMapping

@Repeatable(SqlResultSetMappings.class) @Target({TYPE,METHOD}) @Retention(RUNTIME) public @interface SqlResultSetMapping
Specifies an explicit mapping of the columns of a result set of a native SQL query or stored procedure to entity classes, scalar values, and Java class constructors. Every SQL result set mapping has a name(). SQL result set mapping names must be unique within a persistence unit.

When a SQL result set mapping specifies more than one result mapping, 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 by the entities() element;
  2. constructor results, in the order declared by the classes() element; and then
  3. scalar results, in the order declared by the columns() element.

In this example, a named mapping is declared by annotating an entity class: 

@SqlResultSetMapping(
        name = "orderResults",
        entities = @EntityResult(
            entityClass = Order.class,
            fields = {
                @FieldResult(name = Order_.ID, column = "order_id"),
                @FieldResult(name = Order_.TOTAL, column = "order_total"),
                @FieldResult(name = Order_.ITEM, column = "order_item")
            }
        ),
        columns = @ColumnResult(name = "item_name")
)
@Entity
class Order { ... }

A reference to the mapping is obtained from the static metamodel class of the entity: 

List<Order> orders =
        entityManager.createNativeQuery(
                """
                  SELECT o.id AS order_id,
                         o.total AS order_total,
                         o.item_id AS order_item,
                         i.desc_name AS item_name
                  FROM orders o
                  JOIN order_items i
                    ON o.id = i.order_id
                  WHERE o.total > 25
                """,
                Order_._orderResults
        ).getResultList();

A SqlResultSetMapping may be reified at runtime as an instance of ResultSetMapping. A reified representation of a SqlResultSetMapping known to the persistence unit may be obtained by calling EntityManagerFactory.getResultSetMappings(Class) or from the static metamodel class of the annotated class. 

ResultSetMapping<Order> mapping =
        entityManager.getResultSetMappings(Order.class)
             .get(Order_.MAPPING_ORDER_RESULTS);
Since:
1.0
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    name
    The name given to the result set mapping.

  • 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.