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

Component	Purpose
EntityManager	Entry point to interact with persistence context
CriteriaBuilder	Creates query elements and conditions
CriteriaQuery<T>	Represents the query definition
Root<T>	Represents the entity (FROM clause)
Predicate	Represents WHERE conditions

---

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

Feature	Criteria API	JPQL
Query type	Java-based, object-oriented	String-based, similar to SQL
Type safety	Checked at compile-time	Checked at runtime only
Dynamic queries	Easy to build dynamic conditions	Harder; requires string concatenation
Readability	Verbose, more boilerplate	Simple and concise
Error detection	Compile-time errors caught early	Runtime errors (e.g., typos in field names)

---

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.