Appendix B. The Criteria API

Appendix B. The Criteria API

Criteria queries start by obtaining a Criteria object from the Session, using the
createCriteria⁠⁠(⁠ ⁠) method
to identify the primary class (and thus table) on which the query is to be
performed. Restrictions, projections, and orderings are then attached to the
query using the factories described below, making it a very powerful and
convenient interface.

B.1. The Criterion Factory

Hibernate provides the class
org.hibernate.criterion.Restrictions as a factory
for creating the Criterion instances you use to
narrow down the objects (rows) you want from criteria queries.
Restrictions defines a bunch of static methods you
can invoke to conveniently create each of the standard
Criterion implementations available in Hibernate,
using parameters you supply. These criteria are used to determine which
persistent objects from the database are included in the results of your
query. The following table provides a summary of the available
options.

Method	Parameters	Purpose
allEq	Map properties	A shortcut for requiring several properties to have particular values. The keys of the supplied map are the names of the properties you want to constrain, while the values in the map are the target values each property must equal if an entity is to be included in the query results. The returned Criterion ensures that each named property has the corresponding value.
and	Criterion lhs, Criterion rhs	Builds a compound Criterion that requires both halves to be met in order for the whole to succeed. See also conjunction⁠⁠(⁠ ⁠).
between	String property, Object low, Object high	Requires the value of the named property to fall between the values of low and high.
conjunction	None	Creates a Conjunction object which can be used to build an "and" criterion with as many pieces as you need. Simply call its add⁠⁠(⁠ ⁠) method with each of the Criterion instances you want to check. The conjunction will be true if and only if all its component criteria are true. This is more convenient than building a tree of and⁠⁠(⁠ ⁠) criteria "by hand." The add⁠⁠(⁠ ⁠) method of the Criteria interface acts as though it contains a Conjunction.
disjunction	None	Creates a Disjunction object that can be used to build an "or" criterion with as many pieces as you need. Simply call its add⁠⁠(⁠ ⁠) method with each of the Criterion instances you want to check. The disjunction will be true if any of its component criteria are true. This is more convenient than building a tree of or⁠⁠(⁠ ⁠) criteria "by hand." See Example 8-10.
eq	String property, Object value	Requires the named property to have the specified value.
eqProperty	String property1, String property2	Requires the two named properties to have the same value.
ge	String property, Object value	Requires the named property to be greater than or equal to the specified value.
geProperty	String property1, String property2	Requires the first named property to be greater than or equal to the second.
gt	String property, Object value	Requires the named property to be greater than the specified value.
gtProperty	String property1, String property2	Requires the first named property to be greater than the second.
idEq	Object value	Requires the identifier property to be equal to the specified value.
ilike	String property, Object value	A case-insensitive "like" operator. See like.
ilike	String property, String value, MatchMode mode	A case-insensitive "like" operator for people who don't want to mess with "like" syntax and just want to match a substring. MatchMode is a type-safe enumeration with values START, END, ANYWHERE, and EXACT. This method adjusts the syntax of value to reflect the kind of matching specified by mode, then proceeds like the two-parameter ilike⁠⁠(⁠ ⁠).
in	String property, Collection values	A shortcut for allowing the named property to have any of the values contained in the collection. This is more convenient than building up a disjunction⁠⁠(⁠ ⁠) of eq⁠⁠(⁠ ⁠) criteria "by hand."
in	String property, Object[] values	A shortcut for allowing the named property to have any of the values contained in the array. This is more convenient than building up a disjunction⁠⁠(⁠ ⁠) of eq⁠⁠(⁠ ⁠) criteria "by hand."
isEmpty	String property	Requires the named collection property to be empty (have zero length).
isNotEmpty	String property	Requires the named collection property to be have one or more elements.
isNotNull	String property	Requires the named property to have a value other than null.
isNull	String property	Requires the named property to be null.
le	String property, Object value	Requires the named property to be less than or equal to the specified value. See Example 8-3.
leProperty	String property1, String property2	Requires the first named property to be less than or equal to the second.
like	String property, Object value	Requires the named property to be "like" the specified value (in the sense of the SQL like operator, which allows simple substring matching). See Examples Example 8-8 and Example 8-16.
like	String property, String value, MatchMode mode	A "like" operator for people who don't want to mess with "like" syntax and just want to match a substring. See ilike⁠⁠(⁠ ⁠) for more details.
lt	String property, Object value	Requires the named property to be less than the specified value.
ltProperty	String property1, String property2	Requires the first named property to be less than the second.
naturalId	None	Allows selection through a multicolumn "natural business key" mapped using <natural-id>.
ne	String property, Object value	Requires the named property to have any value other than the specified value.
neProperty	String property1, String property2	Requires the two named properties to have different values.
not	Criterion expression	Negates the supplied Criterion (if it matched, this one fails, and vice versa).
or	Criterion lhs, Criterion rhs	Builds a compound Criterion that succeeds if either of its halves matches. See also disjunction⁠⁠(⁠ ⁠).
sizeEq	String property, int size	Requires the named collection property to have the specified number of elements.
sizeGe	String property, int size	Requires the named collection property to have at least the specified number of elements.
sizeGt	String property, int size	Requires the named collection property to have more than the specified number of elements.
sizeLe	String property, int size	Requires the named collection property to have no more than the specified number of elements.
sizeLt	String property, int size	Requires the named collection property to have fewer than the specified number of elements.
sizeNe	String property, int size	Requires the named collection property to have a different number of elements than size.
sqlRestriction	String sql	Applies a constraint expressed in the native SQL dialect of the underlying database system. This can be very powerful, but be aware it might lead to loss of portability.
sqlRestriction	String sql, Object[] values, Type[] types	Applies a constraint expressed in the native SQL of the underlying database, with the supplied JDBC parameters. This can be very powerful, but be aware it might lead to loss of portability.
sqlRestriction	String sql, Object value, Type type	Applies a constraint expressed in the native SQL of the underlying database, with the supplied JDBC parameter. This can be very powerful, but be aware it might lead to loss of portability.

When specifying query text for the
sqlRestriction⁠⁠(⁠ ⁠) methods, any occurrences of
the string "{alias}" within the query
will be replaced by the actual alias of the table on which the query is
being performed.

Many of these methods accept Criterion
instances as arguments, allowing you to build compound criteria trees with
as much complexity as you need.
conjunction⁠⁠(⁠ ⁠) and disjunction⁠⁠(⁠ ⁠) return objects
that make it even easier to add criteria, by returning objects with
add⁠⁠(⁠ ⁠) methods you can call as many times as
you'd like to add criteria. If your query gets sufficiently complex,
however, it might be easier to express and understand in
HQL. There are also a few remaining kinds of queries
that are not yet supported by this API, so you may not
always be able to avoid HQL. But that's becoming
increasingly rare—most of the kinds of bread-and-butter queries that come
up all the time in application development are expressed very naturally
and easily in this API, leading to readable and compact
Java code that can be checked for correctness at compile-time.