JPA Query API
Queries are represented in JPA 2 by two interfaces - the old Queryjavax.persistence.Query - JPA InterfaceInterface used to control query execution.javax.jdo.Query - JDO InterfaceThe
interface, which was the only interface available for representing queries in JPA 1, and the new Query
interface allows applications to obtain persistent
instances, values, and aggregate data
from the data store.TypedQueryjavax.persistence.TypedQuery
interface that was introduced in JPA 2. The TypedQueryjavax.persistence.TypedQuery
interface extends the Queryjavax.persistence.Query - JPA InterfaceInterface used to control query execution.javax.jdo.Query - JDO InterfaceThe
interface. Query
interface allows applications to obtain persistent
instances, values, and aggregate data
from the data store.
In JPA 2 the Queryjavax.persistence.Query - JPA InterfaceInterface used to control query execution.javax.jdo.Query - JDO InterfaceThe
interface should be used mainly when the query result type is unknown or when a query returns polymorphic results and the lowest known common denominator of all the result objects is Query
interface allows applications to obtain persistent
instances, values, and aggregate data
from the data store.Object
. When a more specific result type is expected queries should usually use the TypedQueryjavax.persistence.TypedQuery
interface. It is easier to run queries and process the query results in a type safe manner when using the TypedQuery
interface.
Building Queries with createQuery
As with most other operations in JPA, using queries starts with an EntityManagerjavax.persistence.EntityManager - JPA InterfaceInterface used to interact with the persistence context.
(represented by em
in the following code snippets), which serves as a factory for both Queryjavax.persistence.Query - JPA InterfaceInterface used to control query execution.javax.jdo.Query - JDO InterfaceThe
and Query
interface allows applications to obtain persistent
instances, values, and aggregate data
from the data store.TypedQueryjavax.persistence.TypedQuery
:
Queryjavax.persistence.Query - JPA InterfaceInterface used to control query execution.javax.jdo.Query - JDO InterfaceTheQuery
interface allows applications to obtain persistent instances, values, and aggregate data from the data store. q1 = em.createQueryEntityManager.createQuery(qlString) - JPA MethodCreate an instance ofQuery
for executing a Java Persistence query language statement.("SELECT c FROM Country c"); TypedQueryjavax.persistence.TypedQuery- JPA Interface Interface used to control the execution of typed queries.<Country> q2 = em.createQueryEntityManager.createQuery(qlString,resultClass) - JPA MethodCreate an instance ofTypedQuery
for executing a Java Persistence query language statement.("SELECT c FROM Country c", Country.class);
In the above code, the same JPQL query which retrieves all the Country
objects in the database is represented by both q1
and q2
. When building a TypedQueryjavax.persistence.TypedQuery
instance the expected result type has to be passed as an additional argument, as demonstrated for q2
. Because, in this case, the result type is known (the query returns only Country
objects), a TypedQuery
is preferred.
There is another advantage of using TypedQuery
in ObjectDB. In the context of the queries above, if there are no Country
instances in the database yet and the Country
class is unknown as a managed entity class - only the TypedQuery
variant is valid because it introduces the Country
class to ObjectDB.
Dynamic JPQL, Criteria API and Named Queries
Building queries by passing JPQL query strings directly to the createQuery
method, as shown above, is referred to in JPA as dynamic query construction because the query string can be built dynamically at runtime.
The JPA Criteria API provides an alternative way for building dynamic queries, based on Java objects that represent query elements (replacing string based JPQL).
JPA also provides a way for building static queries, as named queries, using the @NamedQueryjavax.persistence.NamedQuery - JPA AnnotationSpecifies a static, named query in the Java Persistence query language.
and @NamedQueriesjavax.persistence.NamedQueries - JPA AnnotationSpecifies multiple named Java Persistence query language queries.
annotations. It is considered to be a good practice in JPA to prefer named queries over dynamic queries when possible.
Organization of this Section
The following pages explain how to define and execute queries in JPA:
- Running JPA Queries
- Query Parameters in JPA
- JPA Named Queries
- JPA Criteria API Queries
- Setting and Tuning of JPA Queries
In addition, the syntax of the JPA Query Language (JPQL) is described in: