0
# Expression System
1

2
Rich expression language for data manipulation, filtering, and computation with support for arithmetic, logical, string, and temporal operations in Apache Flink's Table API.
3

4
## Capabilities
5

6
### Expression Factory
7

8
Central factory for creating expressions with static imports for concise syntax.
9

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

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

25
/**
26
 * Create a null literal of specific type
27
 * @param dataType Type of the null value
28
 * @return Expression representing typed null
29
 */
30
public static Expression nullOf(DataType dataType);
31

32
/**
33
 * Create a range expression for array slicing
34
 * @param start Start index (inclusive)
35
 * @param end End index (exclusive)
36
 * @return Range expression for array operations
37
 */
38
public static Expression range(int start, int end);
39
```
40

41
**Basic Usage:**
42

43
```java
44
import static org.apache.flink.table.api.Expressions.*;
45

46
// Column references
47
Expression userId = $("user_id");
48
Expression userName = $("name");
49

50
// Literals
51
Expression hundred = lit(100);
52
Expression greeting = lit("Hello");
53
Expression pi = lit(3.14159);
54
Expression isActive = lit(true);
55

56
// Null values
57
Expression nullString = nullOf(DataTypes.STRING());
58
Expression nullTimestamp = nullOf(DataTypes.TIMESTAMP());
59
```
60

61
### Arithmetic Operations
62

63
Mathematical operations for numeric expressions.
64

65
```java { .api }
66
// Basic arithmetic
67
public Expression plus(Object other);
68
public Expression minus(Object other);
69
public Expression times(Object other);
70
public Expression dividedBy(Object other);
71
public Expression mod(Object other);
72

73
// Unary operations  
74
public Expression unaryMinus();
75
public Expression unaryPlus();
76

77
// Power and mathematical functions
78
public Expression power(Object exponent);
79
public Expression abs();
80
public Expression sqrt();
81
public Expression exp();
82
public Expression log();
83
public Expression log10();
84
public Expression log2();
85
public Expression ln();
86

87
// Trigonometric functions
88
public Expression sin();
89
public Expression cos();
90
public Expression tan();
91
public Expression asin();
92
public Expression acos();
93
public Expression atan();
94
public Expression sinh();
95
public Expression cosh();
96
public Expression tanh();
97

98
// Rounding functions
99
public Expression ceil();
100
public Expression floor();
101
public Expression round();
102
public Expression round(int scale);
103
```
104

105
**Arithmetic Examples:**
106

107
```java
108
// Basic calculations
109
Expression totalPrice = $("quantity").times($("unit_price"));
110
Expression discount = $("price").times(lit(0.1));
111
Expression finalPrice = $("price").minus(discount);
112

113
// Mathematical functions
114
Expression distance = $("x").power(lit(2)).plus($("y").power(lit(2))).sqrt();
115
Expression logValue = $("value").log();
116
Expression roundedPrice = $("price").round(2);
117
```
118

119
### Comparison Operations
120

121
Comparison and equality operations returning boolean expressions.
122

123
```java { .api }
124
// Equality comparisons
125
public Expression isEqual(Object other);
126
public Expression isNotEqual(Object other);
127

128
// Ordering comparisons
129
public Expression isGreater(Object other);
130
public Expression isGreaterOrEqual(Object other);
131
public Expression isLess(Object other);
132
public Expression isLessOrEqual(Object other);
133

134
// Null checks
135
public Expression isNull();
136
public Expression isNotNull();
137

138
// Range operations
139
public Expression between(Object lower, Object upper);
140
public Expression notBetween(Object lower, Object upper);
141

142
// Set membership
143
public Expression in(Object... values);
144
public Expression notIn(Object... values);
145
```
146

147
**Comparison Examples:**
148

149
```java
150
// Age filtering
151
Expression adults = $("age").isGreaterOrEqual(lit(18));
152
Expression seniors = $("age").between(lit(65), lit(100));
153

154
// Price comparisons
155
Expression expensive = $("price").isGreater(lit(1000));
156
Expression affordable = $("price").isLessOrEqual(lit(100));
157

158
// Null handling
159
Expression hasEmail = $("email").isNotNull();
160
Expression validUser = $("name").isNotNull().and($("email").isNotNull());
161

162
// Category filtering
163
Expression popularCategories = $("category").in(lit("electronics"), lit("books"), lit("clothing"));
164
```
165

166
### Logical Operations
167

168
Boolean logic operations for combining and negating expressions.
169

170
```java { .api }
171
/**
172
 * Logical AND operation
173
 * @param other Expression to AND with
174
 * @return Boolean expression representing AND result
175
 */
176
public Expression and(Object other);
177

178
/**
179
 * Logical OR operation
180
 * @param other Expression to OR with
181
 * @return Boolean expression representing OR result
182
 */
183
public Expression or(Object other);
184

185
/**
186
 * Logical NOT operation
187
 * @return Boolean expression representing NOT result
188
 */
189
public Expression not();
190
```
191

192
**Logical Examples:**
193

194
```java
195
// Complex filtering conditions
196
Expression validOrder = $("amount").isGreater(lit(0))
197
    .and($("status").isEqual(lit("confirmed")))
198
    .and($("customer_id").isNotNull());
199

200
Expression weekendOrEvening = $("day_of_week").in(lit("Saturday"), lit("Sunday"))
201
    .or($("hour").isGreaterOrEqual(lit(18)));
202

203
Expression notCancelled = $("status").isNotEqual(lit("cancelled"));
204
```
205

206
### String Operations
207

208
Text manipulation and pattern matching operations.
209

210
```java { .api }
211
// Case conversion
212
public Expression upperCase();
213
public Expression lowerCase();
214
public Expression initCap();
215

216
// String manipulation
217
public Expression substring(int start);
218
public Expression substring(int start, int length);
219
public Expression trim();
220
public Expression ltrim();
221
public Expression rtrim();
222
public Expression repeat(int times);
223
public Expression reverse();
224

225
// String operations
226
public Expression concat(Object... others);
227
public Expression length();
228
public Expression charLength();
229
public Expression position(String substring);
230
public Expression overlay(String replacement, int start);
231
public Expression overlay(String replacement, int start, int length);
232

233
// Pattern matching
234
public Expression like(String pattern);
235
public Expression notLike(String pattern);
236
public Expression similar(String pattern);
237
public Expression notSimilar(String pattern);
238
public Expression rlike(String pattern);
239

240
// String splitting and parsing
241
public Expression split(String delimiter);
242
public Expression regexpReplace(String pattern, String replacement);
243
public Expression regexpExtract(String pattern);
244
public Expression regexpExtract(String pattern, int group);
245
```
246

247
**String Examples:**
248

249
```java
250
// Text processing
251
Expression cleanName = $("name").trim().upperCase();
252
Expression firstName = $("full_name").split(lit(" ")).at(lit(0));
253
Expression emailDomain = $("email").regexpExtract(lit("@(.+)"), lit(1));
254

255
// Pattern matching
256
Expression gmailUsers = $("email").like(lit("%@gmail.com"));
257
Expression phoneNumbers = $("phone").rlike(lit("\\d{3}-\\d{3}-\\d{4}"));
258

259
// String construction
260
Expression fullAddress = $("street").concat(lit(", ")).concat($("city")).concat(lit(", ")).concat($("state"));
261
```
262

263
### Temporal Operations
264

265
Date, time, and timestamp manipulation functions.
266

267
```java { .api }
268
// Current time functions
269
public static Expression currentTimestamp();
270
public static Expression currentDate();
271
public static Expression currentTime();
272
public static Expression localTimestamp();
273
public static Expression localTime();
274

275
// Extraction functions
276
public Expression year();
277
public Expression quarter();
278
public Expression month();
279
public Expression week();
280
public Expression dayOfYear();
281
public Expression dayOfMonth();
282
public Expression dayOfWeek();
283
public Expression hour();
284
public Expression minute();
285
public Expression second();
286

287
// Date/time arithmetic
288
public Expression plus(IntervalUnit unit, int amount);
289
public Expression minus(IntervalUnit unit, int amount);
290
public Expression plus(Expression interval);
291
public Expression minus(Expression interval);
292

293
// Conversion functions
294
public Expression toDate();
295
public Expression toTime();
296
public Expression toTimestamp();
297
public Expression toTimestampLtz();
298

299
// Formatting functions
300
public Expression dateFormat(String format);
301
public Expression timestampDiff(TimePointUnit unit, Expression other);
302
```
303

304
**Temporal Examples:**
305

306
```java
307
// Date extraction
308
Expression orderYear = $("order_date").year();
309
Expression orderMonth = $("order_date").month();
310
Expression orderHour = $("created_at").hour();
311

312
// Date arithmetic
313
Expression oneWeekLater = $("start_date").plus(IntervalUnit.WEEK, 1);
314
Expression ageInYears = currentDate().minus($("birth_date")).dividedBy(lit(365));
315

316
// Time-based filtering
317
Expression recentOrders = $("order_date").isGreater(currentTimestamp().minus(IntervalUnit.DAY, 7));
318
Expression businessHours = $("created_at").hour().between(lit(9), lit(17));
319

320
// Date formatting
321
Expression formattedDate = $("order_date").dateFormat(lit("yyyy-MM-dd"));
322
```
323

324
### Array Operations
325

326
Operations for working with array-typed columns.
327

328
```java { .api }
329
// Array access
330
public Expression at(Object index);
331
public Expression cardinality();
332

333
// Array manipulation
334
public Expression element();
335
public Expression slice(int start, int end);
336

337
// Array predicates
338
public Expression exists(Expression predicate);
339
public Expression forall(Expression predicate);
340
```
341

342
**Array Examples:**
343

344
```java
345
// Array element access
346
Expression firstTag = $("tags").at(lit(0));
347
Expression tagCount = $("tags").cardinality();
348

349
// Array operations
350
Expression hasImportantTag = $("tags").exists($("item").like(lit("important%")));
351
Expression recentTags = $("tags").slice(lit(0), lit(5));
352
```
353

354
### JSON Operations
355

356
JSON data processing and extraction functions.
357

358
```java { .api }
359
// JSON extraction
360
public Expression jsonValue(String path);
361
public Expression jsonValue(String path, JsonValueOnEmptyOrError onEmpty, 
362
                          JsonValueOnEmptyOrError onError);
363
public Expression jsonQuery(String path);
364
public Expression jsonExists(String path);
365

366
// JSON type checking
367
public Expression isJson();
368
public Expression isJson(JsonType type);
369
```
370

371
**JSON Examples:**
372

373
```java
374
// JSON data extraction
375
Expression customerName = $("json_data").jsonValue(lit("$.customer.name"));
376
Expression orderItems = $("order_json").jsonQuery(lit("$.items[*]"));
377
Expression hasShipping = $("order_json").jsonExists(lit("$.shipping"));
378

379
// JSON validation
380
Expression validJson = $("data").isJson();
381
Expression jsonObject = $("data").isJson(JsonType.OBJECT);
382
```
383

384
### Conditional Expressions
385

386
Conditional logic and case statements.
387

388
```java { .api }
389
/**
390
 * Simple CASE WHEN expression
391
 * @param condition Boolean expression
392
 * @param thenValue Value when condition is true
393
 * @param elseValue Value when condition is false
394
 * @return Conditional expression
395
 */
396
public static Expression when(Expression condition, Object thenValue, Object elseValue);
397

398
/**
399
 * Multi-branch CASE expression
400
 * @param condition First condition
401
 * @param thenValue Value for first condition
402
 * @return CaseExpression for chaining additional when clauses
403
 */
404
public static CaseExpression when(Expression condition, Object thenValue);
405

406
public interface CaseExpression extends Expression {
407
    public CaseExpression when(Expression condition, Object thenValue);
408
    public Expression otherwise(Object elseValue);
409
}
410

411
/**
412
 * Null coalescing - return first non-null value
413
 * @param expressions Expressions to check in order
414
 * @return First non-null expression value
415
 */
416
public static Expression coalesce(Expression... expressions);
417

418
/**
419
 * Null-safe equality check
420
 * @param left Left expression
421
 * @param right Right expression
422
 * @return Boolean indicating null-safe equality
423
 */
424
public static Expression nullIf(Expression left, Expression right);
425
```
426

427
**Conditional Examples:**
428

429
```java
430
// Simple conditional
431
Expression priceCategory = when($("price").isGreater(lit(100)), lit("expensive"), lit("affordable"));
432

433
// Multi-branch case
434
Expression ageGroup = when($("age").isLess(lit(18)), lit("minor"))
435
    .when($("age").isLess(lit(65)), lit("adult"))
436
    .otherwise(lit("senior"));
437

438
// Null handling
439
Expression displayName = coalesce($("nickname"), $("first_name"), lit("Anonymous"));
440
Expression cleanValue = nullIf($("value"), lit(""));
441
```
442

443
### Aggregate Functions
444

445
Functions for computing aggregations (used with groupBy).
446

447
```java { .api }
448
// Count functions
449
public Expression count();
450
public Expression countDistinct();
451

452
// Numeric aggregations
453
public Expression sum();
454
public Expression avg();
455
public Expression min();
456
public Expression max();
457
public Expression stddev();
458
public Expression variance();
459

460
// String aggregations
461
public Expression concat(String delimiter);
462
public Expression listAgg();
463
public Expression listAgg(String delimiter);
464

465
// Collection functions
466
public Expression collect();
467
public Expression mode();
468
```
469

470
**Aggregate Examples:**
471

472
```java
473
// Numeric aggregations
474
Table orderSummary = orders
475
    .groupBy($("customer_id"))
476
    .select($("customer_id"),
477
            $("amount").sum().as("total_spent"),
478
            $("order_id").count().as("order_count"),
479
            $("amount").avg().as("avg_order_value"));
480

481
// String aggregations
482
Table customerTags = orders
483
    .groupBy($("customer_id"))
484
    .select($("customer_id"),
485
            $("product_category").listAgg(lit(", ")).as("categories"));
486
```
487

488
### Window Functions
489

490
Functions for window-based calculations (used with window specifications).
491

492
```java { .api }
493
// Ranking functions
494
public Expression rowNumber();
495
public Expression rank();
496
public Expression denseRank();
497
public Expression percentRank();
498

499
// Value functions
500
public Expression lag(int offset);
501
public Expression lag(int offset, Object defaultValue);
502
public Expression lead(int offset);
503
public Expression lead(int offset, Object defaultValue);
504
public Expression firstValue();
505
public Expression lastValue();
506
public Expression nthValue(int n);
507
```
508

509
**Window Function Examples:**
510

511
```java
512
// Ranking within groups
513
Table rankedProducts = sales
514
    .window(Over.partitionBy($("category")).orderBy($("sales").desc()).as("w"))
515
    .select($("product"), $("category"), $("sales"),
516
            $("sales").rank().over($("w")).as("sales_rank"));
517

518
// Time series analysis
519
Table timeSeriesData = events
520
    .window(Over.partitionBy($("user_id")).orderBy($("timestamp")).as("w"))
521
    .select($("user_id"), $("value"), $("timestamp"),
522
            $("value").lag(1).over($("w")).as("previous_value"));
523
```