Chapter 3. Hibernate Annotations

3.1. Hibernate Annotations

The org.hibernate.annotations package contains some annotations which are offered by Hibernate, on top of the standard JPA annotations.

Table 3.1. General Annotations
Annotation	Description
`Check`	Arbitrary SQL check constraints which can be defined at the class, property or collection level.
`Immutable`	Mark an Entity or a Collection as immutable. No annotation means the element is mutable. An immutable entity may not be updated by the application. Updates to an immutable entity will be ignored, but no exception is thrown. `@Immutable` placed on a collection makes the collection immutable, meaning additions and deletions to and from the collection are not allowed. A `HibernateException` is thrown in this case.

Table 3.2. Caching Entities
Annotation	Description
`Cache`	Add caching strategy to a root entity or a collection.

Table 3.3. Collection Related Annotations
Annotation	Description
`MapKeyType`	Defines the type of key of a persistent map.
`ManyToAny`	Defines a `ToMany` association pointing to different entity types. Matching the entity type is done through a metadata discriminator column. This kind of mapping should be only marginal.
`OrderBy`	Order a collection using SQL ordering (not HQL ordering).
`OnDelete`	Strategy to use on collections, arrays and on joined subclasses delete. `OnDelete` of secondary tables is currently not supported.
`Persister`	Specify a custom persister.
`Sort`	Collection sort (Java level sorting).
`Where`	Where clause to add to the element Entity or target entity of a collection. The clause is written in SQL.
`WhereJoinTable`	Where clause to add to the collection join table. The clause is written in SQL.

Table 3.4. Custom SQL for CRUD Operations
Annotation	Description
`Loader`	Overwrites Hibernate default `FIND` method.
`SQLDelete`	Overwrites the Hibernate default `DELETE` method.
`SQLDeleteAll`	Overwrites the Hibernate default `DELETE ALL` method.
`SQLInsert`	Overwrites the Hibernate default `INSERT INTO` method.
`SQLUpdate`	Overwrites the Hibernate default `UPDATE` method.
`Subselect`	Maps an immutable and read-only entity to a given SQL subselect expression.
`Synchronize`	Ensures that auto-flush happens correctly and that queries against the derived entity do not return stale data. Mostly used with `Subselect`.

Table 3.5. Entity
Annotation	Description
`Cascade`	Apply a cascade strategy on an association.
`Entity`	Adds additional metadata that may be needed beyond what is defined in the standard `@Entity`. `mutable`: whether this entity is mutable or not `dynamicInsert`: allow dynamic SQL for inserts `dynamicUpdate`: allow dynamic SQL for updates `selectBeforeUpdate`: Specifies that Hibernate should never perform an SQL UPDATE unless it is certain that an object is actually modified. `polymorphism`: whether the entity polymorphism is of PolymorphismType.IMPLICIT (default) or PolymorphismType.EXPLICIT `optimisticLock`: optimistic locking strategy (OptimisticLockType.VERSION, OptimisticLockType.NONE, OptimisticLockType.DIRTY or OptimisticLockType.ALL) Note The annotation "Entity" is deprecated and scheduled for removal in future releases. Its individual attributes or values should become annotations.
`Polymorphism`	Used to define the type of polymorphism Hibernate will apply to entity hierarchies.
`Proxy`	Lazy and proxy configuration of a particular class.
`Table`	Complementary information to a table either primary or secondary.
`Tables`	Plural annotation of Table.
`Target`	Defines an explicit target, avoiding reflection and generics resolving.
`Tuplizer`	Defines a tuplizer for an entity or a component.
`Tuplizers`	Defines a set of tuplizers for an entity or a component.

Table 3.6. Fetching
Annotation	Description
`BatchSize`	Batch size for SQL loading.
`FetchProfile`	Defines the fetching strategy profile.
`FetchProfiles`	Plural annotation for `@FetchProfile`.
`LazyGroup`	Specifies that an entity attribute should be fetched along with all the other attributes belonging to the same group. In order to load entity attributes lazily, bytecode enhancement is needed. By default, all non-collection attributes are loaded in one group named `DEFAULT`. This annotation allows defining different groups of attributes to be initialized together when accessing one attribute in the group.

Table 3.7. Filters
Annotation	Description
`Filter`	Adds filters to an entity or a target entity of a collection.
`FilterDef`	Filter definition.
`FilterDefs`	Array of filter definitions.
`FilterJoinTable`	Adds filters to a join table collection.
`FilterJoinTables`	Adds multiple `@FilterJoinTable` to a collection.
`Filters`	Adds multiple `@Filter`.
`ParamDef`	A parameter definition.

Table 3.8. Primary Keys
Annotation	Description
`Generated`	This annotated property is generated by the database.
`GenericGenerator`	Generator annotation describing any kind of Hibernate generator in a detyped manner.
`GenericGenerators`	Array of generic generator definitions.
`NaturalId`	Specifies that a property is part of the natural id of the entity.
`Parameter`	Key/value pattern.
`RowId`	Support for `ROWID` mapping feature of Hibernate.

Table 3.9. Inheritance
Annotation	Description
`DiscriminatorFormula`	Discriminator formula to be placed at the root entity.
`DiscriminatorOptions`	Optional annotation to express Hibernate specific discriminator properties.
`MetaValue`	Maps a given discriminator value to the corresponding entity type.

Table 3.10. Mapping JP-QL/HQL Queries
Annotation	Description
`NamedNativeQueries`	Extends `NamedNativeQueries` to hold Hibernate NamedNativeQuery objects.
`NamedNativeQuery`	Extends `NamedNativeQuery` with Hibernate features.
`NamedQueries`	Extends `NamedQueries` to hold Hibernate `NamedQuery` objects.
`NamedQuery`	Extends `NamedQuery` with Hibernate features.

Table 3.11. Mapping Simple Properties
Annotation	Description
`AccessType`	Property access type.
`Columns`	Support an array of columns. Useful for component user type mappings.
`ColumnTransformer`	Custom SQL expression used to read the value from and write a value to a column. Use for direct object loading/saving as well as queries. The write expression must contain exactly one '?' placeholder for the value.
`ColumnTransformers`	Plural annotation for `@ColumnTransformer`. Useful when more than one column is using this behavior.

Table 3.12. Property
Annotation	Description
`Formula`	To be used as a replacement for `@Column` in most places. The formula has to be a valid SQL fragment.
`Index`	Defines a database index.
`JoinFormula`	To be used as a replacement for `@JoinColumn` in most places. The formula has to be a valid SQL fragment.
`Parent`	Reference the property as a pointer back to the owner (generally the owning entity).
`Type`	Hibernate type.
`TypeDef`	Hibernate type definition.
`TypeDefs`	Hibernate type definition array.

Table 3.13. Single Association Related Annotations
Annotation	Description
`Any`	Defines a ToOne association pointing to several entity types. Matching the according entity type is done through a metadata discriminator column. This kind of mapping should be only marginal.
`AnyMetaDef`	Defines `@Any` and `@ManyToAny` metadata.
`AnyMetaDefs`	Defines `@Any` and `@ManyToAny` set of metadata. Can be defined at the entity level or the package level.
`Fetch`	Defines the fetching strategy used for the given association.
`LazyCollection`	Defines the lazy status of a collection.
`LazyToOne`	Defines the lazy status of a ToOne association (i.e. `OneToOne` or `ManyToOne`).
`NotFound`	Action to do when an element is not found on an association.

Table 3.14. Optimistic Locking
Annotation	Description
`OptimisticLock`	Whether or not a change of the annotated property will trigger an entity version increment. If the annotation is not present, the property is involved in the optimistic lock strategy (default).
`OptimisticLocking`	Used to define the style of optimistic locking to be applied to an entity. In a hierarchy, only valid on the root entity.
`Source`	Optional annotation in conjunction with Version and timestamp version properties. The annotation value decides where the timestamp is generated.

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.