Hibernate EntityManager

A EntityManagerFactory is an expensive-to-create, threadsafe object intended to be shared by all application threads. It is created once, usually on application startup.

An EntityManager is an inexpensive, non-threadsafe object that should be used once, for a single business process, a single unit of work, and then discarded. An EntityManager will not obtain a JDBC Connection (or a Datasource) unless it is needed, so you may safely open and close an EntityManager even if you are not sure that data access will be needed to serve a particular request. (This becomes important as soon as you are implementing some of the following patterns using request interception.)

To complete this picture you also have to think about database transactions. A database transaction has to be as short as possible, to reduce lock contention in the database. Long database transactions will prevent your application from scaling to highly concurrent load.

What is the scope of a unit of work? Can a single Hibernate EntityManager span several database transactions or is this a one-to-one relationship of scopes? When should you open and close a Session and how do you demarcate the database transaction boundaries?

Datatabase (or system) transaction boundaries are always necessary. No communication with the database can occur outside of a database transaction (this seems to confuse many developers who are used to the auto-commit mode). Always use clear transaction boundaries, even for read-only operations. Depending on your isolation level and database capabilities this might not be required but there is no downside if you always demarcate transactions explicitly. You'll have to do operations outside a transaction, though, when you'll need to retain modifications in an EXTENDED persistence context.

An EJB3 application can run in non-managed (i.e. standalone, simple Web- or Swing applications) and managed J2EE environments. In a non-managed environment, an EntityManagerFactory is usually responsible for its own database connection pool. The application developer has to manually set transaction boundaries, in other words, begin, commit, or rollback database transactions himself. A managed environment usually provides container-managed transactions, with the transaction assembly defined declaratively through annotations of EJB session beans, for example. Programmatic transaction demarcation is then no longer necessary, even flushing the EntityManager is done automatically.

Usually, ending a unit of work involves four distinct phases:

We'll now have a closer look at transaction demarcation and exception handling in both managed- and non-managed environments.

// Non-managed environment idiom
EntityManager em = emf.createEntityManager();
EntityTransaction tx = null;
try {
    tx = em.getTransaction();
    tx.begin();

    // do some work
    ...

    tx.commit();
}
catch (RuntimeException e) {
    if (tx != null) tx.rollback();
    throw e; // or display error message
}
finally {
    em.close();
}

// BMT idiom
@Resource public UserTransaction utx;
@Resource public EntityManagerFactory factory;

public void doBusiness() {
    EntityManager em = factory.createEntityManager();
    try {

    // do some work
    ...

    utx.commit();
}
catch (RuntimeException e) {
    if (utx != null) utx.rollback();
    throw e; // or display error message
}
finally {
    em.close();
}

// CMT idiom through factory
EntityManager em = factory.getEntityManager();

// do some work
...

/ /CMT idiom through injection
@Resource EntityManager em;

The only approach that is consistent with high concurrency and high scalability is optimistic concurrency control with versioning. Version checking uses version numbers, or timestamps, to detect conflicting updates (and to prevent lost updates). Hibernate provides for three possible approaches to writing application code that uses optimistic concurrency. The use cases we show are in the context of long application transactions but version checking also has the benefit of preventing lost updates in single database transactions.

// foo is an instance loaded by a previous entity manager
em = factory.createEntityManager();
EntityTransaction t = em.getTransaction();
t.begin();
int oldVersion = foo.getVersion();
Foo dbFoo = em.find( foo.getClass(), foo.getKey() ); // load the current state
if ( dbFoo.getVersion()!=foo.getVersion ) throw new StaleObjectStateException();
dbFoo.setProperty("bar");
t.commit();
em.close();

// foo is an instance loaded earlier by the extended entity manager
em.getTransaction.begin(); // new connection to data store is obtained and tx started
foo.setProperty("bar");
em.getTransaction().commit();  // End tx, flush and check version, disconnect

// foo is an instance loaded by a non-extended entity manager
foo.setProperty("bar");
entityManager = factory.createEntityManager();
entityManager.getTransaction().begin();
managedFoo = session.merge(foo); // discard foo and from now on use managedFoo
entityManager.getTransaction().commit();
entityManager.close();

As already discussed, automatic and transparent object/relational mapping is concerned with the management of object state. This implies that the object state is available in memory, hence updating or deleting (using SQL UPDATE and DELETE) data directly in the database will not affect in-memory state. However, Hibernate provides methods for bulk SQL-style UPDATE and DELETE statement execution which are performed through EJB-QL (Chapter 7, EJB-QL: The Object Query Language).

The pseudo-syntax for UPDATE and DELETE statements is: ( UPDATE | DELETE ) FROM? ClassName (WHERE WHERE_CONDITIONS)?. Note that:

As an example, to execute an EJB-QL UPDATE, use the Query.executeUpdate() method:

EntityManager entityManager = entityManagerFactory.createEntityManager();
entityManager.getTransaction().begin();

String ejbqlUpdate = "update Customer set name = :newName where name = :oldName"
int updatedEntities = entityManager.createQuery( hqlUpdate )
                            .setParameter( "newName", newName )
                            .setParameter( "oldName", oldName )
                            .executeUpdate();
entityManager.getTrasnaction().commit();
entityManager.close();

To execute an EJB-QL DELETE, use the same Query.executeUpdate() method (the method is named for those familiar with JDBC's PreparedStatement.executeUpdate()):

EntityManager entityManager = entityManagerFactory.createEntityManager();
entityManager.getTransaction().begin();

String hqlDelete = "delete Customer where name = :oldName";
int deletedEntities = entityManager.createQuery( hqlDelete )
                            .setParameter( "oldName", oldName )
                            .executeUpdate();
entityManager.getTrasnaction().commit();
entityManager.close();

The int value returned by the Query.executeUpdate() method indicate the number of entities effected by the operation. This may or may not correlate with the number of rows effected in the database. An EJB-QL bulk operation might result in multiple actual SQL statements being executed, for joined-subclass, for example. The returned number indicates the number of actual entities affected by the statement. Going back to the example of joined-subclass, a delete against one of the subclasses may actually result in deletes against not just the table to which that subclass is mapped, but also the "root" table and potentially joined-subclass tables further down the inheritence hierarchy.

Queries are case-insensitive, except for names of Java classes and properties. So SeLeCT is the same as sELEct is the same as SELECT but org.hibernate.eg.FOO is not org.hibernate.eg.Foo and foo.barSet is not foo.BARSET.

This manual uses lowercase EJBQL keywords. Some users find queries with uppercase keywords more readable, but we find this convention ugly when embedded in Java code.

The simplest possible EJB-QL query is of the form:

select c from eg.Cat c

which simply returns all instances of the class eg.Cat. Unlike HQL, the select clause is not optional in EJB-QL. We don't usually need to qualify the class name, since the entity name defaults to the unqualified class name (@Entity). So we almost always just write:

select c from Cat c

As you may have noticed you can assign aliases to classes, the as keywork is optional. An alias allows you to refer to Cat in other parts of the query.

select cat from Cat as cat

Multiple classes may appear, resulting in a cartesian product or "cross" join.

select form, param from Formula as form, Parameter as param

It is considered good practice to name query aliases using an initial lowercase, consistent with Java naming standards for local variables (eg. domesticCat).

You may also assign aliases to associated entities, or even to elements of a collection of values, using a join.

select cat, mate, kitten from Cat as cat 
    inner join cat.mate as mate
    left outer join cat.kittens as kitten

select cat from Cat as cat left join cat.mate.kittens as kittens

The supported join types are borrowed from ANSI SQL

The inner join, left outer join constructs may be abbreviated.

select cat, mate, kitten from Cat as cat 
    join cat.mate as mate
    left join cat.kittens as kitten

In addition, a "fetch" join allows associations or collections of values to be initialized along with their parent objects, using a single select. This is particularly useful in the case of a collection. It effectively overrides the fetching options in the associations and collection mapping metadata. See the Performance chapter of the Hibernate reference guide for more information.

select cat from Cat as cat 
    inner join fetch cat.mate
    left join fetch cat.kittens

A fetch join does not usually need to assign an alias, because the associated objects should not be used in the where clause (or any other clause). Also, the associated objects are not returned directly in the query results. Instead, they may be accessed via the parent object. The only reason we might need an alias is if we are recursively join fetching a further collection:

select cat from Cat as cat 
    inner join fetch cat.mate
    left join fetch cat.kittens child
    left join fetch child.kittens

Note that the fetch construct may not be used in queries called using scroll() or iterate(). Nor should fetch be used together with setMaxResults() or setFirstResult(). It is possible to create a cartesian product by join fetching more than one collection in a query (as in the example above), be careful the result of this product isn't bigger than you expect. Join fetching multiple collection roles also sometimes gives unexpected results for bag mappings, so be careful about how you formulate your queries in this case.

TODO: The last statement is useless and typical developer thinking, please elaborate. The word "sometimes" should never appear in any technical documentation.

If you are using property-level lazy fetching (with bytecode instrumentation), it is possible to force Hibernate to fetch the lazy properties immediately (in the first query) using fetch all properties. This is Hibernate specific option:

select doc from Document doc fetch all properties order by doc.name

select doc from Document doc fetch all properties where lower(doc.name) like '%cats%'

The select clause picks which objects and properties to return in the query result set. Consider:

select mate 
from Cat as cat 
    inner join cat.mate as mate

The query will select mates of other Cats. Actually, you may express this query more compactly as:

select cat.mate from Cat cat

Queries may return properties of any value type including properties of component type:

select cat.name from DomesticCat cat
where cat.name like 'fri%'

select cust.name.firstName from Customer as cust

Queries may return multiple objects and/or properties as an array of type Object[],

select mother, offspr, mate.name 
from DomesticCat as mother
    inner join mother.mate as mate
    left outer join mother.kittens as offspr

or as a List (HQL specific feature)

select new list(mother, offspr, mate.name)
from DomesticCat as mother
    inner join mother.mate as mate
    left outer join mother.kittens as offspr

or as an actual typesafe Java object,

select new Family(mother, mate, offspr)
from DomesticCat as mother
    join mother.mate as mate
    left join mother.kittens as offspr

assuming that the class Family has an appropriate constructor.

You may assign aliases to selected expressions using as:

select max(bodyWeight) as max, min(bodyWeight) as min, count(*) as n
from Cat cat

This is most useful when used together with select new map (HQL specific feature):

select new map( max(bodyWeight) as max, min(bodyWeight) as min, count(*) as n )
from Cat cat

This query returns a Map from aliases to selected values.

HQL queries may even return the results of aggregate functions on properties:

select avg(cat.weight), sum(cat.weight), max(cat.weight), count(cat)
from Cat cat

The supported aggregate functions are

You may use arithmetic operators, concatenation, and recognized SQL functions in the select clause (dpending on configured dialect, HQL specific feature):

select cat.weight + sum(kitten.weight) 
from Cat cat 
    join cat.kittens kitten
group by cat.id, cat.weight

select firstName||' '||initial||' '||upper(lastName) from Person

The distinct and all keywords may be used and have the same semantics as in SQL.

select distinct cat.name from Cat cat

select count(distinct cat.name), count(cat) from Cat cat

A query like:

select cat from Cat as cat

returns instances not only of Cat, but also of subclasses like DomesticCat. Hibernate queries may name any Java class or interface in the from clause (portable EJB-QL queries should only name mapped entities). The query will return instances of all persistent classes that extend that class or implement the interface. The following query would return all persistent objects:

from java.lang.Object o // HQL only

The interface Named might be implemented by various persistent classes:

from Named n, Named m where n.name = m.name // HQL only

Note that these last two queries will require more than one SQL SELECT. This means that the order by clause does not correctly order the whole result set. (It also means you can't call these queries using Query.scroll().)

The where clause allows you to narrow the list of instances returned. If no alias exists, you may refer to properties by name:

select cat from Cat cat where cat.name='Fritz'

returns instances of Cat named 'Fritz'.

select foo 
from Foo foo, Bar bar
where foo.startDate = bar.date

will return all instances of Foo for which there exists an instance of bar with a date property equal to the startDate property of the Foo. Compound path expressions make the where clause extremely powerful. Consider:

select cat from Cat cat where cat.mate.name is not null

This query translates to an SQL query with a table (inner) join. If you were to write something like

select foo from Foo foo  
where foo.bar.baz.customer.address.city is not null

you would end up with a query that would require four table joins in SQL.

The = operator may be used to compare not only properties, but also instances:

select cat, rival from Cat cat, Cat rival where cat.mate = rival.mate

select cat, mate 
from Cat cat, Cat mate
where cat.mate = mate

The special property (lowercase) id may be used to reference the unique identifier of an object. (You may also use its mapped identifer property name.). Note that this keyword is specific to HQL.

select cat from Cat as cat where cat.id = 123

select cat from Cat as cat where cat.mate.id = 69

The second query is efficient. No table join is required!

Properties of composite identifiers may also be used. Suppose Person has a composite identifier consisting of country and medicareNumber.

select person from bank.Person person
where person.id.country = 'AU' 
    and person.id.medicareNumber = 123456

select account from bank.Account account
where account.owner.id.country = 'AU' 
    and account.owner.id.medicareNumber = 123456

Once again, the second query requires no table join.

Likewise, the special property class accesses the discriminator value of an instance in the case of polymorphic persistence. A Java class name embedded in the where clause will be translated to its discriminator value. Once again, this is specific to HQL.

select cat from Cat cat where cat.class = DomesticCat

You may also specify properties of components or composite user types (and of components of components, etc). Never try to use a path-expression that ends in a property of component type (as opposed to a property of a component). For example, if store.owner is an entity with a component address

store.owner.address.city    // okay
store.owner.address         // error!

An "any" type has the special properties id and class, allowing us to express a join in the following way (where AuditLog.item is a property mapped with <any>). Any is specific to Hibernate

from AuditLog log, Payment payment 
where log.item.class = 'Payment' and log.item.id = payment.id

Notice that log.item.class and payment.class would refer to the values of completely different database columns in the above query.

Expressions allowed in the where clause include most of the kind of things you could write in SQL:

in and between may be used as follows:

select cat from DomesticCat cat where cat.name between 'A' and 'B'

select cat from DomesticCat cat where cat.name in ( 'Foo', 'Bar', 'Baz' )

and the negated forms may be written

select cat from DomesticCat cat where cat.name not between 'A' and 'B'

select cat from DomesticCat cat where cat.name not in ( 'Foo', 'Bar', 'Baz' )

Likewise, is null and is not null may be used to test for null values.

Booleans may be easily used in expressions by declaring HQL query substitutions in Hibernate configuration:

hibernate.query.substitutions true 1, false 0

This will replace the keywords true and false with the literals 1 and 0 in the translated SQL from this HQL:

select cat from Cat cat where cat.alive = true

You may test the size of a collection with the special property size, or the special size() function (HQL specific feature).

select cat from Cat cat where cat.kittens.size > 0

select cat from Cat cat where size(cat.kittens) > 0

For indexed collections, you may refer to the minimum and maximum indices using minindex and maxindex functions. Similarly, you may refer to the minimum and maximum elements of a collection of basic type using the minelement and maxelement functions. These are HQL specific features.

select cal from Calendar cal where maxelement(cal.holidays) > current date

select order from Order order where maxindex(order.items) > 100

select order from Order order where minelement(order.items) > 10000

The SQL functions any, some, all, exists, in are supported when passed the element or index set of a collection (elements and indices functions) or the result of a subquery (see below). While subqueries are supported by EJB-QL, elements and indices are specific HQL features.

select mother from Cat as mother, Cat as kit
where kit in elements(foo.kittens)

select p from NameList list, Person p
where p.name = some elements(list.names)

select cat from Cat cat where exists elements(cat.kittens)

select cat from Player p where 3 > all elements(p.scores)

select cat from Show show where 'fizard' in indices(show.acts)

Note that these constructs - size, elements, indices, minindex, maxindex, minelement, maxelement - may only be used in the where clause in Hibernate3.

In HQL, elements of indexed collections (arrays, lists, maps) may be referred to by index (in a where clause only):

select order from Order order where order.items[0].id = 1234

select person from Person person, Calendar calendar
where calendar.holidays['national day'] = person.birthDay
    and person.nationality.calendar = calendar

select item from Item item, Order order
where order.items[ order.deliveredItemIndices[0] ] = item and order.id = 11

select item from Item item, Order order
where order.items[ maxindex(order.items) ] = item and order.id = 11

The expression inside [] may even be an arithmetic expression.

select item from Item item, Order order
where order.items[ size(order.items) - 1 ] = item

HQL also provides the built-in index() function, for elements of a one-to-many association or collection of values.

select item, index(item) from Order order 
    join order.items item
where index(item) < 5

Scalar SQL functions supported by the underlying database may be used

select cat from DomesticCat cat where upper(cat.name) like 'FRI%'

If you are not yet convinced by all this, think how much longer and less readable the following query would be in SQL:

select cust
from Product prod,
    Store store
    inner join store.customers cust
where prod.name = 'widget'
    and store.location.name in ( 'Melbourne', 'Sydney' )
    and prod = all elements(cust.currentOrder.lineItems)

Hint: something like

SELECT cust.name, cust.address, cust.phone, cust.id, cust.current_order
FROM customers cust,
    stores store,
    locations loc,
    store_customers sc,
    product prod
WHERE prod.name = 'widget'
    AND store.loc_id = loc.id
    AND loc.name IN ( 'Melbourne', 'Sydney' )
    AND sc.store_id = store.id
    AND sc.cust_id = cust.id
    AND prod.id = ALL(
        SELECT item.prod_id
        FROM line_items item, orders o
        WHERE item.order_id = o.id
            AND cust.current_order = o.id
    )

The list returned by a query may be ordered by any property of a returned class or components:

select cat from DomesticCat cat
order by cat.name asc, cat.weight desc, cat.birthdate

The optional asc or desc indicate ascending or descending order respectively.

A query that returns aggregate values may be grouped by any property of a returned class or components:

select cat.color, sum(cat.weight), count(cat) 
from Cat cat
group by cat.color

select foo.id, avg(name), max(name) 
from Foo foo join foo.names name
group by foo.id

A having clause is also allowed.

select cat.color, sum(cat.weight), count(cat) 
from Cat cat
group by cat.color 
having cat.color in (eg.Color.TABBY, eg.Color.BLACK)

SQL functions and aggregate functions are allowed in the having and order by clauses, if supported by the underlying database (eg. not in MySQL).

select cat
from Cat cat
    join cat.kittens kitten
group by cat
having avg(kitten.weight) > 100
order by count(kitten) asc, sum(kitten.weight) desc

Note that neither the group by clause nor the order by clause may contain arithmetic expressions.

For databases that support subselects, EJB-QL supports subqueries within queries. A subquery must be surrounded by parentheses (often by an SQL aggregate function call). Even correlated subqueries (subqueries that refer to an alias in the outer query) are allowed.

select fatcat from Cat as fatcat 
where fatcat.weight > ( 
    select avg(cat.weight) from DomesticCat cat 
)

select cat from DomesticCat as cat 
where cat.name = some ( 
    select name.nickName from Name as name 
)

select cat from Cat as cat 
where not exists ( 
    from Cat as mate where mate.mate = cat 
)

select cat from DomesticCat as cat 
where cat.name not in ( 
    select name.nickName from Name as name 
)

For subqueries with more than one expression in the select list, you can use a tuple constructor:

select cat from Cat as cat 
where not ( cat.name, cat.color ) in ( 
    select cat.name, cat.color from DomesticCat cat 
)

Note that on some databases (but not Oracle or HSQLDB), you can use tuple constructors in other contexts, for example when querying components or composite user types:

select cat from Person where name = ('Gavin', 'A', 'King')

Which is equivalent to the more verbose:

select cat from Person where name.first = 'Gavin' and name.initial = 'A' and name.last = 'King')

There are two good reasons you might not want to do this kind of thing: first, it is not completely portable between database platforms; second, the query is now dependent upon the ordering of properties in the mapping document.

Hibernate queries can be quite powerful and complex. In fact, the power of the query language is one of Hibernate's main selling points (and now EJB-QL). Here are some example queries very similar to queries that I used on a recent project. Note that most queries you will write are much simpler than these!

The following query returns the order id, number of items and total value of the order for all unpaid orders for a particular customer and given minimum total value, ordering the results by total value. In determining the prices, it uses the current catalog. The resulting SQL query, against the ORDER, ORDER_LINE, PRODUCT, CATALOG and PRICE tables has four inner joins and an (uncorrelated) subselect.

select order.id, sum(price.amount), count(item)
from Order as order
    join order.lineItems as item
    join item.product as product,
    Catalog as catalog
    join catalog.prices as price
where order.paid = false
    and order.customer = :customer
    and price.product = product
    and catalog.effectiveDate < sysdate
    and catalog.effectiveDate >= all (
        select cat.effectiveDate 
        from Catalog as cat
        where cat.effectiveDate < sysdate
    )
group by order
having sum(price.amount) > :minAmount
order by sum(price.amount) desc

What a monster! Actually, in real life, I'm not very keen on subqueries, so my query was really more like this:

select order.id, sum(price.amount), count(item)
from Order as order
    join order.lineItems as item
    join item.product as product,
    Catalog as catalog
    join catalog.prices as price
where order.paid = false
    and order.customer = :customer
    and price.product = product
    and catalog = :currentCatalog
group by order
having sum(price.amount) > :minAmount
order by sum(price.amount) desc

The next query counts the number of payments in each status, excluding all payments in the AWAITING_APPROVAL status where the most recent status change was made by the current user. It translates to an SQL query with two inner joins and a correlated subselect against the PAYMENT, PAYMENT_STATUS and PAYMENT_STATUS_CHANGE tables.

select count(payment), status.name 
from Payment as payment 
    join payment.currentStatus as status
    join payment.statusChanges as statusChange
where payment.status.name <> PaymentStatus.AWAITING_APPROVAL
    or (
        statusChange.timeStamp = ( 
            select max(change.timeStamp) 
            from PaymentStatusChange change 
            where change.payment = payment
        )
        and statusChange.user <> :currentUser
    )
group by status.name, status.sortOrder
order by status.sortOrder

If I would have mapped the statusChanges collection as a list, instead of a set, the query would have been much simpler to write.

select count(payment), status.name 
from Payment as payment
    join payment.currentStatus as status
where payment.status.name <> PaymentStatus.AWAITING_APPROVAL
    or payment.statusChanges[ maxIndex(payment.statusChanges) ].user <> :currentUser
group by status.name, status.sortOrder
order by status.sortOrder

However the query would have been HQL specific.

The next query uses the MS SQL Server isNull() function to return all the accounts and unpaid payments for the organization to which the current user belongs. It translates to an SQL query with three inner joins, an outer join and a subselect against the ACCOUNT, PAYMENT, PAYMENT_STATUS, ACCOUNT_TYPE, ORGANIZATION and ORG_USER tables.

select account, payment
from Account as account
    join account.holder.users as user
    left outer join account.payments as payment
where :currentUser = user
    and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID)
order by account.type.sortOrder, account.accountNumber, payment.dueDate

Hibernate now supports UPDATE and DELETE statements in HQL/EJB-QL. See Section 6.1, “Bulk update/delete” for details.

To order a result by the size of a collection, use the following query:

select usr.id, usr.name
from User as usr 
    left join usr.messages as msg
group by usr.id, usr.name
order by count(msg)

If your database supports subselects, you can place a condition upon selection size in the where clause of your query:

from User usr where size(usr.messages) >= 1

If your database doesn't support subselects, use the following query:

select usr.id, usr.name
from User usr.name
    join usr.messages msg
group by usr.id, usr.name
having count(msg) >= 1

As this solution can't return a User with zero messages because of the inner join, the following form is also useful:

select usr.id, usr.name
from User as usr
    left join usr.messages as msg
group by usr.id, usr.name
having count(msg) = 0

To use a SQL query, you need to describe the SQL resultset, this description will help the EntityManager to map your columns onto entity properties. This is done using the @SqlResultSetMapping annotation. Each @SqlResultSetMapping has a name wich is used when creating a SQL query on EntityManager.

@SqlResultSetMapping(name="GetNightAndArea", entities={
    @EntityResult(name="org.hibernate.test.annotations.query.Night", fields = {
        @FieldResult(name="id", column="nid"),
        @FieldResult(name="duration", column="night_duration"),
        @FieldResult(name="date", column="night_date"),
        @FieldResult(name="area", column="area_id")
    }),
    @EntityResult(name="org.hibernate.test.annotations.query.Area", fields = {
        @FieldResult(name="id", column="aid"),
        @FieldResult(name="name", column="name")
    })
    }
)

//or
@SqlResultSetMapping(name="defaultSpaceShip", entities=@EntityResult(name="org.hibernate.test.annotations.query.SpaceShip"))

You can also define scalar results and even mix entity results and scalar results

@SqlResultSetMapping(name="ScalarAndEntities", 
    entities={
        @EntityResult(name="org.hibernate.test.annotations.query.Night", fields = {
            @FieldResult(name="id", column="nid"),
            @FieldResult(name="duration", column="night_duration"),
            @FieldResult(name="date", column="night_date"),
            @FieldResult(name="area", column="area_id")
        }),
        @EntityResult(name="org.hibernate.test.annotations.query.Area", fields = {
            @FieldResult(name="id", column="aid"),
            @FieldResult(name="name", column="name")
        })
    },
    columns={
        @ColumnResult(name="durationInSec")
    }
)

The SQL query will then have to return a column alias durationInSec.

Please refer to the Hibernate Annotations reference guide for more information about @SqlResultSetMapping.

TODO: This sounds like a dupe...

Now that the result set is described, we are capable of executing the native SQL query. EntityManager provides all the needed APIs. The first method is to use a SQL resultset name to do the binding, the second one uses the entity default mapping (the column returned has to have the same names as the one used in the mapping). A third one (not yet supported by Hibernate entity manager), returns pure scalar results.

String sqlQuery = "select night.id nid, night.night_duration, night.night_date, area.id aid, "
    + "night.area_id, area.name from Night night, Area area where night.area_id = area.id "
    + "and night.night_duration >= ?";
Query q = entityManager.createNativeQuery(sqlQuery, "GetNightAndArea");
q.setParameter( 1, expectedDuration );
q.getResultList();

This native query returns nights and area based on the GetNightAndArea result set.

String sqlQuery = "select * from tbl_spaceship where owner = ?";
Query q = entityManager.createNativeQuery(sqlQuery, SpaceShip.class);
q.setParameter( 1, "Han" );
q.getResultList();

The second version is useful when your SQL query returns one entity reusing the same columns as the ones mapped in metadata.

Native named queries share the same calling API than EJB-QL named queries. Your code doesn't need to know the difference between the two. This is very useful for migration from SQL to EJB-QL:

Query q = entityManager.createNamedQuery("getSeasonByNativeQuery");
q.setParameter( 1, name );
Season season = (Season) q.getSingleResult();