0
# Criteria API
1

2
Complete reference for building type-safe queries programmatically using the Criteria API in Jakarta Persistence.
3

4
## Capabilities
5

6
### Query Construction
7

8
The Criteria API provides a type-safe way to construct JPQL queries programmatically. The main entry point is CriteriaBuilder, which creates query objects and expressions.
9

10
```java { .api }
11
import jakarta.persistence.criteria.*;
12

13
/**
14
 * Main interface for constructing criteria queries, compound selections, expressions, predicates, and orderings
15
 */
16
public interface CriteriaBuilder {
17
    // Query creation
18
    CriteriaQuery<Object> createQuery();
19
    <T> CriteriaQuery<T> createQuery(Class<T> resultClass);
20
    CriteriaQuery<Tuple> createTupleQuery();
21
    <T> CriteriaUpdate<T> createCriteriaUpdate(Class<T> targetEntity);
22
    <T> CriteriaDelete<T> createCriteriaDelete(Class<T> targetEntity);
23

24
    // Logical operators
25
    Predicate and(Expression<Boolean> x, Expression<Boolean> y);
26
    Predicate and(Predicate... restrictions);
27
    Predicate or(Expression<Boolean> x, Expression<Boolean> y);
28
    Predicate or(Predicate... restrictions);
29
    Predicate not(Expression<Boolean> restriction);
30
    Predicate conjunction();
31
    Predicate disjunction();
32

33
    // Comparison predicates
34
    Predicate equal(Expression<?> x, Expression<?> y);
35
    Predicate equal(Expression<?> x, Object y);
36
    Predicate notEqual(Expression<?> x, Expression<?> y);
37
    Predicate notEqual(Expression<?> x, Object y);
38
    <Y extends Comparable<? super Y>> Predicate greaterThan(Expression<? extends Y> x, Expression<? extends Y> y);
39
    <Y extends Comparable<? super Y>> Predicate greaterThan(Expression<? extends Y> x, Y y);
40
    <Y extends Comparable<? super Y>> Predicate greaterThanOrEqualTo(Expression<? extends Y> x, Expression<? extends Y> y);
41
    <Y extends Comparable<? super Y>> Predicate greaterThanOrEqualTo(Expression<? extends Y> x, Y y);
42
    <Y extends Comparable<? super Y>> Predicate lessThan(Expression<? extends Y> x, Expression<? extends Y> y);
43
    <Y extends Comparable<? super Y>> Predicate lessThan(Expression<? extends Y> x, Y y);
44
    <Y extends Comparable<? super Y>> Predicate lessThanOrEqualTo(Expression<? extends Y> x, Expression<? extends Y> y);
45
    <Y extends Comparable<? super Y>> Predicate lessThanOrEqualTo(Expression<? extends Y> x, Y y);
46
    <Y extends Comparable<? super Y>> Predicate between(Expression<? extends Y> v, Expression<? extends Y> x, Expression<? extends Y> y);
47
    <Y extends Comparable<? super Y>> Predicate between(Expression<? extends Y> v, Y x, Y y);
48
    Predicate gt(Expression<? extends Number> x, Expression<? extends Number> y);
49
    Predicate gt(Expression<? extends Number> x, Number y);
50
    Predicate ge(Expression<? extends Number> x, Expression<? extends Number> y);
51
    Predicate ge(Expression<? extends Number> x, Number y);
52
    Predicate lt(Expression<? extends Number> x, Expression<? extends Number> y);
53
    Predicate lt(Expression<? extends Number> x, Number y);
54
    Predicate le(Expression<? extends Number> x, Expression<? extends Number> y);
55
    Predicate le(Expression<? extends Number> x, Number y);
56

57
    // Null predicates
58
    Predicate isNull(Expression<?> x);
59
    Predicate isNotNull(Expression<?> x);
60

61
    // Collection predicates
62
    Predicate isTrue(Expression<Boolean> x);
63
    Predicate isFalse(Expression<Boolean> x);
64
    <E, C extends Collection<E>> Predicate isMember(Expression<E> elem, Expression<C> collection);
65
    <E, C extends Collection<E>> Predicate isMember(E elem, Expression<C> collection);
66
    <E, C extends Collection<E>> Predicate isNotMember(Expression<E> elem, Expression<C> collection);
67
    <E, C extends Collection<E>> Predicate isNotMember(E elem, Expression<C> collection);
68
    <C extends Collection<?>> Predicate isEmpty(Expression<C> collection);
69
    <C extends Collection<?>> Predicate isNotEmpty(Expression<C> collection);
70
    <C extends Collection<?>> Expression<Integer> size(Expression<C> collection);
71
    <C extends Collection<?>> Expression<Integer> size(C collection);
72
    <V, M extends Map<?, V>> Expression<Collection<V>> values(M map);
73
    <K, M extends Map<K, ?>> Expression<Set<K>> keys(M map);
74

75
    // String predicates
76
    Predicate like(Expression<String> x, Expression<String> pattern);
77
    Predicate like(Expression<String> x, String pattern);
78
    Predicate like(Expression<String> x, Expression<String> pattern, Expression<Character> escapeChar);
79
    Predicate like(Expression<String> x, Expression<String> pattern, char escapeChar);
80
    Predicate like(Expression<String> x, String pattern, Expression<Character> escapeChar);
81
    Predicate like(Expression<String> x, String pattern, char escapeChar);
82
    Predicate notLike(Expression<String> x, Expression<String> pattern);
83
    Predicate notLike(Expression<String> x, String pattern);
84
    Predicate notLike(Expression<String> x, Expression<String> pattern, Expression<Character> escapeChar);
85
    Predicate notLike(Expression<String> x, Expression<String> pattern, char escapeChar);
86
    Predicate notLike(Expression<String> x, String pattern, Expression<Character> escapeChar);
87
    Predicate notLike(Expression<String> x, String pattern, char escapeChar);
88

89
    // In predicates
90
    <T> In<T> in(Expression<? extends T> expression);
91
    CriteriaBuilder.In<Object> in(Expression<?> expression);
92

93
    // Arithmetic operators
94
    <N extends Number> Expression<N> neg(Expression<N> x);
95
    <N extends Number> Expression<N> abs(Expression<N> x);
96
    <N extends Number> Expression<N> sum(Expression<? extends N> x, Expression<? extends N> y);
97
    <N extends Number> Expression<N> sum(Expression<? extends N> x, N y);
98
    <N extends Number> Expression<N> sum(N x, Expression<? extends N> y);
99
    <N extends Number> Expression<N> prod(Expression<? extends N> x, Expression<? extends N> y);
100
    <N extends Number> Expression<N> prod(Expression<? extends N> x, N y);
101
    <N extends Number> Expression<N> prod(N x, Expression<? extends N> y);
102
    <N extends Number> Expression<N> diff(Expression<? extends N> x, Expression<? extends N> y);
103
    <N extends Number> Expression<N> diff(Expression<? extends N> x, N y);
104
    <N extends Number> Expression<N> diff(N x, Expression<? extends N> y);
105
    Expression<Number> quot(Expression<? extends Number> x, Expression<? extends Number> y);
106
    Expression<Number> quot(Expression<? extends Number> x, Number y);
107
    Expression<Number> quot(Number x, Expression<? extends Number> y);
108
    Expression<Integer> mod(Expression<Integer> x, Expression<Integer> y);
109
    Expression<Integer> mod(Expression<Integer> x, Integer y);
110
    Expression<Integer> mod(Integer x, Expression<Integer> y);
111
    Expression<Double> sqrt(Expression<? extends Number> x);
112
    <N extends Number> Expression<N> ceiling(Expression<N> x);
113
    <N extends Number> Expression<N> floor(Expression<N> x);
114
    Expression<Integer> sign(Expression<? extends Number> x);
115
    Expression<Double> power(Expression<? extends Number> x, Expression<? extends Number> y);
116
    Expression<Double> power(Expression<? extends Number> x, Number y);
117
    Expression<Double> exp(Expression<? extends Number> x);
118
    Expression<Double> ln(Expression<? extends Number> x);
119

120
    // Aggregate functions
121
    <N extends Number> Expression<Double> avg(Expression<N> x);
122
    <N extends Number> Expression<N> sum(Expression<N> x);
123
    Expression<Long> sumAsLong(Expression<Integer> x);
124
    Expression<Double> sumAsDouble(Expression<Float> x);
125
    <N extends Number> Expression<N> max(Expression<N> x);
126
    <N extends Number> Expression<N> min(Expression<N> x);
127
    <X extends Comparable<? super X>> Expression<X> greatest(Expression<X> x);
128
    <X extends Comparable<? super X>> Expression<X> least(Expression<X> x);
129
    Expression<Long> count(Expression<?> x);
130
    Expression<Long> countDistinct(Expression<?> x);
131

132
    // String functions
133
    Expression<String> concat(Expression<String> x, Expression<String> y);
134
    Expression<String> concat(Expression<String> x, String y);
135
    Expression<String> concat(String x, Expression<String> y);
136
    Expression<String> substring(Expression<String> x, Expression<Integer> from);
137
    Expression<String> substring(Expression<String> x, int from);
138
    Expression<String> substring(Expression<String> x, Expression<Integer> from, Expression<Integer> len);
139
    Expression<String> substring(Expression<String> x, int from, int len);
140
    Expression<String> trim(Expression<String> x);
141
    Expression<String> trim(Trimspec ts, Expression<String> x);
142
    Expression<String> trim(Expression<Character> t, Expression<String> x);
143
    Expression<String> trim(Trimspec ts, Expression<Character> t, Expression<String> x);
144
    Expression<String> trim(char t, Expression<String> x);
145
    Expression<String> trim(Trimspec ts, char t, Expression<String> x);
146
    Expression<String> lower(Expression<String> x);
147
    Expression<String> upper(Expression<String> x);
148
    Expression<Integer> length(Expression<String> x);
149
    Expression<Integer> locate(Expression<String> x, Expression<String> pattern);
150
    Expression<Integer> locate(Expression<String> x, String pattern);
151
    Expression<Integer> locate(Expression<String> x, Expression<String> pattern, Expression<Integer> from);
152
    Expression<Integer> locate(Expression<String> x, String pattern, int from);
153

154
    // Date/time functions
155
    Expression<java.sql.Date> currentDate();
156
    Expression<java.sql.Timestamp> currentTimestamp();
157
    Expression<java.sql.Time> currentTime();
158

159
    // Literals
160
    <T> Expression<T> literal(T value);
161
    <T> Expression<T> nullLiteral(Class<T> resultClass);
162

163
    // Parameters
164
    <T> ParameterExpression<T> parameter(Class<T> paramClass);
165
    <T> ParameterExpression<T> parameter(Class<T> paramClass, String name);
166

167
    // Case expressions
168
    <R> Case<R> selectCase();
169
    <C, R> SimpleCase<C, R> selectCase(Expression<? extends C> expression);
170
    <T> Coalesce<T> coalesce();
171
    <Y> Expression<Y> coalesce(Expression<? extends Y> x, Expression<? extends Y> y);
172
    <Y> Expression<Y> coalesce(Expression<? extends Y> x, Y y);
173
    <Y> Expression<Y> nullif(Expression<Y> x, Expression<?> y);
174
    <Y> Expression<Y> nullif(Expression<Y> x, Y y);
175

176
    // Functions
177
    <T> Expression<T> function(String name, Class<T> type, Expression<?>... args);
178

179
    // Ordering
180
    Order asc(Expression<?> x);
181
    Order desc(Expression<?> x);
182

183
    // Tuples
184
    CompoundSelection<Tuple> tuple(Selection<?>... selections);
185
    CompoundSelection<Object[]> array(Selection<?>... selections);
186
    <Y> CompoundSelection<Y> construct(Class<Y> resultClass, Selection<?>... selections);
187

188
    // Subqueries
189
    Predicate exists(Subquery<?> subquery);
190
    <Y> Expression<Y> all(Subquery<Y> subquery);
191
    <Y> Expression<Y> some(Subquery<Y> subquery);
192
    <Y> Expression<Y> any(Subquery<Y> subquery);
193

194
    // Treat and type operations
195
    <X, T, V extends T> Join<X, V> treat(Join<X, T> join, Class<V> type);
196
    <X, T, E extends T> CollectionJoin<X, E> treat(CollectionJoin<X, T> join, Class<E> type);
197
    <X, T, E extends T> SetJoin<X, E> treat(SetJoin<X, T> join, Class<E> type);
198
    <X, T, E extends T> ListJoin<X, E> treat(ListJoin<X, T> join, Class<E> type);
199
    <X, K, T, V extends T> MapJoin<X, K, V> treat(MapJoin<X, K, T> join, Class<V> type);
200
    <X, T extends X> Path<T> treat(Path<X> path, Class<T> type);
201
    <X, T extends X> Root<T> treat(Root<X> root, Class<T> type);
202

203
    // Type
204
    <X, T> Expression<X> type(Root<T> root);
205
}
206
```
207

208
**Usage Example:**
209

210
```java
211
CriteriaBuilder cb = entityManager.getCriteriaBuilder();
212
CriteriaQuery<User> query = cb.createQuery(User.class);
213
Root<User> root = query.from(User.class);
214

215
// Add predicates
216
Predicate agePredicate = cb.greaterThan(root.get("age"), 18);
217
Predicate namePredicate = cb.like(root.get("name"), "John%");
218
query.where(cb.and(agePredicate, namePredicate));
219

220
// Order results
221
query.orderBy(cb.asc(root.get("name")));
222

223
List<User> results = entityManager.createQuery(query).getResultList();
224
```
225

226
### Query Interfaces
227

228
Interfaces for defining and executing criteria queries.
229

230
```java { .api }
231
/**
232
 * The CriteriaQuery interface defines functionality specific to top-level queries
233
 */
234
public interface CriteriaQuery<T> extends AbstractQuery<T> {
235
    CriteriaQuery<T> select(Selection<? extends T> selection);
236
    CriteriaQuery<T> multiselect(Selection<?>... selections);
237
    CriteriaQuery<T> multiselect(List<Selection<?>> selectionList);
238
    CriteriaQuery<T> where(Expression<Boolean> restriction);
239
    CriteriaQuery<T> where(Predicate... restrictions);
240
    CriteriaQuery<T> groupBy(Expression<?>... grouping);
241
    CriteriaQuery<T> groupBy(List<Expression<?>> grouping);
242
    CriteriaQuery<T> having(Expression<Boolean> restriction);
243
    CriteriaQuery<T> having(Predicate... restrictions);
244
    CriteriaQuery<T> orderBy(Order... o);
245
    CriteriaQuery<T> orderBy(List<Order> o);
246
    CriteriaQuery<T> distinct(boolean distinct);
247
    List<Order> getOrderList();
248
    Set<ParameterExpression<?>> getParameters();
249
}
250

251
/**
252
 * Base interface for criteria queries and subqueries
253
 */
254
public interface AbstractQuery<T> extends CommonAbstractCriteria {
255
    <X> Root<X> from(Class<X> entityClass);
256
    <X> Root<X> from(EntityType<X> entity);
257
    AbstractQuery<T> where(Expression<Boolean> restriction);
258
    AbstractQuery<T> where(Predicate... restrictions);
259
    AbstractQuery<T> groupBy(Expression<?>... grouping);
260
    AbstractQuery<T> groupBy(List<Expression<?>> grouping);
261
    AbstractQuery<T> having(Expression<Boolean> restriction);
262
    AbstractQuery<T> having(Predicate... restrictions);
263
    AbstractQuery<T> distinct(boolean distinct);
264
    Set<Root<?>> getRoots();
265
    Selection<T> getSelection();
266
    List<Expression<?>> getGroupList();
267
    Predicate getGroupRestriction();
268
    boolean isDistinct();
269
    Class<T> getResultType();
270
}
271

272
/**
273
 * Common functionality for all criteria operations
274
 */
275
public interface CommonAbstractCriteria {
276
    <U> Subquery<U> subquery(Class<U> type);
277
    Predicate getRestriction();
278
}
279

280
/**
281
 * The Subquery interface defines functionality specific to subqueries
282
 */
283
public interface Subquery<T> extends AbstractQuery<T>, Expression<T> {
284
    Subquery<T> select(Expression<T> expression);
285
    Subquery<T> where(Expression<Boolean> restriction);
286
    Subquery<T> where(Predicate... restrictions);
287
    Subquery<T> groupBy(Expression<?>... grouping);
288
    Subquery<T> groupBy(List<Expression<?>> grouping);
289
    Subquery<T> having(Expression<Boolean> restriction);
290
    Subquery<T> having(Predicate... restrictions);
291
    Subquery<T> distinct(boolean distinct);
292
    <Y> Root<Y> correlate(Root<Y> parentRoot);
293
    <X, Y> Join<X, Y> correlate(Join<X, Y> parentJoin);
294
    <X, Y> CollectionJoin<X, Y> correlate(CollectionJoin<X, Y> parentCollection);
295
    <X, Y> SetJoin<X, Y> correlate(SetJoin<X, Y> parentSet);
296
    <X, Y> ListJoin<X, Y> correlate(ListJoin<X, Y> parentList);
297
    <X, K, V> MapJoin<X, K, V> correlate(MapJoin<X, K, V> parentMap);
298
    AbstractQuery<?> getParent();
299
    CommonAbstractCriteria getContainingQuery();
300
    Expression<T> getSelection();
301
    Set<Join<?, ?>> getCorrelatedJoins();
302
}
303
```
304

305
### Bulk Update and Delete
306

307
Criteria API for bulk update and delete operations.
308

309
```java { .api }
310
/**
311
 * Interface for performing bulk update operations using Criteria API
312
 */
313
public interface CriteriaUpdate<T> extends CommonAbstractCriteria {
314
    Root<T> from(Class<T> entityClass);
315
    Root<T> from(EntityType<T> entity);
316
    Root<T> getRoot();
317
    <Y, X extends Y> CriteriaUpdate<T> set(SingularAttribute<? super T, Y> attribute, X value);
318
    <Y> CriteriaUpdate<T> set(SingularAttribute<? super T, Y> attribute, Expression<? extends Y> value);
319
    <Y, X extends Y> CriteriaUpdate<T> set(Path<Y> attribute, X value);
320
    <Y> CriteriaUpdate<T> set(Path<Y> attribute, Expression<? extends Y> value);
321
    CriteriaUpdate<T> set(String attributeName, Object value);
322
    CriteriaUpdate<T> where(Expression<Boolean> restriction);
323
    CriteriaUpdate<T> where(Predicate... restrictions);
324
}
325

326
/**
327
 * Interface for performing bulk delete operations using Criteria API
328
 */
329
public interface CriteriaDelete<T> extends CommonAbstractCriteria {
330
    Root<T> from(Class<T> entityClass);
331
    Root<T> from(EntityType<T> entity);
332
    Root<T> getRoot();
333
    CriteriaDelete<T> where(Expression<Boolean> restriction);
334
    CriteriaDelete<T> where(Predicate... restrictions);
335
}
336
```
337

338
**Usage Example:**
339

340
```java
341
// Bulk update
342
CriteriaBuilder cb = em.getCriteriaBuilder();
343
CriteriaUpdate<User> update = cb.createCriteriaUpdate(User.class);
344
Root<User> root = update.from(User.class);
345
update.set(root.get("status"), "inactive")
346
      .where(cb.lessThan(root.get("lastLogin"), oldDate));
347
em.createQuery(update).executeUpdate();
348

349
// Bulk delete
350
CriteriaDelete<User> delete = cb.createCriteriaDelete(User.class);
351
Root<User> root = delete.from(User.class);
352
delete.where(cb.equal(root.get("status"), "deleted"));
353
em.createQuery(delete).executeUpdate();
354
```
355

356
### Expressions and Predicates
357

358
Core expression and predicate types for building query conditions.
359

360
```java { .api }
361
/**
362
 * Type for query expressions
363
 */
364
public interface Expression<T> extends Selection<T> {
365
    Predicate isNull();
366
    Predicate isNotNull();
367
    Predicate in(Object... values);
368
    Predicate in(Expression<?>... values);
369
    Predicate in(Collection<?> values);
370
    Predicate in(Expression<Collection<?>> values);
371
    <X> Expression<X> as(Class<X> type);
372
}
373

374
/**
375
 * Boolean expressions used in WHERE clauses
376
 */
377
public interface Predicate extends Expression<Boolean> {
378
    enum BooleanOperator { AND, OR }
379

380
    BooleanOperator getOperator();
381
    boolean isNegated();
382
    List<Expression<Boolean>> getExpressions();
383
    Predicate not();
384
}
385

386
/**
387
 * Represents a selection item in the SELECT clause
388
 */
389
public interface Selection<X> extends TupleElement<X> {
390
    Selection<X> alias(String name);
391
    boolean isCompoundSelection();
392
    List<Selection<?>> getCompoundSelectionItems();
393
}
394

395
/**
396
 * Compound selection item (tuple, array, or constructor result)
397
 */
398
public interface CompoundSelection<X> extends Selection<X> {
399
    // Inherits all methods from Selection<X>
400
}
401

402
/**
403
 * Type of criteria query parameter expressions
404
 */
405
public interface ParameterExpression<T> extends Parameter<T>, Expression<T> {
406
    // Combines Parameter and Expression functionality
407
}
408
```
409

410
### Paths and Navigation
411

412
Path expressions for navigating to entity attributes.
413

414
```java { .api }
415
/**
416
 * Represents a simple or compound attribute path
417
 */
418
public interface Path<X> extends Expression<X> {
419
    Bindable<X> getModel();
420
    Path<?> getParentPath();
421
    <Y> Path<Y> get(SingularAttribute<? super X, Y> attribute);
422
    <E, C extends Collection<E>> Expression<C> get(PluralAttribute<X, C, E> collection);
423
    <K, V, M extends Map<K, V>> Expression<M> get(MapAttribute<X, K, V> map);
424
    Expression<Class<? extends X>> type();
425
    <Y> Path<Y> get(String attributeName);
426
}
427

428
/**
429
 * A root type in the from clause that references entities
430
 */
431
public interface Root<X> extends From<X, X> {
432
    EntityType<X> getModel();
433
}
434

435
/**
436
 * Represents a bound type appearing in the from clause
437
 */
438
public interface From<Z, X> extends Path<X>, FetchParent<Z, X> {
439
    Set<Join<X, ?>> getJoins();
440
    boolean isCorrelated();
441
    From<Z, X> getCorrelationParent();
442
    <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute);
443
    <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute, JoinType jt);
444
    <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection);
445
    <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set);
446
    <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list);
447
    <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map);
448
    <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection, JoinType jt);
449
    <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set, JoinType jt);
450
    <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list, JoinType jt);
451
    <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map, JoinType jt);
452
    <X, Y> Join<X, Y> join(String attributeName);
453
    <X, Y> CollectionJoin<X, Y> joinCollection(String attributeName);
454
    <X, Y> SetJoin<X, Y> joinSet(String attributeName);
455
    <X, Y> ListJoin<X, Y> joinList(String attributeName);
456
    <X, K, V> MapJoin<X, K, V> joinMap(String attributeName);
457
    <X, Y> Join<X, Y> join(String attributeName, JoinType jt);
458
    <X, Y> CollectionJoin<X, Y> joinCollection(String attributeName, JoinType jt);
459
    <X, Y> SetJoin<X, Y> joinSet(String attributeName, JoinType jt);
460
    <X, Y> ListJoin<X, Y> joinList(String attributeName, JoinType jt);
461
    <X, K, V> MapJoin<X, K, V> joinMap(String attributeName, JoinType jt);
462
}
463
```
464

465
### Joins
466

467
Join interfaces for navigating relationships.
468

469
```java { .api }
470
/**
471
 * A join to an entity, embeddable, or basic type
472
 */
473
public interface Join<Z, X> extends From<Z, X> {
474
    Join<Z, X> on(Expression<Boolean> restriction);
475
    Join<Z, X> on(Predicate... restrictions);
476
    Predicate getOn();
477
    Attribute<? super Z, ?> getAttribute();
478
    From<?, Z> getParent();
479
    JoinType getJoinType();
480
}
481

482
/**
483
 * Common functionality for joins to all collection types
484
 */
485
public interface PluralJoin<Z, C, E> extends Join<Z, E> {
486
    PluralAttribute<? super Z, C, E> getModel();
487
}
488

489
/**
490
 * Join to a java.util.Collection
491
 */
492
public interface CollectionJoin<Z, E> extends PluralJoin<Z, Collection<E>, E> {
493
    CollectionJoin<Z, E> on(Expression<Boolean> restriction);
494
    CollectionJoin<Z, E> on(Predicate... restrictions);
495
    CollectionAttribute<? super Z, E> getModel();
496
}
497

498
/**
499
 * Join to a java.util.Set
500
 */
501
public interface SetJoin<Z, E> extends PluralJoin<Z, Set<E>, E> {
502
    SetJoin<Z, E> on(Expression<Boolean> restriction);
503
    SetJoin<Z, E> on(Predicate... restrictions);
504
    SetAttribute<? super Z, E> getModel();
505
}
506

507
/**
508
 * Join to a java.util.List
509
 */
510
public interface ListJoin<Z, E> extends PluralJoin<Z, List<E>, E> {
511
    ListJoin<Z, E> on(Expression<Boolean> restriction);
512
    ListJoin<Z, E> on(Predicate... restrictions);
513
    ListAttribute<? super Z, E> getModel();
514
    Expression<Integer> index();
515
}
516

517
/**
518
 * Join to a java.util.Map
519
 */
520
public interface MapJoin<Z, K, V> extends PluralJoin<Z, Map<K, V>, V> {
521
    MapJoin<Z, K, V> on(Expression<Boolean> restriction);
522
    MapJoin<Z, K, V> on(Predicate... restrictions);
523
    MapAttribute<? super Z, K, V> getModel();
524
    Path<K> key();
525
    Path<V> value();
526
    Expression<Map.Entry<K, V>> entry();
527
}
528

529
/**
530
 * Join type enumeration
531
 */
532
public enum JoinType {
533
    INNER,
534
    LEFT,
535
    RIGHT
536
}
537
```
538

539
**Usage Example:**
540

541
```java
542
CriteriaBuilder cb = em.getCriteriaBuilder();
543
CriteriaQuery<Order> query = cb.createQuery(Order.class);
544
Root<Order> order = query.from(Order.class);
545

546
// Create joins
547
Join<Order, Customer> customer = order.join("customer", JoinType.INNER);
548
Join<Customer, Address> address = customer.join("address", JoinType.LEFT);
549

550
// Use ON condition
551
Join<Order, OrderItem> items = order.join("items");
552
items.on(cb.greaterThan(items.get("quantity"), 0));
553

554
query.where(cb.equal(address.get("city"), "New York"));
555
```
556

557
### Fetch Joins
558

559
Fetch joins for eagerly loading associations.
560

561
```java { .api }
562
/**
563
 * Parent interface for fetch operations
564
 */
565
public interface FetchParent<Z, X> {
566
    Set<Fetch<X, ?>> getFetches();
567
    <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute);
568
    <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute, JoinType jt);
569
    <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute);
570
    <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute, JoinType jt);
571
    <X, Y> Fetch<X, Y> fetch(String attributeName);
572
    <X, Y> Fetch<X, Y> fetch(String attributeName, JoinType jt);
573
}
574

575
/**
576
 * Represents a join-fetched association or attribute
577
 */
578
public interface Fetch<Z, X> extends FetchParent<Z, X> {
579
    Attribute<? super Z, ?> getAttribute();
580
    FetchParent<?, Z> getParent();
581
    JoinType getJoinType();
582
}
583
```
584

585
**Usage Example:**
586

587
```java
588
CriteriaBuilder cb = em.getCriteriaBuilder();
589
CriteriaQuery<Order> query = cb.createQuery(Order.class);
590
Root<Order> order = query.from(Order.class);
591

592
// Fetch associations eagerly
593
order.fetch("customer", JoinType.LEFT);
594
order.fetch("items", JoinType.LEFT);
595

596
List<Order> orders = em.createQuery(query).getResultList();
597
// Customer and items are eagerly loaded
598
```
599

600
### Ordering
601

602
Order expressions for sorting query results.
603

604
```java { .api }
605
/**
606
 * Defines an ordering over the query results
607
 */
608
public interface Order {
609
    Order reverse();
610
    boolean isAscending();
611
    Expression<?> getExpression();
612
}
613
```
614

615
**Usage Example:**
616

617
```java
618
CriteriaBuilder cb = em.getCriteriaBuilder();
619
CriteriaQuery<User> query = cb.createQuery(User.class);
620
Root<User> user = query.from(User.class);
621

622
// Create ordering
623
Order nameOrder = cb.asc(user.get("name"));
624
Order ageOrder = cb.desc(user.get("age"));
625

626
query.orderBy(nameOrder, ageOrder);
627
```
628

629
### CriteriaBuilder Nested Interfaces
630

631
CriteriaBuilder defines several nested interfaces for building complex query expressions.
632

633
```java { .api }
634
/**
635
 * Enum used to specify how strings are trimmed
636
 */
637
public static enum Trimspec {
638
    /** Trim from leading end */
639
    LEADING,
640

641
    /** Trim from trailing end */
642
    TRAILING,
643

644
    /** Trim from both ends */
645
    BOTH
646
}
647

648
/**
649
 * Interface used to build IN predicates
650
 */
651
public static interface In<T> extends Predicate {
652
    /**
653
     * Return the expression to be tested against the list of values
654
     * @return expression
655
     */
656
    Expression<T> getExpression();
657

658
    /**
659
     * Add to list of values to be tested against
660
     * @param value value
661
     * @return in predicate
662
     */
663
    In<T> value(T value);
664

665
    /**
666
     * Add to list of values to be tested against
667
     * @param value expression
668
     * @return in predicate
669
     */
670
    In<T> value(Expression<? extends T> value);
671
}
672

673
/**
674
 * Interface used to build COALESCE expressions
675
 *
676
 * A coalesce expression is equivalent to a case expression that returns null
677
 * if all its arguments evaluate to null, and the value of its first non-null
678
 * argument otherwise
679
 */
680
public static interface Coalesce<T> extends Expression<T> {
681
    /**
682
     * Add an argument to the coalesce expression
683
     * @param value value
684
     * @return coalesce expression
685
     */
686
    Coalesce<T> value(T value);
687

688
    /**
689
     * Add an argument to the coalesce expression
690
     * @param value expression
691
     * @return coalesce expression
692
     */
693
    Coalesce<T> value(Expression<? extends T> value);
694
}
695

696
/**
697
 * Interface used to build simple CASE expressions
698
 *
699
 * Case conditions are evaluated in the order in which they are specified
700
 */
701
public static interface SimpleCase<C, R> extends Expression<R> {
702
    /**
703
     * Return the expression to be tested against the conditions
704
     * @return expression
705
     */
706
    Expression<C> getExpression();
707

708
    /**
709
     * Add a when/then clause to the case expression
710
     * @param condition "when" condition
711
     * @param result "then" result value
712
     * @return simple case expression
713
     */
714
    SimpleCase<C, R> when(C condition, R result);
715

716
    /**
717
     * Add a when/then clause to the case expression
718
     * @param condition "when" condition
719
     * @param result "then" result expression
720
     * @return simple case expression
721
     */
722
    SimpleCase<C, R> when(C condition, Expression<? extends R> result);
723

724
    /**
725
     * Add a when/then clause to the case expression
726
     * @param condition "when" condition
727
     * @param result "then" result value
728
     * @return simple case expression
729
     */
730
    SimpleCase<C, R> when(Expression<? extends C> condition, R result);
731

732
    /**
733
     * Add a when/then clause to the case expression
734
     * @param condition "when" condition
735
     * @param result "then" result expression
736
     * @return simple case expression
737
     */
738
    SimpleCase<C, R> when(Expression<? extends C> condition, Expression<? extends R> result);
739

740
    /**
741
     * Add an "else" clause to the case expression
742
     * @param result "else" result
743
     * @return expression
744
     */
745
    Expression<R> otherwise(R result);
746

747
    /**
748
     * Add an "else" clause to the case expression
749
     * @param result "else" result expression
750
     * @return expression
751
     */
752
    Expression<R> otherwise(Expression<? extends R> result);
753
}
754

755
/**
756
 * Interface used to build general CASE expressions
757
 *
758
 * Case conditions are evaluated in the order in which they are specified
759
 */
760
public static interface Case<R> extends Expression<R> {
761
    /**
762
     * Add a when/then clause to the case expression
763
     * @param condition "when" condition
764
     * @param result "then" result value
765
     * @return general case expression
766
     */
767
    Case<R> when(Expression<Boolean> condition, R result);
768

769
    /**
770
     * Add a when/then clause to the case expression
771
     * @param condition "when" condition
772
     * @param result "then" result expression
773
     * @return general case expression
774
     */
775
    Case<R> when(Expression<Boolean> condition, Expression<? extends R> result);
776

777
    /**
778
     * Add an "else" clause to the case expression
779
     * @param result "else" result
780
     * @return expression
781
     */
782
    Expression<R> otherwise(R result);
783

784
    /**
785
     * Add an "else" clause to the case expression
786
     * @param result "else" result expression
787
     * @return expression
788
     */
789
    Expression<R> otherwise(Expression<? extends R> result);
790
}
791
```
792

793
**Usage Examples:**
794

795
**IN Predicate:**
796
```java
797
CriteriaBuilder cb = em.getCriteriaBuilder();
798
CriteriaQuery<User> query = cb.createQuery(User.class);
799
Root<User> user = query.from(User.class);
800

801
// Build IN predicate
802
CriteriaBuilder.In<String> inPredicate = cb.in(user.get("status"));
803
inPredicate.value("ACTIVE").value("PENDING").value("APPROVED");
804
query.where(inPredicate);
805
```
806

807
**COALESCE Expression:**
808
```java
809
CriteriaBuilder cb = em.getCriteriaBuilder();
810
CriteriaQuery<String> query = cb.createQuery(String.class);
811
Root<User> user = query.from(User.class);
812

813
// Return nickname if not null, otherwise return username
814
CriteriaBuilder.Coalesce<String> coalesce = cb.coalesce();
815
coalesce.value(user.get("nickname")).value(user.get("username"));
816
query.select(coalesce);
817
```
818

819
**Simple CASE Expression:**
820
```java
821
CriteriaBuilder cb = em.getCriteriaBuilder();
822
CriteriaQuery<String> query = cb.createQuery(String.class);
823
Root<User> user = query.from(User.class);
824

825
// Map status codes to descriptions
826
CriteriaBuilder.SimpleCase<Integer, String> caseExpr =
827
    cb.selectCase(user.get("statusCode"));
828
caseExpr.when(1, "Active")
829
        .when(2, "Inactive")
830
        .when(3, "Suspended")
831
        .otherwise("Unknown");
832
query.select(caseExpr);
833
```
834

835
**General CASE Expression:**
836
```java
837
CriteriaBuilder cb = em.getCriteriaBuilder();
838
CriteriaQuery<String> query = cb.createQuery(String.class);
839
Root<User> user = query.from(User.class);
840

841
// Categorize users based on age
842
CriteriaBuilder.Case<String> caseExpr = cb.selectCase();
843
caseExpr.when(cb.lessThan(user.get("age"), 18), "Minor")
844
        .when(cb.between(user.get("age"), 18, 65), "Adult")
845
        .otherwise("Senior");
846
query.select(caseExpr);
847
```
848