Criteria API

When applications require dynamic, complex, and type-safe queries, derived queries or JPQL strings are often insufficient.

The Criteria API solves this by allowing queries to be built programmatically using Java code instead of string-based JPQL.

What is Criteria API?

The Criteria API is a Java-based query-building mechanism provided by JPA.

Instead of writing queries as strings (JPQL/SQL), queries are constructed step by step using Java objects, making them:

• Type-safe
• Dynamic
• Less error-prone
• Easier to maintain in large applications

Why Use Criteria API?

Use Criteria API when:

• Queries are dynamic (conditions added at runtime)
• Multiple optional filters are involved
• Type safety is required (compile-time checking)
• JPQL strings become too complex
• Used in advanced search & reporting features

Core Components

Basic Flow of Criteria API

1. Get EntityManager
2. Obtain CriteriaBuilder
3. Create CriteriaQuery
4. Define entity Root
5. Add conditions using Predicate
6. Execute the query

This flow allows incremental and conditional query building.

Basic Example of Criteria API

CriteriaBuildercb= entityManager.getCriteriaBuilder();
CriteriaQuery<User> cq = cb.createQuery(User.class);
Root<User> user = cq.from(User.class);

cq.select(user)
  .where(cb.equal(user.get("status"),"ACTIVE"));

List<User> users = entityManager.createQuery(cq).getResultList();

Here,

• CriteriaBuilder → Builds query parts
• CriteriaQuery → Defines what to fetch
• Root<User> → Refers to the User entity
• Predicate → Applies filtering
• EntityManager → Executes the query

Dynamic Queries with Criteria API

The Criteria API is very powerful for building type-safe, dynamic queries. Unlike JPQL, you can conditionally add query restrictions at runtime.

Example: Dynamic search filters

CriteriaBuildercb= entityManager.getCriteriaBuilder();
CriteriaQuery<User> cq = cb.createQuery(User.class);
Root<User> user = cq.from(User.class);

List<Predicate> predicates =newArrayList<>();

if (status !=null) {
    predicates.add(cb.equal(user.get("status"), status));
}

if (minAge !=null) {
    predicates.add(cb.greaterThan(user.get("age"), minAge));
}

// Apply predicates only if they exist
cq.where(predicates.toArray(newPredicate[0]));

TypedQuery<User> query = entityManager.createQuery(cq);
List<User> result = query.getResultList();

• Predicates are added only if the value exists, making it ideal for search forms or filtering.
• CriteriaBuilder provides methods like equal, greaterThan, lessThan, like, etc.

Sorting with Criteria API

You can define order dynamically:

// Ascending order by name
cq.orderBy(cb.asc(user.get("name")));

// Descending order by creation date
cq.orderBy(cb.desc(user.get("createdDate")));

• Sorting can also be conditional, e.g., based on user input.
• Multiple sorting criteria can be applied:

cq.orderBy(cb.asc(user.get("name")), cb.desc(user.get("createdDate")));

Pagination with Criteria API

Pagination can be applied using TypedQuery:

TypedQuery<User> query = entityManager.createQuery(cq);

query.setFirstResult(0);// Offset (starting row)
query.setMaxResults(10);// Limit (page size)

List<User> users = query.getResultList();

• setFirstResult(offset) → skips rows before returning results.
• setMaxResults(limit) → controls the number of rows fetched.
• Works seamlessly with dynamic queries for paged search results.

Criteria API vs JPQL

When Should You Use Criteria API?

Use Criteria API when:

• Queries are dynamic (conditions vary at runtime)
• Multiple optional filters exist
• Working on enterprise-level applications
• Building advanced search or reporting features

Avoid Criteria API when:

• Queries are simple or static
• Readability is a priority
• Derived queries or @Query annotations are sufficient

Best Practices

• Use Derived Queries for simple CRUD or filtering logic.
• Use JPQL for fixed, readable queries.
• Use Criteria API only for complex or dynamic query cases.
• Encapsulate Criteria logic in custom repository implementations to keep your code clean.

Real-World Use Cases

• Advanced search screens with multiple optional filters
• Filter-based dashboards with dynamic sorting and conditions
• Reporting modules requiring aggregation and conditional logic
• Admin panels with flexible query parameters

Conclusion

• Criteria API allows building queries using Java code, not strings.
• Ideal for dynamic and complex queries that change at runtime.
• Provides type safety, reducing runtime errors.
• Best suited for advanced JPA scenarios where flexibility and maintainability are important.