Specifies a restriction written in native SQL to add to the generated SQL for entities or collections.

For example, @Where could be used to hide entity instances which have been soft-deleted, either for the entity class itself:

@Entity
@Where(clause = "status <> 'DELETED'")
class Document {
    ...
    @Enumerated(STRING)
    Status status;
    ...
}

or, at the level of an association to the entity:

@OneToMany(mappedBy = "owner")
@Where(clause = "status <> 'DELETED'")
List<Document> documents;

The WhereJoinTable annotation lets a restriction be applied to an association table:

@ManyToMany
@JoinTable(name = "collaborations")
@Where(clause = "status <> 'DELETED'")
@WhereJoinTable(clause = "status = 'ACTIVE'")
List<Document> documents;

By default, @Where restrictions declared for an entity are also applied when loading associations of that entity type. This behavior can be disabled using the setting hibernate.use_entity_where_clause_for_collections. However, this setting is now deprecated.

Note that @Where restrictions are always applied and cannot be disabled. Nor may they be parameterized. They're therefore much less flexible than filters.