0
# Expressions and Column References
1

2
The expression system provides type-safe column references, function calls, and complex predicates for table operations. The Expressions utility class offers static methods for creating various types of expressions.
3

4
## Capabilities
5

6
### Column References and Literals
7

8
Create references to table columns and literal values.
9

10
```java { .api }
11
/**
12
 * Creates a column reference expression
13
 * @param name Column name
14
 * @return Expression referencing the specified column
15
 */
16
public static Expression $(String name);
17

18
/**
19
 * Creates a literal value expression
20
 * @param value Literal value (String, Number, Boolean, etc.)
21
 * @return Expression representing the literal value
22
 */
23
public static Expression lit(Object value);
24

25
/**
26
 * Creates a column reference from a table and column
27
 * @param table Table alias or name
28
 * @param column Column name
29
 * @return Qualified column reference expression
30
 */
31
public static Expression $(String table, String column);
32
```
33

34
**Usage Examples:**
35

36
```java
37
import static org.apache.flink.table.api.Expressions.*;
38

39
// Column references
40
Expression nameCol = $("name");
41
Expression ageCol = $("age"); 
42
Expression qualifiedCol = $("employees", "salary");
43

44
// Literals
45
Expression stringLit = lit("Active");
46
Expression numberLit = lit(100);
47
Expression boolLit = lit(true);
48
Expression nullLit = lit(null);
49

50
// Using in table operations
51
Table result = sourceTable.select(
52
    $("employee_id"),
53
    $("name"),
54
    lit("EMPLOYEE").as("type"),
55
    lit(1.0).as("multiplier")
56
);
57
```
58

59
### Arithmetic Operations
60

61
Perform mathematical operations on numeric expressions.
62

63
```java { .api }
64
/**
65
 * Addition operation
66
 * @param left Left operand expression
67
 * @param right Right operand expression
68
 * @return Expression representing left + right
69
 */
70
public static Expression plus(Object left, Object right);
71

72
/**
73
 * Subtraction operation
74
 * @param left Left operand expression  
75
 * @param right Right operand expression
76
 * @return Expression representing left - right
77
 */
78
public static Expression minus(Object left, Object right);
79

80
/**
81
 * Multiplication operation
82
 * @param left Left operand expression
83
 * @param right Right operand expression
84
 * @return Expression representing left * right
85
 */
86
public static Expression times(Object left, Object right);
87

88
/**
89
 * Division operation
90
 * @param left Left operand expression
91
 * @param right Right operand expression
92
 * @return Expression representing left / right
93
 */
94
public static Expression dividedBy(Object left, Object right);
95

96
/**
97
 * Modulo operation
98
 * @param left Left operand expression
99
 * @param right Right operand expression
100
 * @return Expression representing left % right
101
 */
102
public static Expression mod(Object left, Object right);
103
```
104

105
**Usage Examples:**
106

107
```java
108
// Basic arithmetic
109
Expression totalSalary = plus($("base_salary"), $("bonus"));
110
Expression netPay = minus($("gross_pay"), $("deductions"));
111
Expression area = times($("length"), $("width"));
112
Expression average = dividedBy($("total"), $("count"));
113

114
// Chain operations using Expression methods
115
Expression complexCalc = $("salary")
116
    .multiply(1.1)  // 10% increase
117
    .plus($("bonus"))
118
    .minus($("tax"));
119

120
// Mixed literals and columns
121
Expression adjustedPrice = $("price").multiply(lit(1.08)); // Add 8% tax
122
```
123

124
### Comparison Operations
125

126
Compare values using various comparison operators.
127

128
```java { .api }
129
/**
130
 * Equality comparison
131
 * @param left Left operand expression
132
 * @param right Right operand expression
133
 * @return Boolean expression for left == right
134
 */
135
public static Expression isEqual(Object left, Object right);
136

137
/**
138
 * Inequality comparison
139
 * @param left Left operand expression
140
 * @param right Right operand expression
141
 * @return Boolean expression for left != right
142
 */
143
public static Expression isNotEqual(Object left, Object right);
144

145
/**
146
 * Greater than comparison
147
 * @param left Left operand expression
148
 * @param right Right operand expression
149
 * @return Boolean expression for left > right
150
 */
151
public static Expression isGreater(Object left, Object right);
152

153
/**
154
 * Greater than or equal comparison
155
 * @param left Left operand expression
156
 * @param right Right operand expression
157
 * @return Boolean expression for left >= right
158
 */
159
public static Expression isGreaterOrEqual(Object left, Object right);
160

161
/**
162
 * Less than comparison
163
 * @param left Left operand expression
164
 * @param right Right operand expression
165
 * @return Boolean expression for left < right
166
 */
167
public static Expression isLess(Object left, Object right);
168

169
/**
170
 * Less than or equal comparison
171
 * @param left Left operand expression
172
 * @param right Right operand expression
173
 * @return Boolean expression for left <= right
174
 */
175
public static Expression isLessOrEqual(Object left, Object right);
176
```
177

178
**Usage Examples:**
179

180
```java
181
// Comparison filters
182
Table adults = sourceTable.filter(isGreaterOrEqual($("age"), 18));
183
Table highEarners = sourceTable.filter(isGreater($("salary"), 100000));
184
Table specificDept = sourceTable.filter(isEqual($("department"), "Engineering"));
185

186
// Complex comparisons
187
Table filtered = sourceTable.filter(
188
    isGreaterOrEqual($("experience_years"), 5)
189
    .and(isLessOrEqual($("age"), 50))
190
    .and(isNotEqual($("status"), "INACTIVE"))
191
);
192
```
193

194
### Logical Operations
195

196
Combine boolean expressions using logical operators.
197

198
```java { .api }
199
/**
200
 * Logical AND operation
201
 * @param left Left boolean expression
202
 * @param right Right boolean expression
203
 * @return Boolean expression for left AND right
204
 */
205
public static Expression and(Object left, Object right);
206

207
/**
208
 * Logical OR operation
209
 * @param left Left boolean expression
210
 * @param right Right boolean expression
211
 * @return Boolean expression for left OR right
212
 */
213
public static Expression or(Object left, Object right);
214

215
/**
216
 * Logical NOT operation
217
 * @param expression Boolean expression to negate
218
 * @return Boolean expression for NOT expression
219
 */
220
public static Expression not(Object expression);
221
```
222

223
**Usage Examples:**
224

225
```java
226
// Logical combinations
227
Expression seniorDeveloper = and(
228
    isEqual($("role"), "Developer"),
229
    isGreaterOrEqual($("experience"), 5)
230
);
231

232
Expression eligibleForBonus = or(
233
    isEqual($("performance"), "Excellent"),
234
    and(
235
        isEqual($("performance"), "Good"),
236
        isGreaterOrEqual($("tenure"), 2)
237
    )
238
);
239

240
Expression notInactive = not(isEqual($("status"), "INACTIVE"));
241

242
// Using in table operations
243
Table filtered = sourceTable.filter(
244
    and(
245
        isGreaterOrEqual($("age"), 25),
246
        or(
247
            isEqual($("department"), "Engineering"),
248
            isEqual($("department"), "Research")
249
        )
250
    )
251
);
252
```
253

254
### String Operations
255

256
Work with string data using various string manipulation functions.
257

258
```java { .api }
259
/**
260
 * String concatenation
261
 * @param left Left string expression
262
 * @param right Right string expression
263
 * @return Expression for concatenated string
264
 */
265
public static Expression concat(Object left, Object right);
266

267
/**
268
 * String LIKE pattern matching
269
 * @param str String expression to match
270
 * @param pattern Pattern string with % and _ wildcards
271
 * @return Boolean expression for pattern match
272
 */
273
public static Expression like(Object str, Object pattern);
274

275
/**
276
 * String length function
277
 * @param str String expression
278
 * @return Expression for string length
279
 */
280
public static Expression length(Object str);
281

282
/**
283
 * Uppercase conversion
284
 * @param str String expression
285
 * @return Expression for uppercase string
286
 */
287
public static Expression upper(Object str);
288

289
/**
290
 * Lowercase conversion  
291
 * @param str String expression
292
 * @return Expression for lowercase string
293
 */
294
public static Expression lower(Object str);
295

296
/**
297
 * Trim whitespace from string
298
 * @param str String expression
299
 * @return Expression for trimmed string
300
 */
301
public static Expression trim(Object str);
302

303
/**
304
 * Substring extraction
305
 * @param str String expression
306
 * @param start Start position (1-based)
307
 * @param length Length of substring
308
 * @return Expression for substring
309
 */
310
public static Expression substring(Object str, Object start, Object length);
311
```
312

313
**Usage Examples:**
314

315
```java
316
// String operations
317
Table processed = sourceTable.select(
318
    $("id"),
319
    upper($("name")).as("name_upper"),
320
    concat($("first_name"), lit(" "), $("last_name")).as("full_name"),
321
    trim($("description")).as("clean_description")
322
);
323

324
// String filtering
325
Table nameFiltered = sourceTable.filter(like($("name"), "John%"));
326
Table domainFiltered = sourceTable.filter(like($("email"), "%@company.com"));
327

328
// String transformations
329
Table transformed = sourceTable.select(
330
    $("id"),
331
    substring($("code"), 1, 3).as("prefix"),
332
    length($("description")).as("desc_length"),
333
    lower(trim($("category"))).as("normalized_category")
334
);
335
```
336

337
### Null Handling
338

339
Handle null values in expressions and data.
340

341
```java { .api }
342
/**
343
 * Check if expression is null
344
 * @param expr Expression to check
345
 * @return Boolean expression for null check
346
 */
347
public static Expression isNull(Object expr);
348

349
/**
350
 * Check if expression is not null
351
 * @param expr Expression to check
352
 * @return Boolean expression for not null check
353
 */
354
public static Expression isNotNull(Object expr);
355

356
/**
357
 * Return alternative value if expression is null
358
 * @param expr Expression to check
359
 * @param ifNull Value to return if expr is null
360
 * @return Expression with null handling
361
 */
362
public static Expression ifNull(Object expr, Object ifNull);
363

364
/**
365
 * Null-safe equality comparison
366
 * @param left Left expression
367
 * @param right Right expression
368
 * @return Boolean expression for null-safe equality
369
 */
370
public static Expression isNotDistinctFrom(Object left, Object right);
371
```
372

373
**Usage Examples:**
374

375
```java
376
// Null checks
377
Table withNonNullEmails = sourceTable.filter(isNotNull($("email")));
378
Table missingPhones = sourceTable.filter(isNull($("phone")));
379

380
// Null handling
381
Table processed = sourceTable.select(
382
    $("id"),
383
    $("name"),
384
    ifNull($("middle_name"), lit("")).as("middle_name"),
385
    ifNull($("salary"), lit(0)).as("salary_or_zero")
386
);
387

388
// Null-safe comparisons
389
Table matched = sourceTable.filter(isNotDistinctFrom($("category"), lit("PREMIUM")));
390
```
391

392
### Conditional Expressions
393

394
Create conditional logic using CASE/WHEN expressions.
395

396
```java { .api }
397
/**
398
 * Creates a CASE WHEN expression builder
399
 * @param condition Boolean condition expression
400
 * @param result Result expression when condition is true
401
 * @return CaseWhenBuilder for additional when/otherwise clauses
402
 */
403
public static ApiExpression when(Object condition, Object result);
404
```
405

406
**Usage Examples:**
407

408
```java
409
// Simple conditional
410
Expression statusDescription = when($("status").isEqual("A"), "Active")
411
    .otherwise("Inactive");
412

413
// Multiple conditions
414
Expression salaryGrade = when($("salary").isGreater(100000), "Senior")
415
    .when($("salary").isGreater(70000), "Mid")
416
    .when($("salary").isGreater(40000), "Junior")
417
    .otherwise("Entry");
418

419
// Complex conditions
420
Expression performanceBonus = when(
421
        and(
422
            isEqual($("performance"), "Excellent"),
423
            isGreaterOrEqual($("tenure"), 1)
424
        ),
425
        $("salary").multiply(0.1)
426
    )
427
    .when(isEqual($("performance"), "Good"), $("salary").multiply(0.05))
428
    .otherwise(lit(0));
429

430
// Using in select
431
Table categorized = sourceTable.select(
432
    $("employee_id"),
433
    $("name"),
434
    $("salary"),
435
    salaryGrade.as("grade"),
436
    performanceBonus.as("bonus")
437
);
438
```
439

440
### Collection Operations
441

442
Work with array and collection data types.
443

444
```java { .api }
445
/**
446
 * Check if value is in a collection
447
 * @param expr Expression to check
448
 * @param values Collection of values to check against
449
 * @return Boolean expression for membership test
450
 */
451
public static Expression in(Object expr, Object... values);
452

453
/**
454
 * Array element access
455
 * @param array Array expression
456
 * @param index Index expression (0-based)
457
 * @return Expression for array element
458
 */
459
public static Expression at(Object array, Object index);
460

461
/**
462
 * Array cardinality (size)
463
 * @param array Array expression
464
 * @return Expression for array size
465
 */
466
public static Expression cardinality(Object array);
467
```
468

469
**Usage Examples:**
470

471
```java
472
// IN predicates
473
Table filtered = sourceTable.filter(
474
    in($("department"), "Engineering", "Research", "Product")
475
);
476

477
Table statusFiltered = sourceTable.filter(
478
    in($("status"), "ACTIVE", "PENDING", "APPROVED")
479
);
480

481
// Array operations (if your data contains arrays)
482
Table arrayProcessed = sourceTable.select(
483
    $("id"),
484
    at($("tags"), 0).as("primary_tag"),
485
    cardinality($("skills")).as("skill_count")
486
);
487
```
488

489
### Function Calls
490

491
Call built-in and user-defined functions.
492

493
```java { .api }
494
/**
495
 * Generic function call
496
 * @param name Function name
497
 * @param args Function arguments
498
 * @return Expression representing function call
499
 */
500
public static Expression call(String name, Object... args);
501

502
/**
503
 * Call user-defined function
504
 * @param function Function class or instance
505
 * @param args Function arguments
506
 * @return Expression representing UDF call
507
 */
508
public static Expression call(Class<?> function, Object... args);
509
```
510

511
**Usage Examples:**
512

513
```java
514
// Built-in function calls
515
Expression currentTime = call("CURRENT_TIMESTAMP");
516
Expression rounded = call("ROUND", $("price"), 2);
517
Expression dayOfWeek = call("DAYOFWEEK", $("created_date"));
518

519
// Mathematical functions
520
Expression sqrtValue = call("SQRT", $("area"));
521
Expression logValue = call("LOG", $("value"));
522

523
// User-defined function calls
524
Expression customHash = call("MY_HASH_FUNCTION", $("user_id"), $("timestamp"));
525

526
// Using in operations
527
Table processed = sourceTable.select(
528
    $("id"),
529
    call("UPPER", $("name")).as("name_upper"),
530
    call("DATE_FORMAT", $("created_date"), "yyyy-MM-dd").as("date_str"),
531
    call("GREATEST", $("score1"), $("score2"), $("score3")).as("max_score")
532
);
533
```
534

535
## Expression Interface Methods
536

537
The Expression interface provides instance methods for fluent operation chaining.
538

539
```java { .api }
540
public interface Expression {
541
    /**
542
     * Creates an alias for this expression
543
     * @param alias Alias name
544
     * @return Expression with alias
545
     */
546
    Expression as(String alias);
547
    
548
    /**
549
     * Equality comparison (instance method)
550
     * @param other Value to compare with
551
     * @return Boolean expression for equality
552
     */
553
    Expression isEqual(Object other);
554
    
555
    /**
556
     * Greater than comparison (instance method)
557
     * @param other Value to compare with
558
     * @return Boolean expression for greater than
559
     */
560
    Expression isGreater(Object other);
561
    
562
    /**
563
     * Addition (instance method)
564
     * @param other Value to add
565
     * @return Expression for addition
566
     */
567
    Expression plus(Object other);
568
    
569
    /**
570
     * Subtraction (instance method)
571
     * @param other Value to subtract
572
     * @return Expression for subtraction
573
     */
574
    Expression minus(Object other);
575
    
576
    /**
577
     * Multiplication (instance method)
578
     * @param other Value to multiply by
579
     * @return Expression for multiplication
580
     */
581
    Expression multiply(Object other);
582
    
583
    /**
584
     * String concatenation (instance method)
585
     * @param other String to concatenate
586
     * @return Expression for concatenation
587
     */
588
    Expression concat(Object other);
589
    
590
    /**
591
     * LIKE pattern matching (instance method)
592
     * @param pattern Pattern string
593
     * @return Boolean expression for pattern match
594
     */
595
    Expression like(Object pattern);
596
}
597
```
598

599
**Usage Examples:**
600

601
```java
602
// Fluent expression chaining
603
Expression complexExpr = $("base_salary")
604
    .multiply(lit(1.1))     // 10% increase
605
    .plus($("bonus"))       // Add bonus
606
    .minus($("tax"))        // Subtract tax
607
    .as("net_salary");      // Alias the result
608

609
// Method chaining for comparisons
610
Table filtered = sourceTable.filter(
611
    $("salary")
612
        .multiply(lit(12))  // Annual salary
613
        .isGreater(lit(100000))
614
);
615

616
// String method chaining
617
Expression processedName = $("raw_name")
618
    .concat(lit(" (processed)"))
619
    .as("processed_name");
620
```