What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Hibernate’s @Where annotation adds a fixed native-SQL predicate to an entity or collection mapping. It is deprecated since Hibernate 6.3; for a permanent restriction in current Hibernate, use @SQLRestriction. If the condition must be enabled, disabled, or parameterized at runtime, use a filter instead.
What does Hibernate @Where do?
@Where tells Hibernate to apply a native SQL condition when reading the mapped entity or collection. It is not a JPQL expression: column names, quoting, and other SQL details must work with the target database and its dialect.
A common legacy use is to exclude soft-deleted rows:
@Entity
@Where(clause = "deleted = false")
class Account {
// fields
}Hibernate’s 6.3 Javadoc documents the annotation for entities and collections, and gives a status predicate as an example. It may be placed on a type, method, or field.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
What are its limits?
The restriction is static and unconditional: Hibernate always applies it, it cannot be disabled, and it cannot take runtime parameters. That makes it appropriate for a visibility rule that should always hold, such as hiding deleted records. It is not suitable when the condition changes by tenant, locale, date range, or user choice.
Hibernate 6.3 documentation says entity restrictions are applied to associations by default. Association loading behavior has changed across Hibernate versions, so verify the behavior against the exact ORM version used by the application.
Is @Where deprecated, and what should replace it?
Yes. Hibernate marks @Where deprecated since 6.3 and points to @SQLRestriction. The replacement also expresses an unconditional native-SQL restriction and can be used for entities and collections. See the @Where Javadoc and @SQLRestriction Javadoc.
Use @SQLJoinTableRestriction when the predicate belongs to a many-to-many association’s join table, rather than to the associated entity’s table. @WhereJoinTable is also deprecated since 6.3. The distinction is important: an entity restriction filters rows from the entity table; a join-table restriction filters association-table rows. See the @SQLJoinTableRestriction Javadoc.
Rank #3
Which Hibernate filtering API fits the requirement?
| Requirement | Mapping to use |
|---|---|
| Permanent predicate in existing Hibernate code before 6.3 | @Where (legacy; plan migration) |
| Permanent predicate on an entity or collection | @SQLRestriction("...") |
| Predicate on a many-to-many join table | @SQLJoinTableRestriction("...") |
| Condition that needs runtime enable/disable or parameters | @Filter or @FilterJoinTable |
Hibernate’s user guide distinguishes static restrictions such as @SQLRestriction and @SQLJoinTableRestriction from dynamic filtering with @Filter and @FilterJoinTable. Its introduction explains that a static condition with no parameters does not need a filter.
What should you test when migrating?
A restriction can change what an association looks like to application code, even when the database still contains a foreign key. Hibernate’s migration guide documents behavior for restricted @ManyToOne and @OneToOne targets across eager and lazy loading, fetch joins, find(), and entity graphs.
Rank #4
- A target excluded by an applicable restriction may appear as
nullin the association view, despite a non-null foreign key. - An explicit inner fetch join can omit the owner whose target is restricted; a left fetch join can retain the owner with a null association.
@SQLRestrictionremains unconditional and cannot be disabled.
Before changing versions or replacing the annotation, test hidden references, assumptions about association optionality, fetch joins, and any code that expects EntityNotFoundException. Consult the user guide and migration guide for the exact Hibernate ORM line in use; documentation lists older 6.3 and 6.4 lines as end-of-life.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
