Introduction to HQL

HQL (Hibernate Query Language) is Hibernate's object-oriented query language. It looks similar to SQL but operates on entity classes and their mapped properties rather than database tables and columns. In Hibernate 6, HQL is parsed by the SQM (Semantic Query Model) engine, which provides better validation and improved JPQL compliance.

Key differences from SQL:

Basic HQL examples:

// Select all orders (uses entity name, not table name)
List orders = session.createQuery(
    "FROM Order WHERE status = :status", Order.class)
    .setParameter("status", OrderStatus.PENDING)
    .getResultList();

// JOIN via association path (no explicit ON clause)
List orders = session.createQuery(
    "SELECT o FROM Order o JOIN o.customer c WHERE c.city = :city", Order.class)
    .setParameter("city", "London")
    .getResultList();

// Aggregate
Long count = session.createQuery(
    "SELECT COUNT(o) FROM Order o WHERE o.status = :status", Long.class)
    .setParameter("status", OrderStatus.SHIPPED)
    .getSingleResult();

JPQL vs HQL: JPQL is the JPA standard subset; HQL is Hibernate's superset that adds features like INSERT ... SELECT, collection functions, and additional aggregate functions. All valid JPQL is valid HQL.

Hibernate 6 improvement: HQL now supports SELECT without FROM for scalar expressions, and the SQM engine catches type mismatches and invalid property names at parse time rather than at runtime.

HQL handles associations and joins using object navigation paths rather than explicit table join conditions. Because Hibernate already knows the relationship structure from your entity mappings, you traverse associations using dot notation or the JOIN keyword.

Implicit join (dot navigation):

SELECT o FROM Order o WHERE o.customer.city = 'London'

Hibernate generates the necessary JOIN SQL automatically.

Explicit JOIN:

SELECT a FROM Author a JOIN a.books b WHERE b.genre = :genre

This joins the Author and Book entities via the books collection mapping.

JOIN FETCH — most important for interviews:

SELECT a FROM Author a JOIN FETCH a.books WHERE a.id = :id

JOIN FETCH initialises the collection in the same SQL query, preventing LazyInitializationException and the N+1 problem.

LEFT JOIN / LEFT JOIN FETCH:

SELECT a FROM Author a LEFT JOIN FETCH a.books

Returns authors even when they have no books (outer join semantics).

Full example with parameters:

List authors = session.createQuery(
    "SELECT DISTINCT a FROM Author a " +
    "JOIN FETCH a.books b " +
    "WHERE b.publicationYear > :year",
    Author.class)
    .setParameter("year", 2020)
    .getResultList();

Note DISTINCT is used here to deduplicate authors when a JOIN FETCH on a collection multiplies rows.

Key differences from SQL joins:

• You join on association names (e.g., a.books), not table names with ON clauses.
• The join condition (foreign key mapping) is already encoded in the @JoinColumn or @JoinTable annotation — no need to repeat it in HQL.
• HQL supports INNER JOIN, LEFT JOIN, CROSS JOIN, and JOIN FETCH; RIGHT JOIN has limited support.

HQL's INSERT support is limited to INSERT ... SELECT — you cannot insert literal values directly the way you can in SQL. HQL does not support INSERT INTO ... VALUES (...).

Syntax:

INSERT INTO TargetEntity (field1, field2, ...)
SELECT sourceField1, sourceField2, ...
FROM SourceEntity [WHERE condition]

Example — copy active products to an archive table:

int inserted = session.createMutationQuery(
    "INSERT INTO ArchivedProduct (name, price, archivedAt) " +
    "SELECT p.name, p.price, CURRENT_TIMESTAMP " +
    "FROM Product p WHERE p.active = false")
    .executeUpdate();

Note: In Hibernate 6 the preferred API for DML is createMutationQuery() rather than the older createQuery().executeUpdate().

Rules and restrictions:

• The target entity must have an @Id field. If the ID is not included in the SELECT, the ID generator is not invoked — you must include the id value explicitly from the source query, or the insert will fail.
• Auto-generated @Version fields are set to their initial value (0 or equivalent) automatically.
• Only persistent entity classes can be used; you cannot INSERT INTO a native SQL table name.

When to use: Primarily for bulk data migration, archiving, or copying records between entities with matching shapes. For inserting new objects from the application layer, always use session.persist(entity) — it supports ID generation, lifecycle callbacks, and cascade operations.

Interview follow-up: To insert individual records, use:

Product p = new Product("Widget", new BigDecimal("9.99"));
session.persist(p);  // replaces deprecated session.save()

HQL's UPDATE statement performs bulk updates directly in the database without loading entities into the persistence context. It is ideal for modifying many rows at once efficiently.

Syntax:

UPDATE EntityName SET property1 = :value1 [, property2 = :value2 ...] [WHERE condition]

Example:

int updatedCount = session.createMutationQuery(
    "UPDATE Product p SET p.price = p.price * 1.10 WHERE p.category = :cat")
    .setParameter("cat", "Electronics")
    .executeUpdate();

Hibernate 6 API: Use createMutationQuery() for DML statements (replaces the older createQuery(...).executeUpdate() pattern).

Important caveats:

1. Bypasses the persistence context — Entities already loaded in the session are NOT updated in memory. After a bulk UPDATE, call session.clear() or re-fetch entities to avoid stale data.

2. No dirty checking or lifecycle callbacks — @PreUpdate listeners and @Version increment do NOT fire for bulk HQL updates. If you use optimistic locking, include the version field manually:

   UPDATE Product SET price = :price, version = version + 1
   WHERE id = :id AND version = :expectedVersion
   

3. No cascade — Cascaded operations defined on associations are not triggered.

When to use bulk HQL UPDATE vs. loading entities:

• Bulk HQL: updating hundreds/thousands of rows efficiently
• Load-then-modify: when you need lifecycle callbacks, cascades, or only a few entities

Example with multiple parameters:

session.createMutationQuery(
    "UPDATE Employee e SET e.salary = :newSalary, e.updatedAt = CURRENT_TIMESTAMP " +
    "WHERE e.department.id = :deptId AND e.salary < :threshold")
    .setParameter("newSalary", 60000)
    .setParameter("deptId", 5L)
    .setParameter("threshold", 50000)
    .executeUpdate();

HQL's DELETE statement performs bulk deletes directly in the database without loading entities into memory. It is more efficient than loading entities one by one and calling session.remove().

Syntax:

DELETE FROM EntityName [WHERE condition]

(FROM is optional — DELETE EntityName WHERE ... is also valid.)

Example:

int deletedCount = session.createMutationQuery(
    "DELETE FROM AuditLog a WHERE a.createdAt < :cutoff")
    .setParameter("cutoff", LocalDate.now().minusYears(2))
    .executeUpdate();

Hibernate 6 API: Use createMutationQuery() for DML statements.

Critical caveats:

1. Bypasses the persistence context — Entities already in the session cache are not evicted. Call session.clear() after a bulk delete if you might access those entities again in the same session.

2. No cascade — Associations annotated with cascade = CascadeType.REMOVE or orphanRemoval = true are not processed. If children exist and have a NOT NULL foreign key, the database will throw a constraint violation. Delete children first:

   // Delete children first
   session.createMutationQuery("DELETE FROM OrderLine ol WHERE ol.order.id = :orderId")
      .setParameter("orderId", orderId).executeUpdate();
   // Then delete parent
   session.createMutationQuery("DELETE FROM Order o WHERE o.id = :orderId")
      .setParameter("orderId", orderId).executeUpdate();
   

3. No lifecycle callbacks — @PreRemove and @PostRemove listeners do not fire.

When to prefer bulk DELETE: For large-scale cleanup operations (archiving, purging old records). For a handful of entities where cascades and callbacks matter, load them and call session.remove(entity) instead.