JPA Query API

Queries are represented in JPA 2 by two interfaces - the old Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.See JavaDoc Reference Page... interface, which was the only interface available for representing queries in JPA 1, and the new TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.See JavaDoc Reference Page... interface that was introduced in JPA 2. The TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.See JavaDoc Reference Page... interface extends the Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.See JavaDoc Reference Page... interface.

In JPA 2 the Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.See JavaDoc Reference Page... 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 Object. When a more specific result type is expected queries should usually use the TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.See JavaDoc Reference Page... 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.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... (represented by em in the following code snippets), which serves as a factory for both Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.See JavaDoc Reference Page... and TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.See JavaDoc Reference Page...:

  Queryjavax.persistence.QueryJPA interfaceInterface used to control query execution.See JavaDoc Reference Page... q1 = em.createQuerycreateQuery(qlString)EntityManager's methodCreate an instance of Query for executing a
 Java Persistence query language statement.See JavaDoc Reference Page...("SELECT c FROM Country c");

  TypedQueryjavax.persistence.TypedQueryJPA interfaceInterface used to control the execution of typed queries.See JavaDoc Reference Page...<Country> q2 =
      em.createQuerycreateQuery(qlString, resultClass)EntityManager's methodCreate an instance of TypedQuery for executing a
 Java Persistence query language statement.See JavaDoc Reference Page...("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.TypedQueryJPA interfaceInterface used to control the execution of typed queries.See JavaDoc Reference Page... 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.NamedQueryJPA annotationSpecifies a static, named query in the Java Persistence query language.See JavaDoc Reference Page... and @NamedQueriesjavax.persistence.NamedQueriesJPA annotationSpecifies multiple named Java Persistence query language queries.See JavaDoc Reference Page... 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:

• JPA Query Structure (JPQL / Criteria)
• JPA Query Expressions (JPQL / Criteria)