Hibernate Reference

This section documents Hibernate ORM 7.4.x (User Guide, Introduction, Query Language Guide, Data Repositories Guide), Jakarta Persistence 3.2, Hibernate Search 8.4.x, and the Hibernate Validator / Hibernate Reactive references — which are the references these pages are written and verified against.

This content was generated with the assistance of AI and should be verified against those official docs before being relied on in production.

Three older reference books were consulted as bibliography only while preparing these pages and are not the primary or main source for any page. All three predate Jakarta Persistence 3.2 and Hibernate ORM 6/7 (the javax.persistence → jakarta.persistence namespace change, the ORM 6 query-engine rewrite, the Hibernate Search 6+ Elasticsearch backend), so the official documentation above wins on any discrepancy.

This section’s bibliography lists the reference material consulted while preparing these pages.

Welcome to the Hibernate reference. Hibernate ORM is the reference implementation of Jakarta Persistence and the object/relational mapping engine most Java backend services build their data-access layer on. This section is framework-agnostic — plain Jakarta Persistence and native Hibernate, with Spring Boot wiring noted only where it matters — and goes considerably deeper than Hibernate (JPA & ORM)'s conceptual overview, which stays the right starting point for a first orientation before diving into this section.

If you are new to Hibernate, start with Getting Started, then Architecture and Entities and Identifiers, then work down the list or jump to what you need.

What’s covered

Getting started

Getting Started — Hibernate and Jakarta Persistence, adding Hibernate to a Maven/Gradle build, persistence.xml vs. programmatic bootstrap, a "Hello, Hibernate" example, and the most-used hibernate.properties settings.
Hibernate & Spring Boot Integration — how spring-boot-starter-data-jpa wires Hibernate in, why Spring Data JPA does not supersede Hibernate (a comparison table of what each layer is responsible for), Hibernate’s own limitations inside a Spring Boot application, and where database model evolution is tracked.

Architecture & domain model

Architecture — the object/relational paradigm mismatch in depth, Hibernate’s layered architecture, SessionFactory/Session vs. EntityManagerFactory/EntityManager, StatelessSession, persistence units, and dialects.
Entities and Identifiers — @Entity/@Table, access strategies, @GeneratedValue strategies, composite keys, @NaturalId, @MapsId, and equals()/hashCode() guidance.
Basic and Embeddable Types — @Basic, @Enumerated, AttributeConverter, @Embeddable/@Embedded, JSON/LOB mapping, geospatial types with Hibernate Spatial, java.time and time zones, @Nationalized, and @Immutable.
Associations — @ManyToOne, @OneToMany, @OneToOne, @ManyToMany, owning vs. inverse side, bidirectional sync, cascading, orphan removal, and @OnDelete.
Collections — List/Set/Map/sorted collections, @ElementCollection, ordering annotations, bag vs. list semantics, and SQL array columns.
Inheritance Mapping — SINGLE_TABLE, JOINED, TABLE_PER_CLASS, @MappedSuperclass, and polymorphic query cost.

The persistence context

Persistence Context and Lifecycle — the identity map and first-level cache, the four entity states, EntityManager operations, merge() semantics, and cascading/exception handling.
Flushing and Dirty Checking — automatic dirty checking, flush modes, auto-flush, flush ordering, and @DynamicUpdate/@DynamicInsert.
Transactions — resource-local vs. JTA, the Hibernate transaction API, session-per-request, and rollback interaction with the persistence context.
Locking — optimistic locking with @Version, @OptimisticLocking, pessimistic locking modes, and lock scope/timeout hints.
Fetching and N+1 — lazy vs. eager, proxies and bytecode enhancement, JOIN FETCH, entity graphs, @BatchSize, subselect fetching, and DTO projections.

Querying

HQL and JPQL — statement types, joins, functions, SELECT new projections, set operations, aggregation, the Query API, pagination, @NamedQuery, and scrolling/streaming.
Criteria API — CriteriaBuilder/CriteriaQuery/Root, the static metamodel, joins and fetch joins, SelectionSpecification/MutationSpecification, and composing dynamic queries.
Native SQL and Stored Procedures — createNativeQuery, @SqlResultSetMapping, @NamedNativeQuery, @Subselect/@Formula, and stored procedures.
Bulk Operations and Batching — JDBC batching, StatelessSession, bulk HQL UPDATE/DELETE/INSERT … SELECT, and the flush/clear loop.

Caching, events & advanced mapping

Second-Level Cache — providers, @Cache and CacheConcurrencyStrategy, the query cache, CacheMode/SharedCacheMode, and cache regions/statistics.
Events, Interceptors, and Filters — JPA lifecycle callbacks, the Hibernate Interceptor, the native event system and Integrator, dynamic filters, and soft delete.
Schema Generation and Tooling — hibernate.hbm2ddl.auto, import.sql, DDL-generation annotations, build plugins, and Hibernate Tools.
Envers Auditing — @Audited, _AUD tables, AuditReader, custom revision entities, and ValidityAuditStrategy.
Multitenancy — separate-database, separate-schema, and discriminator-column strategies.

Performance & the wider Hibernate ecosystem

Performance and Statistics — the performance checklist, the Statistics API, the slow-query log, JFR events, and common anti-patterns.
Integration Testing with Hibernate — bootstrapping a test SessionFactory, in-memory databases and their limits, parameterized tests across multiple database engines, and Testcontainers with Docker images.
Hibernate Search Fundamentals — @Indexed, field annotations, analyzers, automatic vs. explicit indexing, the search DSL, fuzzy matching, ID/score projections completed with a database query, faceting with aggregations, and geospatial search.
Hibernate Search Analyzers — defining custom analyzers (language-specific stemming, n-grams/edge n-grams for autocomplete), and handling content whose language varies per document.
Hibernate Search Backends — the embedded Lucene backend vs. Elasticsearch/OpenSearch, coordination strategies, and sync/async indexing.
Integration Testing with Hibernate Search — the Lucene backend’s in-memory directory for fast tests, testing analyzers/queries/faceting/projections, and Testcontainers with a real Elasticsearch/OpenSearch image.
Hibernate Reactive and Data Repositories — Mutiny.SessionFactory, the Vert.x Context binding, bridging to Reactor, and Hibernate Data Repositories.
Validation with Hibernate Validator — built-in constraints, @Valid cascading, custom validators, and JPA/Spring MVC integration.

Reference

Cheat Sheet — a one-page, downloadable PDF summary of the essentials above for quick memorization.

Bibliography

Official documentation (primary source for every page)

hibernate.org/orm/documentation — the Hibernate ORM project’s own documentation index.
Hibernate ORM 7.4 — Introduction.
Hibernate ORM 7.4 — User Guide — the primary reference for the great majority of pages in this section (architecture, mapping, the persistence context, locking, fetching, caching, events, schema generation, Envers, multitenancy, and performance).
Hibernate ORM 7.4 — Query Language Guide — the primary source for HQL and JPQL and Criteria API.
Hibernate ORM 7.4 — Data Repositories Guide — Jakarta Data support, covered in Hibernate Reactive and Data Repositories.
Jakarta Persistence 3.2 Specification.
Hibernate ORM 7.4 — Migration Guide and Hibernate ORM — Releases (what’s new).
Hibernate ORM 7.4 — Javadoc.
Hibernate Search 8.4 — Reference Documentation and Hibernate Search — Getting Started — the primary source for Hibernate Search Fundamentals and Hibernate Search Backends.
Hibernate Validator — Reference Guide and Jakarta Validation 3.1 Specification — the primary source for Validation with Hibernate Validator.
Hibernate Tools.
Spring Boot — JPA and Spring Data — Spring Boot wiring context, referenced from Getting Started and elsewhere in this section.
Hibernate Reactive — Reference Documentation — the primary source for the Hibernate Reactive portion of Hibernate Reactive and Data Repositories.
SmallRye Mutiny — Using other reactive programming libraries and the io.smallrye.reactive:mutiny-reactor artifact it documents (the Uni/Multi <→ Mono/Flux bridge).
Hantsy Bai — Integrating Hibernate Reactive with Spring (Spring bean wiring precedent).
HSEARCH-4922 and the Hibernate team’s own confirmation on the Hibernate community forum — the citation that Hibernate Search does not support Hibernate Reactive.

Local books (bibliography only — consulted while preparing these pages, not the primary source for any page; all three predate Jakarta Persistence 3.2 and Hibernate ORM 6/7, so on any discrepancy the official documentation above wins)

Bauer, Christian, Gavin King, and Gary Gregory. Java Persistence with Hibernate, 2nd ed. Manning Publications, 2016. ISBN 9781617290459. Consulted as part of the bibliography for this section — covers JPA 2.1 / javax.persistence, so it predates Jakarta Persistence 3.2 and Hibernate ORM 6/7. See the publisher’s book page and manning.com.
Peak, Patrick, and Nick Heudecker. Hibernate Quickly. Manning Publications, 2006. ISBN 978-1-932394-41-2. Consulted as part of the bibliography for this section — covers Hibernate 3 with XML (hbm.xml) mapping; retained only for its conceptual treatment of the ORM paradigm mismatch and the DAO pattern. See the publisher’s book page and manning.com.
Bernard, Emmanuel, and John Griffin. Hibernate Search in Action. Manning Publications, 2009. ISBN 978-1-933988-64-1. Consulted as part of the bibliography for this section — predates modern Hibernate Search 6/7 (Elasticsearch backend, jakarta.*). See the publisher’s book page and manning.com.