0
# Query Builder System
1

2
Type-safe, fluent query building with comprehensive SQL support. The QueryWrapper system provides a powerful, readable way to construct complex SQL queries with full IDE support and compile-time type checking.
3

4
## Capabilities
5

6
### QueryWrapper
7

8
Primary query builder class providing fluent API for constructing SQL queries with type safety and IDE auto-completion.
9

10
```java { .api }
11
/**
12
 * Fluent query builder for type-safe SQL construction
13
 */
14
public class QueryWrapper {
15
    /**
16
     * Create new empty query wrapper
17
     * @return new QueryWrapper instance
18
     */
19
    public static QueryWrapper create();
20
    
21
    /**
22
     * Create query wrapper from entity with non-null fields as conditions
23
     * @param entity entity object
24
     * @return QueryWrapper with entity conditions
25
     */
26
    public static QueryWrapper create(Object entity);
27
    
28
    /**
29
     * Create query wrapper from map with key-value conditions
30
     * @param map condition map
31
     * @return QueryWrapper with map conditions
32
     */
33
    public static QueryWrapper create(Map<String, Object> map);
34
    
35
    /**
36
     * Specify columns to select
37
     * @param queryColumns columns to select
38
     * @return query wrapper for chaining
39
     */
40
    public QueryWrapper select(QueryColumn... queryColumns);
41
    
42
    /**
43
     * Specify columns to select with lambda expressions
44
     * @param lambdaGetters lambda getter methods
45
     * @return query wrapper for chaining
46
     */
47
    public <T> QueryWrapper select(LambdaGetter<T>... lambdaGetters);
48
    
49
    /**
50
     * Select distinct records
51
     * @param queryColumns columns to select
52
     * @return query wrapper for chaining
53
     */
54
    public QueryWrapper selectDistinct(QueryColumn... queryColumns);
55
    
56
    /**
57
     * Specify tables to query from
58
     * @param entityClasses entity classes representing tables
59
     * @return query wrapper for chaining
60
     */
61
    public QueryWrapper from(Class<?>... entityClasses);
62
    
63
    /**
64
     * Add WHERE conditions
65
     * @param queryCondition condition to apply
66
     * @return query wrapper for chaining
67
     */
68
    public QueryWrapper where(QueryCondition queryCondition);
69
    
70
    /**
71
     * Add LEFT JOIN clause
72
     * @param entityClass entity class to join
73
     * @return query wrapper for chaining
74
     */
75
    public QueryWrapper leftJoin(Class<?> entityClass);
76
    
77
    /**
78
     * Add INNER JOIN clause
79
     * @param entityClass entity class to join
80
     * @return query wrapper for chaining
81
     */
82
    public QueryWrapper innerJoin(Class<?> entityClass);
83
    
84
    /**
85
     * Add RIGHT JOIN clause
86
     * @param entityClass entity class to join
87
     * @return query wrapper for chaining
88
     */
89
    public QueryWrapper rightJoin(Class<?> entityClass);
90
    
91
    /**
92
     * Add GROUP BY clause
93
     * @param queryColumns columns to group by
94
     * @return query wrapper for chaining
95
     */
96
    public QueryWrapper groupBy(QueryColumn... queryColumns);
97
    
98
    /**
99
     * Add HAVING clause for group conditions
100
     * @param queryCondition having condition
101
     * @return query wrapper for chaining
102
     */
103
    public QueryWrapper having(QueryCondition queryCondition);
104
    
105
    /**
106
     * Add ORDER BY clause
107
     * @param queryColumns columns to order by
108
     * @return query wrapper for chaining
109
     */
110
    public QueryWrapper orderBy(QueryColumn... queryColumns);
111
    
112
    /**
113
     * Limit number of results
114
     * @param rows maximum number of rows
115
     * @return query wrapper for chaining
116
     */
117
    public QueryWrapper limit(Number rows);
118
    
119
    /**
120
     * Set result offset for pagination
121
     * @param offset number of rows to skip
122
     * @return query wrapper for chaining
123
     */
124
    public QueryWrapper offset(Number offset);
125
    
126
    /**
127
     * Add UNION clause
128
     * @param queryWrapper query to union with
129
     * @return query wrapper for chaining
130
     */
131
    public QueryWrapper union(QueryWrapper queryWrapper);
132
    
133
    /**
134
     * Add UNION ALL clause
135
     * @param queryWrapper query to union with
136
     * @return query wrapper for chaining
137
     */
138
    public QueryWrapper unionAll(QueryWrapper queryWrapper);
139
}
140
```
141

142
**Basic Query Building:**
143

144
```java
145
import static com.mybatisflex.core.query.QueryMethods.*;
146

147
// Simple select
148
QueryWrapper query = QueryWrapper.create()
149
    .select()
150
    .from(User.class)
151
    .where(USER.AGE.ge(18));
152

153
// Select specific columns
154
QueryWrapper query = QueryWrapper.create()
155
    .select(USER.NAME, USER.EMAIL)
156
    .from(User.class)
157
    .where(USER.ACTIVE.eq(true));
158

159
// Complex conditions
160
QueryWrapper query = QueryWrapper.create()
161
    .select()
162
    .from(User.class)
163
    .where(USER.AGE.between(18, 65)
164
        .and(USER.CITY.in("New York", "London", "Tokyo"))
165
        .or(USER.VIP_LEVEL.ge(5)));
166
```
167

168
**Advanced Query Features:**
169

170
```java
171
// Joins
172
QueryWrapper query = QueryWrapper.create()
173
    .select(USER.NAME, ORDER.TOTAL)
174
    .from(User.class)
175
    .leftJoin(Order.class).on(USER.ID.eq(ORDER.USER_ID))
176
    .where(ORDER.STATUS.eq("COMPLETED"));
177

178
// Grouping and aggregation
179
QueryWrapper query = QueryWrapper.create()
180
    .select(USER.CITY, count(USER.ID).as("user_count"))
181
    .from(User.class)
182
    .where(USER.ACTIVE.eq(true))
183
    .groupBy(USER.CITY)
184
    .having(count(USER.ID).ge(10))
185
    .orderBy(count(USER.ID).desc());
186

187
// Subqueries
188
QueryWrapper subQuery = QueryWrapper.create()
189
    .select(ORDER.USER_ID)
190
    .from(Order.class)
191
    .where(ORDER.TOTAL.ge(1000));
192

193
QueryWrapper query = QueryWrapper.create()
194
    .select()
195
    .from(User.class)
196
    .where(USER.ID.in(subQuery));
197
```
198

199
### QueryColumn
200

201
Represents database columns with type-safe operations and SQL function support.
202

203
```java { .api }
204
/**
205
 * Represents a database column with type-safe operations
206
 */
207
public class QueryColumn {
208
    /**
209
     * Create column reference
210
     * @param columnName database column name
211
     * @return QueryColumn instance
212
     */
213
    public static QueryColumn create(String columnName);
214
    
215
    /**
216
     * Create column reference with table alias
217
     * @param columnName database column name
218
     * @param tableAlias table alias
219
     * @return QueryColumn instance
220
     */
221
    public static QueryColumn create(String columnName, String tableAlias);
222
    
223
    /**
224
     * Add column alias
225
     * @param alias column alias
226
     * @return QueryColumn with alias
227
     */
228
    public QueryColumn as(String alias);
229
    
230
    // Comparison operations
231
    /**
232
     * Equal condition
233
     * @param value comparison value
234
     * @return QueryCondition
235
     */
236
    public QueryCondition eq(Object value);
237
    
238
    /**
239
     * Not equal condition
240
     * @param value comparison value
241
     * @return QueryCondition
242
     */
243
    public QueryCondition ne(Object value);
244
    
245
    /**
246
     * Greater than condition
247
     * @param value comparison value
248
     * @return QueryCondition
249
     */
250
    public QueryCondition gt(Object value);
251
    
252
    /**
253
     * Greater than or equal condition
254
     * @param value comparison value
255
     * @return QueryCondition
256
     */
257
    public QueryCondition ge(Object value);
258
    
259
    /**
260
     * Less than condition
261
     * @param value comparison value
262
     * @return QueryCondition
263
     */
264
    public QueryCondition lt(Object value);
265
    
266
    /**
267
     * Less than or equal condition
268
     * @param value comparison value
269
     * @return QueryCondition
270
     */
271
    public QueryCondition le(Object value);
272
    
273
    /**
274
     * IN condition
275
     * @param values array of values
276
     * @return QueryCondition
277
     */
278
    public QueryCondition in(Object... values);
279
    
280
    /**
281
     * NOT IN condition
282
     * @param values array of values
283
     * @return QueryCondition
284
     */
285
    public QueryCondition notIn(Object... values);
286
    
287
    /**
288
     * BETWEEN condition
289
     * @param start start value
290
     * @param end end value
291
     * @return QueryCondition
292
     */
293
    public QueryCondition between(Object start, Object end);
294
    
295
    /**
296
     * LIKE condition
297
     * @param pattern like pattern
298
     * @return QueryCondition
299
     */
300
    public QueryCondition like(String pattern);
301
    
302
    /**
303
     * IS NULL condition
304
     * @return QueryCondition
305
     */
306
    public QueryCondition isNull();
307
    
308
    /**
309
     * IS NOT NULL condition
310
     * @return QueryCondition
311
     */
312
    public QueryCondition isNotNull();
313
    
314
    // SQL functions
315
    /**
316
     * COUNT function
317
     * @return QueryColumn with COUNT
318
     */
319
    public QueryColumn count();
320
    
321
    /**
322
     * SUM function
323
     * @return QueryColumn with SUM
324
     */
325
    public QueryColumn sum();
326
    
327
    /**
328
     * AVG function
329
     * @return QueryColumn with AVG
330
     */
331
    public QueryColumn avg();
332
    
333
    /**
334
     * MAX function
335
     * @return QueryColumn with MAX
336
     */
337
    public QueryColumn max();
338
    
339
    /**
340
     * MIN function
341
     * @return QueryColumn with MIN
342
     */
343
    public QueryColumn min();
344
}
345
```
346

347
**Column Operations Examples:**
348

349
```java
350
// Basic comparisons
351
QueryCondition condition1 = USER.AGE.ge(18);
352
QueryCondition condition2 = USER.NAME.like("A%");
353
QueryCondition condition3 = USER.EMAIL.isNotNull();
354

355
// IN conditions
356
QueryCondition condition4 = USER.CITY.in("New York", "London", "Tokyo");
357
QueryCondition condition5 = USER.STATUS.notIn("DELETED", "SUSPENDED");
358

359
// BETWEEN conditions
360
QueryCondition condition6 = USER.CREATE_TIME.between(startDate, endDate);
361
QueryCondition condition7 = USER.SALARY.between(50000, 100000);
362

363
// SQL functions
364
QueryColumn userCount = USER.ID.count().as("total_users");
365
QueryColumn avgAge = USER.AGE.avg().as("average_age");
366
QueryColumn maxSalary = USER.SALARY.max().as("max_salary");
367
```
368

369
### QueryCondition
370

371
Represents WHERE clause conditions with logical operators for combining multiple conditions.
372

373
```java { .api }
374
/**
375
 * Represents query conditions with logical operations
376
 */
377
public class QueryCondition {
378
    /**
379
     * Combine with AND logic
380
     * @param condition condition to combine
381
     * @return combined QueryCondition
382
     */
383
    public QueryCondition and(QueryCondition condition);
384
    
385
    /**
386
     * Combine with OR logic
387
     * @param condition condition to combine
388
     * @return combined QueryCondition
389
     */
390
    public QueryCondition or(QueryCondition condition);
391
    
392
    /**
393
     * Negate condition with NOT
394
     * @return negated QueryCondition
395
     */
396
    public QueryCondition not();
397
}
398
```
399

400
**Condition Combining Examples:**
401

402
```java
403
// Complex condition building
404
QueryCondition complexCondition = USER.AGE.ge(18)
405
    .and(USER.ACTIVE.eq(true))
406
    .and(USER.CITY.in("New York", "London")
407
        .or(USER.VIP_LEVEL.ge(5)));
408

409
// Negation
410
QueryCondition notCondition = USER.STATUS.eq("DELETED").not();
411

412
// Grouped conditions
413
QueryCondition grouped = USER.AGE.between(25, 35)
414
    .and(USER.SALARY.ge(60000)
415
        .or(USER.EDUCATION.eq("PhD")));
416
```
417

418
### QueryMethods
419

420
Static utility methods for common query operations and SQL functions.
421

422
```java { .api }
423
/**
424
 * Static utility methods for query building
425
 */
426
public class QueryMethods {
427
    /**
428
     * SELECT all columns
429
     * @return QueryColumn array for all columns
430
     */
431
    public static QueryColumn[] selectAll();
432
    
433
    /**
434
     * COUNT function
435
     * @param column column to count
436
     * @return QueryColumn with COUNT
437
     */
438
    public static QueryColumn count(QueryColumn column);
439
    
440
    /**
441
     * COUNT(*) function
442
     * @return QueryColumn with COUNT(*)
443
     */
444
    public static QueryColumn count();
445
    
446
    /**
447
     * DISTINCT function
448
     * @param column column for distinct
449
     * @return QueryColumn with DISTINCT
450
     */
451
    public static QueryColumn distinct(QueryColumn column);
452
    
453
    /**
454
     * SUM function
455
     * @param column column to sum
456
     * @return QueryColumn with SUM
457
     */
458
    public static QueryColumn sum(QueryColumn column);
459
    
460
    /**
461
     * AVG function
462
     * @param column column to average
463
     * @return QueryColumn with AVG
464
     */
465
    public static QueryColumn avg(QueryColumn column);
466
    
467
    /**
468
     * MAX function
469
     * @param column column to find maximum
470
     * @return QueryColumn with MAX
471
     */
472
    public static QueryColumn max(QueryColumn column);
473
    
474
    /**
475
     * MIN function
476
     * @param column column to find minimum
477
     * @return QueryColumn with MIN
478
     */
479
    public static QueryColumn min(QueryColumn column);
480
}
481
```
482

483
**Static Method Examples:**
484

485
```java
486
import static com.mybatisflex.core.query.QueryMethods.*;
487

488
// Using static methods
489
QueryWrapper query = QueryWrapper.create()
490
    .select(count(), avg(USER.AGE), max(USER.SALARY))
491
    .from(User.class)
492
    .where(USER.ACTIVE.eq(true));
493
    
494
// Distinct queries
495
QueryWrapper distinctQuery = QueryWrapper.create()
496
    .select(distinct(USER.CITY))
497
    .from(User.class);
498
```
499

500
### Lambda Support
501

502
Type-safe column references using lambda expressions for compile-time checking.
503

504
```java { .api }
505
/**
506
 * Lambda getter interface for type-safe column references
507
 * @param <T> entity type
508
 */
509
public interface LambdaGetter<T> extends Serializable, Function<T, Object> {
510
    // Marker interface for lambda getters
511
}
512
```
513

514
**Lambda Examples:**
515

516
```java
517
// Type-safe column selection with lambdas
518
QueryWrapper lambdaQuery = QueryWrapper.create()
519
    .select(User::getName, User::getEmail, User::getAge)
520
    .from(User.class)
521
    .where(USER.ACTIVE.eq(true));
522

523
// Lambda conditions (if supported by entity fields)
524
QueryWrapper conditionQuery = QueryWrapper.create()
525
    .select()
526
    .from(User.class)
527
    .where(USER.AGE.ge(18));
528
```
529

530
## Types
531

532
```java { .api }
533
// Core query types
534
public class QueryTable {
535
    public static QueryTable create(String tableName);
536
    public static QueryTable create(Class<?> entityClass);
537
    public QueryTable as(String alias);
538
}
539

540
// Order by support
541
public class QueryOrderBy {
542
    public static QueryOrderBy asc(QueryColumn column);
543
    public static QueryOrderBy desc(QueryColumn column);
544
}
545

546
// Join conditions
547
public class JoinCondition {
548
    public JoinCondition on(QueryCondition condition);
549
    public JoinCondition and(QueryCondition condition);
550
    public JoinCondition or(QueryCondition condition);
551
}
552

553
// Functional interfaces
554
@FunctionalInterface
555
public interface LambdaGetter<T> extends Serializable, Function<T, Object> {
556
}
557
```