JPA Query API

Queries are represented in JPA 2 by two interfaces - the old Queryjakarta.persistence.Query - JPA Interface Interface used to control query execution. interface, which was the only interface available for representing queries in JPA 1, and the new TypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. interface that was introduced in JPA 2. The TypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. interface extends the Queryjakarta.persistence.Query - JPA Interface Interface used to control query execution. interface.

In JPA 2 the Queryjakarta.persistence.Query - JPA Interface Interface used to control query execution. 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 TypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. 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 EntityManagerjakarta.persistence.EntityManager - JPA Interface Interface used to interact with the persistence context. (represented by em in the following code snippets), which serves as a factory for both Queryjakarta.persistence.Query - JPA Interface Interface used to control query execution. and TypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries.:

  Queryjakarta.persistence.Query - JPA Interface
 Interface used to control query execution. q1 = em.createQueryEntityManager.createQuery(qlString) - JPA Method
 Create an instance of Query for executing a
 Jakarta Persistence query language statement.("SELECT c FROM Country c");

  TypedQueryjakarta.persistence.TypedQuery - JPA Interface
 Interface used to control the execution of typed queries.<Country> q2 =
      em.createQueryEntityManager.createQuery(qlString,resultClass) - JPA Method
 Create an instance of TypedQuery for executing a
 Jakarta 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 TypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. 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 @NamedQueryjakarta.persistence.NamedQuery - JPA Annotation Declares a named query written in the Jakarta Persistence query language. and @NamedQueriesjakarta.persistence.NamedQueries - JPA Annotation Declares multiple named Jakarta 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:

In addition, the syntax of the JPA Query Language (JPQL) is described in: