JPA Criteria API Queries

The JPA Criteria API provides an alternative way for defining JPA queries, which is mainly useful for building dynamic queries whose exact structure is only known at runtime.

JPA Criteria API vs JPQL

JPQL queries are defined as strings, similarly to SQL. JPA criteria queries, on the other hand, are defined by the instantiation of Java objects that represent query elements.

A major advantage of using the criteria API is that errors can be detected earlier, during compilation rather than at runtime. On the other hand, for many developers string based JPQL queries, which are very similar to SQL queries, are easier to use and understand.

For simple static queries - string based JPQL queries (e.g. as named queries) may be preferred. For dynamic queries that are built at runtime - the criteria API may be preferred.

For example, building a dynamic query based on fields that a user fills at runtime in a form that contains many optional fields - is expected to be cleaner when using the JPA criteria API, because it eliminates the need for building the query using many string concatenation operations.

String based JPQL queries and JPA criteria based queries are equally powerful and efficient. Therefore, choosing one method over the other is also a matter of personal preference. 

First JPA Criteria Query

The following query string represents a minimal JPQL query:

SELECT c FROM Country c

An equivalent query can be built using the JPA criteria API as follows:

  CriteriaBuilderjakarta.persistence.criteria.CriteriaBuilder - JPA Interface
 Used to construct criteria queries, compound selections,
 expressions, predicates, orderings. cb = em.getCriteriaBuilderEntityManager.getCriteriaBuilder() - JPA Method
 Obtain an instance of CriteriaBuilder which may be
 used to construct CriteriaQuery objects.();

  CriteriaQueryjakarta.persistence.criteria.CriteriaQuery - JPA Interface
 The {@code CriteriaQuery} interface defines functionality that is
 specific to top-level queries.<Country> q = cb.createQueryCriteriaBuilder.createQuery(resultClass) - JPA Method
 Create a CriteriaQuery object with the given
 result type.(Country.class);
  Rootjakarta.persistence.criteria.Root - JPA Interface
 A root type in the from clause.<Country> c = q.fromAbstractQuery.from(entityClass) - JPA Method
 Create and add a query root corresponding to the given entity,
 forming a cartesian product with any existing roots.(Country.class);
  q.selectCriteriaQuery.select(selection) - JPA Method
 Specify the item that is to be returned in the query result.(c);

The CriteriaBuilderjakarta.persistence.criteria.CriteriaBuilder - JPA Interface Used to construct criteria queries, compound selections, expressions, predicates, orderings. interface serves as the main factory of criteria queries and criteria query elements. It can be obtained either by the EntityManagerFactoryjakarta.persistence.EntityManagerFactory - JPA Interface Interface used to interact with the persistence unit, and to create new instances of EntityManager.'s getCriteriaBuilderEntityManagerFactory.getCriteriaBuilder() - JPA Method Return an instance of CriteriaBuilder which may be used to construct jakarta.persistence.criteria.CriteriaQuery objects. method or by the EntityManagerjakarta.persistence.EntityManager - JPA Interface Interface used to interact with the persistence context.'s getCriteriaBuilderEntityManager.getCriteriaBuilder() - JPA Method Obtain an instance of CriteriaBuilder which may be used to construct CriteriaQuery objects. method (both methods are equivalent).

In the example above a CriteriaQueryjakarta.persistence.criteria.CriteriaQuery - JPA Interface The {@code CriteriaQuery} interface defines functionality that is specific to top-level queries. instance is created for representing the built query. Then a Rootjakarta.persistence.criteria.Root - JPA Interface A root type in the from clause. instance is created to define a range variable in the FROM clause. Finally, the range variable, c, is also used in the SELECT clause as the query result expression. CriteriaQueryTypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries.TypedQuery

  TypedQueryjakarta.persistence.TypedQuery - JPA Interface
 Interface used to control the execution of typed queries.<Country> query = em.createQueryEntityManager.createQuery(criteriaQuery) - JPA Method
 Create an instance of TypedQuery for executing a
 criteria query.(q);
  List<Country> results = query.getResultListQuery.getResultList() - JPA Method
 Execute a SELECT query and return the query results as an untyped
 List.();

Using the criteria API introduces some extra work, at least for simple static queries, since the equivalent JPQL query could simply be executed as follows:

  TypedQueryjakarta.persistence.TypedQuery - JPA Interface
 Interface used to control the execution of typed queries.<Country> query =
      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);
  List<Country> results = query.getResultListQuery.getResultList() - JPA Method
 Execute a SELECT query and return the query results as an untyped
 List.();

Because eventually both types of queries are represented by a TypedQueryjakarta.persistence.TypedQuery - JPA Interface Interface used to control the execution of typed queries. instance - query execution and query setting is similar, regardless of the way in which the query is built.

Parameters in Criteria Queries

The following query string represents a JPQL query with a parameter:

SELECT c FROM Country c WHERE c.population > :p

An equivalent query can be built using the JPA criteria API as follows:

  CriteriaBuilderjakarta.persistence.criteria.CriteriaBuilder - JPA Interface
 Used to construct criteria queries, compound selections,
 expressions, predicates, orderings. cb = em.getCriteriaBuilderEntityManager.getCriteriaBuilder() - JPA Method
 Obtain an instance of CriteriaBuilder which may be
 used to construct CriteriaQuery objects.();

  CriteriaQueryjakarta.persistence.criteria.CriteriaQuery - JPA Interface
 The {@code CriteriaQuery} interface defines functionality that is
 specific to top-level queries.<Country> q = cb.createQueryCriteriaBuilder.createQuery(resultClass) - JPA Method
 Create a CriteriaQuery object with the given
 result type.(Country.class);
  Rootjakarta.persistence.criteria.Root - JPA Interface
 A root type in the from clause.<Country> c = q.fromAbstractQuery.from(entityClass) - JPA Method
 Create and add a query root corresponding to the given entity,
 forming a cartesian product with any existing roots.(Country.class);
  ParameterExpressionjakarta.persistence.criteria.ParameterExpression - JPA Interface
 Type of criteria query parameter expressions.<Integer> p = cb.parameterCriteriaBuilder.parameter(paramClass) - JPA Method
 Create a parameter expression.(Integer.class);
  q.selectCriteriaQuery.select(selection) - JPA Method
 Specify the item that is to be returned in the query result.(c).whereCriteriaQuery.where(restriction) - JPA Method
 Modify the query to restrict the query result according
 to the specified boolean expression.(cb.gtCriteriaBuilder.gt(x,y) - JPA Method
 Create a predicate for testing whether the first argument is
 greater than the second.(c.getPath.get(attributeName) - JPA Method
 Create a path corresponding to the referenced attribute.("population"), p));

The ParameterExpressionjakarta.persistence.criteria.ParameterExpression - JPA Interface Type of criteria query parameter expressions. instance, p, is created to represent the query parameter. The whereCriteriaQuery.where(restriction) - JPA Method Modify the query to restrict the query result according to the specified boolean expression. method sets the WHERE clause. As shown above, The CriteriaQueryjakarta.persistence.criteria.CriteriaQuery - JPA Interface The {@code CriteriaQuery} interface defines functionality that is specific to top-level queries. interface supports method chaining. See the links in the next sections of this page for detailed explanations on how to set criteria query clauses and build criteria expressions.

Running this query requires setting the parameter:

  TypedQueryjakarta.persistence.TypedQuery - JPA Interface
 Interface used to control the execution of typed queries.<Country> query = em.createQueryEntityManager.createQuery(criteriaQuery) - JPA Method
 Create an instance of TypedQuery for executing a
 criteria query.(q);
  query.setParameterQuery.setParameter(param,value) - JPA Method
 Bind the value of a {@code Parameter} object.(p, 10000000);
  List<Country> results = query.getResultListQuery.getResultList() - JPA Method
 Execute a SELECT query and return the query results as an untyped
 List.();

The setParameterQuery.setParameter(param,value) - JPA Method Bind the value of a {@code Parameter} object. method takes a Parameterjakarta.persistence.Parameter - JPA Interface Type for query parameter objects. (or a ParameterExpressionjakarta.persistence.criteria.ParameterExpression - JPA Interface Type of criteria query parameter expressions.) instance as the first argument instead of a name or a position (which are used with string based JPQL parameters).

Criteria Query Structure

Queries in JPA (as in SQL) are composed of clauses. Because JPQL queries and criteria queries use equivalent clauses - they are explained side by side in the Query Structure pages.

Specific details about criteria query clauses are provided in the following page sections:

• SELECT clause (selectCriteriaQuery.select(selection) - JPA Method Specify the item that is to be returned in the query result., distinctCriteriaQuery.distinct(distinct) - JPA Method Specify whether duplicate query results are eliminated., multiselectCriteriaQuery.multiselect(selections) - JPA Method Specify the selection items that are to be returned in the query result., arrayCriteriaBuilder.array(selections) - JPA Method Create an array-valued selection item., tupleCriteriaBuilder.tuple(selections) - JPA Method Create a tuple-valued selection item., constructCriteriaBuilder.construct(resultClass,selections) - JPA Method Create a selection item corresponding to a constructor.).
• FROM clause (fromAbstractQuery.from(entityClass) - JPA Method Create and add a query root corresponding to the given entity, forming a cartesian product with any existing roots., joinFrom.join(attributeName,jt) - JPA Method Create a join to the specified attribute using the given join type., fetchFetchParent.fetch(attributeName) - JPA Method Create a fetch join to the specified attribute using an inner join.).
• WHERE clause (whereCriteriaQuery.where(restrictions) - JPA Method Modify the query to restrict the query result according to the conjunction of the specified restriction predicates.).
• GROUP BY / HAVING clauses (groupByCriteriaQuery.groupBy(grouping) - JPA Method Specify the expressions that are used to form groups over the query results., havingCriteriaQuery.having(restriction) - JPA Method Specify a restriction over the groups of the query., countCriteriaBuilder.count(x) - JPA Method Create an aggregate expression applying the count operation., sumCriteriaBuilder.sum(x) - JPA Method Create an aggregate expression applying the sum operation., avgCriteriaBuilder.avg(x) - JPA Method Create an aggregate expression applying the avg operation., minCriteriaBuilder.min(x) - JPA Method Create an aggregate expression applying the numerical min operation., maxCriteriaBuilder.max(x) - JPA Method Create an aggregate expression applying the numerical max operation., ...).
• ORDER BY clause (orderByCriteriaQuery.orderBy(o) - JPA Method Specify the ordering expressions that are used to order the query results., Orderjakarta.persistence.criteria.Order - JPA Interface An object that defines an ordering over the query results., ascCriteriaBuilder.asc(expression) - JPA Method Create an ordering by the ascending value of the expression., descCriteriaBuilder.desc(expression) - JPA Method Create an ordering by the descending value of the expression.).

The links above are direct links to the criteria query sections in pages that describe query structure in general, including in the context of string based JPQL queries.

Criteria Query Expressions

JPA query clauses are composed of expressions. Because JPQL queries and criteria queries use equivalent expressions - they are explained side by side in the Query Expressions pages.

Specific details about criteria query expressions are provided in the following page sections:

• Literals and Dates (literalCriteriaBuilder.literal(value) - JPA Method Create an expression for a literal., nullLiteralCriteriaBuilder.nullLiteral(resultClass) - JPA Method Create an expression for a null literal with the given type., currentDateCriteriaBuilder.currentDate() - JPA Method Create expression to return current date., ...).
• Paths, navigation and types (getPath.get(attributeName) - JPA Method Create a path corresponding to the referenced attribute., typePath.type() - JPA Method Create an expression corresponding to the type of the path.).
• Arithmetic expressions (sumCriteriaBuilder.sum(x,y) - JPA Method Create an expression that returns the sum of its arguments., diffCriteriaBuilder.diff(x,y) - JPA Method Create an expression that returns the difference between its arguments., prodCriteriaBuilder.prod(x,y) - JPA Method Create an expression that returns the product of its arguments., quotCriteriaBuilder.quot(x,y) - JPA Method Create an expression that returns the quotient of its arguments., modCriteriaBuilder.mod(x,y) - JPA Method Create an expression that returns the modulus (remainder under integer division) of its arguments., absCriteriaBuilder.abs(x) - JPA Method Create an expression that returns the absolute value of its argument., negCriteriaBuilder.neg(x) - JPA Method Create an expression that returns the arithmetic negation of its argument., sqrtCriteriaBuilder.sqrt(x) - JPA Method Create an expression that returns the square root of its argument.).
• String expressions (likeCriteriaBuilder.like(x,pattern) - JPA Method Create a predicate for testing whether the expression satisfies the given pattern., lengthCriteriaBuilder.length(x) - JPA Method Create expression to return length of a string., locateCriteriaBuilder.locate(x,pattern) - JPA Method Create expression to locate the position of one string within another, returning position of first character if found., lowerCriteriaBuilder.lower(x) - JPA Method Create expression for converting a string to lowercase., upperCriteriaBuilder.upper(x) - JPA Method Create expression for converting a string to uppercase., concatCriteriaBuilder.concat(x,y) - JPA Method Create an expression for string concatenation., substringCriteriaBuilder.substring(x,from) - JPA Method Create an expression for substring extraction., ...).
• Collection expressions (isEmptyCriteriaBuilder.isEmpty(collection) - JPA Method Create a predicate that tests whether a collection is empty., isNotEmptyCriteriaBuilder.isNotEmpty(collection) - JPA Method Create a predicate that tests whether a collection is not empty., isMemberCriteriaBuilder.isMember(elem,collection) - JPA Method Create a predicate that tests whether an element is a member of a collection., isNotMemberCriteriaBuilder.isNotMember(elem,collection) - JPA Method Create a predicate that tests whether an element is not a member of a collection., sizeCriteriaBuilder.size(collection) - JPA Method Create an expression that tests the size of a collection.).
• Comparison expressions (equalCriteriaBuilder.size(collection) - JPA Method Create an expression that tests the size of a collection., notEqualCriteriaBuilder.notEqual(x,y) - JPA Method Create a predicate for testing the arguments for inequality., gtCriteriaBuilder.gt(x,y) - JPA Method Create a predicate for testing whether the first argument is greater than the second., geCriteriaBuilder.ge(x,y) - JPA Method Create a predicate for testing whether the first argument is greater than or equal to the second., ltCriteriaBuilder.lt(x,y) - JPA Method Create a predicate for testing whether the first argument is less than the second., leCriteriaBuilder.le(x,y) - JPA Method Create a predicate for testing whether the first argument is less than or equal to the second., betweenCriteriaBuilder.between(v,x,y) - JPA Method Create a predicate for testing whether the first argument is between the second and third arguments in value., isNullCriteriaBuilder.isNull(x) - JPA Method Create a predicate to test whether the expression is null., ...)
• Logical expressions (andCriteriaBuilder.and(x,y) - JPA Method Create a conjunction of the given boolean expressions., orCriteriaBuilder.or(x,y) - JPA Method Create a disjunction of the given boolean expressions., notCriteriaBuilder.not(restriction) - JPA Method Create a negation of the given restriction., isTrueCriteriaBuilder.isTrue(x) - JPA Method Create a predicate testing for a true value.).

The links above are direct links to the criteria query sections in pages that describe expressions in general, including in the context of string based JPQL queries.