The Ultimate Guide to Hibernate 7 Criteria Queries: Master Dynamic, Type-Safe Persistence

Writing dynamic queries with string-based HQL is fragile. One typo, one missing space, and your application fails at runtime. In enterprise applications—where filters change based on user input—this often turns into a mess of concatenated strings that are hard to test and harder to maintain.

Hibernate 7’s Criteria API solves this by letting you build queries programmatically using a type-safe, refactoring-friendly API. With alignment to Jakarta Persistence 3.2+ and Hibernate 7’s improved Semantic Query Model (SQM), Criteria queries are now more predictable and production-ready than ever.

In this guide, we’ll walk through Criteria Queries step by step—from basic selection to joins, analytics, and bulk operations—so you can confidently use them for real-world, dynamic data access.

Why the Criteria API Exists

In a typical enterprise application, search filters are rarely static. Users toggle checkboxes, select ranges, and combine conditions. Expressing this logic with raw HQL usually results in brittle string concatenation, runtime-only failures, and code that becomes impossible to refactor safely.

The Criteria API replaces query strings with a structured, object-based model. Instead of writing text, you assemble query parts using Java objects. This shifts many errors from runtime to compile time and makes your persistence layer safer and easier to evolve.

What Is the Hibernate Criteria API?

The Criteria API is a programmatic way to create queries. Instead of writing query strings, you use Java objects to define the structure of your search.

In Hibernate 7, this API is fully aligned with Jakarta Persistence 3.2+ and backed internally by the Semantic Query Model (SQM), which improves validation and SQL generation.

Why Use It in Hibernate 7?

Type Safety: Use the static metamodel to avoid hardcoding field names.
Dynamic Logic: Add WHERE clauses or JOINs based on runtime conditions.
Refactoring Friendly: Rename entity fields without silently breaking queries.
Early Validation: Hibernate 7 validates queries earlier in the lifecycle.

The Core Building Blocks

Before writing code, you must understand the three pillars of a Criteria query:

CriteriaBuilder – A factory for creating predicates, expressions, and ordering.
CriteriaQuery – The structure of the query (what you are selecting).
Root – The entity being queried (the FROM clause).

These pieces work together to describe the query tree that Hibernate later translates into SQL.

Setting the Stage: The Entity Model

To follow along, we’ll use a simple Employee and Department model. Hibernate 7 works seamlessly with standard Jakarta Persistence annotations.

@Entity
public class Employee {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String firstName;
    private String lastName;
    private Double salary;

    @ManyToOne(fetch = FetchType.LAZY)
    private Department department;

    // Getters and Setters
}

Step 1: Basic Selection (Select All)

We’ll start with the simplest case: fetching all records. This is equivalent to SELECT * FROM Employee.

try (Session session = sessionFactory.openSession()) {
    CriteriaBuilder cb = session.getCriteriaBuilder();
    CriteriaQuery<Employee> cr = cb.createQuery(Employee.class);
    Root<Employee> root = cr.from(Employee.class);

    cr.select(root);

    List<Employee> results = session.createQuery(cr).getResultList();
    results.forEach(e -> System.out.println(e.getFirstName()));
}

At this point, you’ve built a query tree using Java objects instead of strings.

Step 2: Adding Restrictions (The WHERE Clause)

This is where Criteria really starts to shine. Instead of stitching together text, you compose predicates.

CriteriaBuilder cb = session.getCriteriaBuilder();
CriteriaQuery<Employee> cr = cb.createQuery(Employee.class);
Root<Employee> root = cr.from(Employee.class);

Predicate salaryGreater = cb.gt(root.get("salary"), 50000);
Predicate nameLike = cb.like(root.get("lastName"), "D%");

cr.select(root)
  .where(cb.and(salaryGreater, nameLike))
  .orderBy(cb.asc(root.get("lastName")));

List<Employee> filtered = session.createQuery(cr).getResultList();

This approach is modular: you can build a list of predicates and apply them only if they are not null.

Step 3: True Type Safety with the Static Metamodel

Using root.get("salary") is better than raw HQL, but it’s still a string.

Hibernate can generate a static metamodel that lets you write:

cr.select(root)
  .where(cb.gt(root.get(Employee_.salary), 75000));

If salary is renamed to baseSalary, this code fails at compile time instead of crashing at runtime.

Step 4: Joins and Relationship Navigation

Criteria makes joins explicit and type-safe.

Join<Employee, Department> department = root.join(Employee_.department, JoinType.INNER);

cr.select(root)
  .where(cb.equal(department.get(Department_.name), "Engineering"));

If you want to fetch the association eagerly to avoid extra queries, use fetch() instead of join().

Step 5: Aggregations and Analytics

Criteria supports analytical queries for dashboards and reports.

CriteriaQuery<Double> avgQuery = cb.createQuery(Double.class);
Root<Employee> avgRoot = avgQuery.from(Employee.class);

avgQuery.select(cb.avg(avgRoot.get(Employee_.salary)));

Double averageSalary = session.createQuery(avgQuery).getSingleResult();

Step 6: Subqueries

Subqueries allow you to express nested logic in a type-safe way.

CriteriaQuery<Employee> mainQuery = cb.createQuery(Employee.class);
Root<Employee> empRoot = mainQuery.from(Employee.class);

Subquery<Double> sub = mainQuery.subquery(Double.class);
Root<Employee> subRoot = sub.from(Employee.class);
sub.select(cb.avg(subRoot.get(Employee_.salary)));

mainQuery.select(empRoot)
         .where(cb.gt(empRoot.get(Employee_.salary), sub));

List<Employee> highEarners = session.createQuery(mainQuery).getResultList();

Step 7: Bulk Updates and Deletes

Hibernate 7 integrates Criteria mutations with createMutationQuery() for predictable bulk operations.

Bulk Update

CriteriaUpdate<Employee> update = cb.createCriteriaUpdate(Employee.class);
Root<Employee> updRoot = update.from(Employee.class);

update.set(Employee_.salary, cb.prod(updRoot.get(Employee_.salary), 1.1))
      .where(cb.equal(updRoot.get(Employee_.department).get(Department_.name), "Sales"));

session.createMutationQuery(update).executeUpdate();

Bulk Delete

CriteriaDelete<Employee> delete = cb.createCriteriaDelete(Employee.class);
Root<Employee> delRoot = delete.from(Employee.class);

delete.where(cb.isNull(delRoot.get(Employee_.department)));

session.createMutationQuery(delete).executeUpdate();

Caution: Bulk mutations bypass the persistence context. Entities already loaded into memory will not be updated automatically.

What’s New in Hibernate 7 for Criteria

Hibernate 7 brings meaningful improvements to the Criteria API:

Earlier Validation: Queries are validated against your domain model at creation time.
Smarter SQL Translation: Better join optimization and function resolution.
Dialect Awareness: Uses JSON operators and window functions when supported.
Improved Type Safety: Stronger validation for constructor expressions and parameters.

These changes make Criteria queries both safer and more predictable in production.

When NOT to Use the Criteria API

Criteria is not always the best tool:

Static, human-readable queries (HQL is cleaner)
Reporting queries written once and rarely changed
Performance-tuned native SQL
Extremely complex joins that become unreadable in Criteria

Common Pitfalls and Performance Considerations

Even with Hibernate 7, a few sharp edges remain:

Verbosity: For very simple queries, Criteria is more code than HQL.
N+1 Risk: root.join() does not force eager loading. Use root.fetch() to avoid extra queries.
Parameter Binding: Always use CriteriaBuilder methods for values.
Metamodel Maintenance: Ensure your build regenerates _ classes when entities change.

HQL vs Criteria API

Use HQL for static, readable queries. Use Criteria only when query logic must be built dynamically at runtime.

Frequently Asked Questions

1. Is the Hibernate Criteria API deprecated in Hibernate 7?
No. The legacy org.hibernate.Criteria API was removed. The JPA Criteria API (jakarta.persistence.criteria) is the modern standard and fully supported.

2. How do I implement pagination?
Pagination is handled at the query level:

session.createQuery(cr)
       .setFirstResult(offset)
       .setMaxResults(limit)
       .getResultList();

3. Can I use native SQL functions?
Yes. Use cb.function("DATEDIFF", Integer.class, root.get(Employee_.hireDate), cb.currentDate()) to call any database-specific function. Hibernate passes the function name and arguments through to the generated SQL, so the function must exist in the target database.

Q4: How does the Criteria API compare to Querydsl?

Both solve the same problem — type-safe dynamic queries — but with different ergonomics. The JPA Criteria API is the standard (no extra dependencies) but is verbose. Querydsl generates its own Q-classes and provides a much more fluent, readable DSL. For new projects that need extensive dynamic querying, Querydsl is often easier to maintain. For Jakarta EE portability without extra dependencies, the Criteria API is the right choice.

Q5: How do I handle OR conditions in the Criteria API?

Use cb.or(predicate1, predicate2, ...). You can combine any number of predicates: cr.where(cb.or(cb.equal(root.get("status"), "ACTIVE"), cb.equal(root.get("status"), "PROBATION"))). For complex nested AND/OR logic, build your predicate list programmatically and pass it to cb.and() or cb.or() using the varargs overload, giving you full boolean expression power without string concatenation.

Conclusion

The Hibernate 7 Criteria API is your best tool when query logic must be constructed dynamically at runtime. It trades the brevity of HQL for compile-time safety, refactoring confidence, and modular predicate composition. Use the static metamodel to eliminate string-based field references, use root.fetch() instead of root.join() when you need the association data, and remember that Criteria mutations bypass the persistence context just like HQL bulk operations. Reserve HQL for static, human-readable queries and Criteria for dynamic, user-driven search scenarios — together, they cover every querying need a production Hibernate application will have.

@ankurm