JPA Query API

Jakarta Persistence (JPA)

represents queries with two interfaces: the Queryjakarta.persistence.QueryInterface used to control query execution. interface, which was the only query interface in JPA 1, and the TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries. interface, which was introduced in JPA 2. The TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries. interface extends the Queryjakarta.persistence.QueryInterface used to control query execution. interface.

Use the Queryjakarta.persistence.QueryInterface used to control query execution. interface primarily when the query result type is unknown or when a query returns polymorphic results whose lowest common denominator is Object. When a more specific result type is expected, use the TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries. interface. The TypedQuery interface makes it easier to run queries and process results in a type-safe manner.

Building queries with createQuery

As with most JPA operations, queries start with an EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context. (represented as em in the following code snippets). The EntityManager serves as a factory for both Queryjakarta.persistence.QueryInterface used to control query execution. and TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries. objects:

  Queryjakarta.persistence.QueryInterface used to control query execution. q1 = em.createQueryjakarta.persistence.EntityManager.createQuery(String)Create an instance of   Query   for executing a Jakarta Persistence query language statement.("SELECT c FROM Country c");
  TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries.<Country> q2 =
      em.createQueryjakarta.persistence.EntityManager.createQuery(String,Class)Create an instance of   TypedQuery<X>   for executing a Jakarta Persistence query language statement.("SELECT c FROM Country c", Country.class);

In the preceding code, the same JPQL query, which retrieves all Country objects from the database, is represented by both q1 and q2. When you build a TypedQueryjakarta.persistence.TypedQueryInterface used to control the execution of typed queries. instance, you must pass the expected result type as an additional argument, as shown for q2. Because the result type is known in this case (the query returns only Country objects), a TypedQuery is preferred.

Using TypedQuery with ObjectDB has another advantage. In the context of the preceding queries, consider a scenario where no Country instances exist in the database and the Country class is not yet known as a managed entity class. In this case, only the TypedQuery variant is valid because it introduces the Country class to ObjectDB.

Dynamic JPQL, Criteria API, and named queries

In JPA, building queries by passing JPQL query strings directly to the createQuery method is called dynamic query construction because you can build the query string dynamically at run time.

The JPA Criteria API provides an alternative way to build dynamic queries. It uses Java objects that represent query elements instead of string-based JPQL.

JPA also provides a way to build static queries, known as named queries, by using the @NamedQueryjakarta.persistence.NamedQueryDeclares a named query written in the Jakarta Persistence query language. and @NamedQueriesjakarta.persistence.NamedQueriesDeclares multiple named Jakarta Persistence query language queries. annotations. In JPA, it is a best practice to use named queries instead of dynamic queries when possible.

Organization of this Section

The following pages explain how to define and run queries in JPA:

In addition, the following pages describe the syntax of the JPA Query Language (JPQL):