The Java Persistence Criteria API is used to define dynamic queries through the construction of object-based
query definition objects, rather than use of the string-based approach of JPQL. The criteria API allows dynamic queries to be built programmatically offering better integration with the Java language than a string-based 4th GL approach.

The Criteria API has two modes, the type-restricted mode, and the non-typed mode. The type-restricted mode uses a set of JPA meta-model generated class to define the query-able attributes of a class, see Metamodel. The non-typed mode uses strings to reference attributes of a class.

The criteria API is only for dynamic queries, and cannot be used in meta-data or named queries. Criteria queries are dynamic queries, so are not as performant as static named queries, or even dynamic parametrized JPQL which may benefit from a parse cache in some JPA providers.

CriteriaBuilder is the main interface into the Criteria API. A CriteriaBuilder is obtained from an EntityManager or an EntityManagerFactory using the getCriteriaBuilder() API. CriteriaBuilder is used to construct CriteriaQuery objects and their expressions. The Criteria API currently only supports select queries.

CriteriaBuilder defines API to create CriteriaQuery objects:

createQuery() - Creates a CriteriaQuery.

createQuery(Class) - Creates a CriteriaQuery using generics to avoid casting the result class.

CriteriaQuery defines a database select query. A CriteriaQuery models all of the clauses of a JPQL select query.
Elements from one CriteriaQuery cannot be used in other CriteriaQuerys. A CriteriaQuery is used with the EntityManagercreateQuery() API to create a JPA Query.

CriteriaQuery defines the following clauses and options:

distinct(boolean) - Defines if the query should filter duplicate results (defaults to false). If a join to a collection relationship is used, distinct should be used to avoid duplicate results.

from(Class) - Defines and returns an element in the query's from clause for the entity class. At least one from element is required for the query to be valid.

from(EntityType) - Defines and returns an element in the query's from clause for the meta-model entity type. At least one from element is required for the query to be valid.

select(Selection) - Defines the query's select clause. If not set, the first root will be selected by default.

CriteriaBuildercriteriaBuilder=entityManager.getCriteriaBuilder();// Query for a List of objects.CriteriaQuerycriteriaQuery=criteriaBuilder.createQuery();Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.where(criteriaBuilder.greaterThan(employee.get("salary"),100000));Queryquery=entityManager.createQuery(criteriaQuery);List<Employee>result=query.getResultList();// Query for a single object.CriteriaQuerycriteriaQuery=criteriaBuilder.createQuery();Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.where(criteriaBuilder.equal(employee.get("id"),criteriaBuilder.parameter(Long.class,"id")));Queryquery=entityManager.createQuery(criteriaQuery);query.setParameter("id",id);Employeeresult2=(Employee)query.getSingleResult();// Query for a single data element.CriteriaQuerycriteriaQuery=criteriaBuilder.createQuery();Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.select(criteriaBuilder.max(employee.get("salary")));Queryquery=entityManager.createQuery(criteriaQuery);BigDecimalresult3=(BigDecimal)query.getSingleResult();// Query for a List of data elements.CriteriaQuerycriteriaQuery=criteriaBuilder.createQuery();Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.select(employee.get("firstName"));Queryquery=entityManager.createQuery(criteriaQuery);List<String>result4=query.getResultList();// Query for a List of element arrays.CriteriaQuerycriteriaQuery=criteriaBuilder.createQuery();Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.multiselect(employee.get("firstName"),employee.get("lastName"));Queryquery=entityManager.createQuery(criteriaQuery);List<Object[]>result5=query.getResultList();

A Selection defines what is selected by a query. A Selection can be any object expression, attribute expression, function, sub-select, constructor or aggregation function. An alias can be defined for a Selection using the alias() API.

The construct operator on CriteriaBuilder can be used with a class and values to return data objects from a criteria query. These will not be managed objects, and the class must define a constructor that matches the arguments and types. Constructor queries can be used to select partial data or reporting data on objects, and get back a class instance instead of an object array or tuple.

The query from clause defines what is being queried. The from clause is defined using the from API on CriteriaQuery. A Root object is return from from, which represent the object in the context of the query. A Root also implements From, and Path. From defines a variable in the from clause, and allows joins. Path defines any attribute value and allows traversal to nested attributes.

Rootemployee=criteriaQuery.from(Employee.class);

Criteria queries allow for multiple root level objects. Caution should be used when doing this, as it can result in Cartesian products of the two table. The where clause should ensure the two objects are joined in some way.

// Select the employees and the mailing addresses that have the same address.CriteriaBuildercriteriaBuilder=entityManager.getCriteriaBuilder();CriteriaQuerycriteriaQuery=criteriaBuilder.createQuery();Rootemployee=criteriaQuery.from(Employee.class);Rootaddress=criteriaQuery.from(MailingAddress.class);criteriaQuery.multiselect(employee,address);criteriaQuery.where(criteriaBuilder.equal(employee.get("address"),address.get("address"));Queryquery=entityManager.createQuery(criteriaQuery);List<Object[]>result=query.getResultList();

A join operation can be used on a From object to obtain a relationship to use in the query. join does not mean the relationships will be fetched, to also fetch the related objects in the result use the fetch operation instead.

The join operation can be used with OneToOne, ManyToOne, OneToMany, ManyToMany and ElementCollection mappings. When used with a collection relationship you can join the same relationship multiple times to query multiple independent values.

// All employees who work on both projects.Rootemployee=criteriaQuery.from(Employee.class);Joinp=employee.join("projects");Joinp2=employee.join("projects");criteriaQuery.where(criteriaBuilder.and(criteriaBuilder.equal(p.get("name"),projectName1),criteriaBuilder.equal(p2.get("name"),projectName2));

The fetch operation can be used on a From object to fetch the related objects in a single query. This avoids additional queries for each of the object's relationships, and ensures that the relationships have been fetched if they were LAZY.

Caution should be used in using a Fetch in the where clause as it can affect the data returned for the resulting object's relationships. Objects should normally always have the same data, no matter how they were queried, this is important for caching and consistency. This is only an issue if the alias is used in the where clause on a collection relationship to filter the related objects that will be fetched. This should not be done, but is sometimes desirable, in which case the query should ensure it has been set to BYPASS the cache.

By default join and fetch are INNER joins. This means that results that do not have the relationship will be filtered from the query results. To avoid this, a join can be defined as an OUTER join using the LEFT JoinType as an argument to the join or fetch operation.

The query order by clause defines how the query results will be ordered. The order by clause is defined using the orderBy API on CriteriaQuery. Only Order objects can be passed to orderBy, and are obtained from CriteriaBuilder using the asc or desc API.

// Order by the last and first names.Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.orderBy(criteriaBuilder.desc(employee.get("lastName")),criteriaBuilder.asc(employee.get("firstName")));

// Order by the last name, ignoring case.Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.orderBy(criteriaBuilder.asc(criteriaBuilder.upper(employee.get("lastName"))));

// Order by the address object (orders by its id).Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.orderBy(criteriaBuilder.asc(employee.get("address")));

The query group by clause allows for summary information to be computed on a set of objects. group by is normally used in conjunction with aggregation functions. The group by clause is defined using the groupBy API on CriteriaQuery with any valid Expression object.

// Select the average salaries grouped by city.Rootemployee=criteriaQuery.from(Employee.class);criteriaQuery.multiselect(criteriaBuilder.avg(employee.<Number>get("salary")),employee.get("address").get("city"));criteriaQuery.groupBy(employee.get("address").get("city"));

// Select the average salaries grouped by city, ordered by the average salary.Rootemployee=criteriaQuery.from(Employee.class);Expressionavg=criteriaBuilder.avg(employee.<Number>get("salary"));criteriaQuery.multiselect(avg,employee.get("address").get("city"));criteriaQuery.groupBy(employee.get("address").get("city"));criteriaQuery.orderBy(criteriaBuilder.asc(avg));

// Select employees and the count of their number of projects.Rootemployee=criteriaQuery.from(Employee.class);Expressionproject=employee.join("projects",JoinType.LEFT);criteriaQuery.multiselect(e,criteriaBuilder.count(project));criteriaQuery.groupBy(employee);

The query having clause allows for the results of a group by to be filtered. The having clause is defined using the having API on CriteriaQuery with any Predicate object.

// Select the average salaries grouped by city, only including cities with average salaries over 100000.Rootemployee=criteriaQuery.from(Employee.class);Expressionavg=criteriaBuilder.avg(employee.<Number>get("salary"));criteriaQuery.multiselect(avg,employee.get("address").get("city"));criteriaQuery.groupBy(employee.get("address").get("city"));criteriaQuery.having(criteriaBuilder.greaterThan(avg,100000));

CriteriaUpdate defines a database update query. A CriteriaUpdate models all of the clauses of a JPQL update query.
Elements from one CriteriaUpdate cannot be used in other CriteriaUpdates. A CriteriaUpdate is used with the EntityManagercreateQuery() API to create a JPA Query. Criteria updates should only be used for batch updates. For regular updates to objects, the objects should be read through the EntityManager in a transaction an modified in Java, and have the changes committed.

CriteriaBuildercriteriaBuilder=entityManager.getCriteriaBuilder();// Updates the salary to 90,000 of all Employee's making more than 100,000.CriteriaUpdateupdate=criteriaBuilder.createCriteriaUpdate(Employee.class);Rootemployee=update.from(Employee.class);update.set("salary",90000);update.where(criteriaBuilder.greaterThan(employee.get("salary"),100000));Queryquery=entityManager.createQuery(update);introwCount=query.executeUpdate();// Gives all Employees a 10% raise.CriteriaUpdateupdate=criteriaBuilder.createCriteriaUpdate(Employee.class);Rootemployee=update.from(Employee.class);update.set(employee.get("salary"),criteriaBuilder.sum(employee.get("salary"),criteriaBuilder.quot(employee.get("salary"),10));Queryquery=entityManager.createQuery(update);introwCount=query.executeUpdate();

CriteriaDelete defines a database delete query. A CriteriaDelete models all of the clauses of a JPQL delete query.
Elements from one CriteriaDelete cannot be used in other CriteriaDelete. A CriteriaDelete is used with the EntityManagercreateQuery() API to create a JPA Query. CriteriaDelete should only be used for batch deletes. For regular deletes of objects, the objects should be read through the EntityManager in a transaction and deleted through the remove() API, and have the changes committed.

CriteriaDelete defines the following clauses and options:

where(Expression), where(Predicate...) - Defines the delete's where clause. By default all instances of the class are deleted.

The Expressions, Predicates elements are defined using the CriteriaBuilder API and expressions derived from the fromRoot elements.

CriteriaBuildercriteriaBuilder=entityManager.getCriteriaBuilder();// Deletes all Employee's making more than 100,000.CriteriaDeletedelete=criteriaBuilder.createCriteriaDelete(Employee.class);Rootemployee=delete.from(Employee.class);delete.where(criteriaBuilder.greaterThan(employee.get("salary"),100000));Queryquery=entityManager.createQuery(delete);introwCount=query.executeUpdate();// Deletes all Employees.CriteriaDeletedelete=criteriaBuilder.createCriteriaDelete(Employee.class);Rootemployee=delete.from(Employee.class);Queryquery=entityManager.createQuery(delete);introwCount=query.executeUpdate();

The where clause is normally the main part of the query as it defines the conditions (predicates) that filter what is returned. The where clause is defined using the where API on CriteriaQuery with any Predicate objects. A Predicate is obtained using a comparison operation, or a logical operation on CriteriaBuilder. The isNull, isNotNull, and in operations can also be called on Expression. The not operation can also be called on Predicate

Subqueries can only be used in the where clause and having clause. A subQuery is created from a CriteriaQuery using the subQuery operation. Most subQuery usage restricts the subQuery to returning a single result and value, unless used with the CriteriaBuilderexists, all, any, or some operations, or with an in operation.

CriteriaBuildercriteriaBuilder=entityManager.getCriteriaBuilder();// Find all manager that only manage below-average employees.CriteriaQuerycriteriaQuery=criteriaBuilder.createQuery();Rootemployee=criteriaQuery.from(Employee.class);SubquerysubQuery=criteriaQuery.subquery(Employee.class);Rootemployee_2=subQuery.from(Employee.class);subQuery.where(criteriaBuilder.and(employee_2.get("manager").equal(e),criteriaBuilder.equal(employee_2.get("productivity"),"below average").not());criteriaQuery.where(criteriaBuilder.exists(subQuery).not());Queryquery=entityManager.createQuery(criteriaQuery)List<Employee>=query.getResultList();// Find the employee with the lowest salary.CriteriaQuerycriteriaQuery=criteriaBuilder.createQuery();Rootemployee=criteriaQuery.from(Employee.class);SubquerysubQuery=criteriaQuery.subquery(Employee.class);Rootemployee_2=subQuery.from(Employee.class);subQuery.select(employee_2.get("salary"));criteriaQuery.where(criteriaBuilder.lessThan(employee.get("salary"),criteriaBuilder.all(subQuery)));Queryquery=entityManager.createQuery(criteriaQuery)List<Employee>=query.getResultList();

Parameters can be defined using the parameter API on CriteriaBuilder. JPA defines named parameters, and positional parameters. For named parameters the parameter type and name are specified.
For positional parameters only the parameter type is specified. Positional parameters start at position 1 not 0.

Several database functions are supported by the Criteria API. All supported functions are defined on CriteriaBuilder.
Some functions may not be supported by some databases, if they are not SQL compliant, and offer no equivalent function.

The Criteria API defines several special operations that are not database functions, but have special meaning in JPA. Some of these operations are defined on CriteriaBuilder and some are on specific Expression interfaces.

JPA defines a meta-model that can be used at runtime to query information about the ORM mapping meta-data. The meta-model includes the list of mapped attributes for a class, and their mapping types and cardinality. The meta-model can be used with the Criteria API in place of using strings to reference the class attributes.

JPA defines a set of _ classes that are to be generated by the JPA provider, or IDE, that give compile time access to the meta-model. This allows typed static variables to be used in the Criteria API. This can reduce the occurrence of typos, or invalid queries in application code, by catching query issues at compile time, instead of during testing. It does however add complexity to the development process, as the meta-model static class needs to be generated, and be part of the development cycle.

A Tuple defines a multi-select query result. Normally an object array is returned by JPA multi-select queries, but an object array is not a very useful data structure. A Tuple is a map-like structure that allows the results to be retrieved by name or index.