0
# Table Operations and Transformations
1

2
The Table interface provides the core data transformation operations for manipulating table data. These operations create new Table instances in a functional programming style, allowing for method chaining and lazy evaluation.
3

4
## Capabilities
5

6
### Selection and Projection
7

8
Select specific columns and create computed columns from table data.
9

10
```java { .api }
11
/**
12
 * Selects specific fields from the table
13
 * @param fields Column expressions to select
14
 * @return New Table with selected fields
15
 */
16
public Table select(Expression... fields);
17

18
/**
19
 * Selects fields using string field references (deprecated)
20
 * @param fields Field names as strings
21
 * @return New Table with selected fields
22
 * @deprecated Use select(Expression...) instead
23
 */
24
@Deprecated
25
public Table select(String fields);
26
```
27

28
**Usage Examples:**
29

30
```java
31
import static org.apache.flink.table.api.Expressions.*;
32

33
// Basic column selection
34
Table result = sourceTable.select($("name"), $("age"), $("salary"));
35

36
// Computed columns
37
Table computed = sourceTable.select(
38
    $("name"),
39
    $("age"),
40
    $("salary").multiply(1.1).as("adjusted_salary"),
41
    $("first_name").concat($("last_name")).as("full_name")
42
);
43

44
// Complex expressions
45
Table complex = sourceTable.select(
46
    $("customer_id"),
47
    $("order_date").extract(IntervalUnit.YEAR).as("order_year"),
48
    when($("amount").isGreater(1000), "HIGH")
49
        .otherwise(when($("amount").isGreater(500), "MEDIUM")
50
        .otherwise("LOW")).as("order_category")
51
);
52
```
53

54
### Table Aliasing and Field Renaming
55

56
Rename table fields to resolve naming conflicts and improve readability.
57

58
```java { .api }
59
/**
60
 * Renames the fields of the table for disambiguation
61
 * @param field First field name
62
 * @param fields Additional field names
63
 * @return New Table with renamed fields
64
 */
65
public Table as(String field, String... fields);
66

67
/**
68
 * Renames fields using expressions (deprecated)
69
 * @param fields Field expressions for renaming
70
 * @return New Table with renamed fields
71
 * @deprecated Use as(String, String...) instead
72
 */
73
@Deprecated
74
public Table as(Expression... fields);
75
```
76

77
**Usage Examples:**
78

79
```java
80
// Rename all fields in order
81
Table renamedTable = sourceTable.as("customer_id", "customer_name", "total_orders");
82

83
// Use for disambiguation before joins
84
Table customers = customerTable.as("c_id", "c_name", "c_email");
85
Table orders = orderTable.as("o_id", "o_customer_id", "o_amount");
86

87
Table joined = customers.join(
88
    orders,
89
    $("c_id").isEqual($("o_customer_id"))
90
);
91
```
92

93
### Filtering and Predicates
94

95
Filter table rows based on boolean expressions and predicates.
96

97
```java { .api }
98
/**
99
 * Filters table rows based on the given predicate
100
 * @param predicate Boolean expression to filter on
101
 * @return New Table with filtered rows
102
 */
103
public Table filter(Expression predicate);
104

105
/**
106
 * Filters table rows using string expression (deprecated)
107
 * @param predicate Boolean expression as string
108
 * @return New Table with filtered rows
109
 * @deprecated Use filter(Expression) instead
110
 */
111
@Deprecated
112
public Table filter(String predicate);
113

114
/**
115
 * Alternative name for filter operation
116
 * @param predicate Boolean expression to filter on
117
 * @return New Table with filtered rows
118
 */
119
public Table where(Expression predicate);
120
```
121

122
**Usage Examples:**
123

124
```java
125
// Simple filters
126
Table adults = sourceTable.filter($("age").isGreaterOrEqual(18));
127
Table highSalary = sourceTable.filter($("salary").isGreater(50000));
128

129
// Complex predicates
130
Table filtered = sourceTable.filter(
131
    $("age").isGreaterOrEqual(25)
132
    .and($("department").isEqual("Engineering"))
133
    .and($("salary").isGreater(60000))
134
);
135

136
// String matching
137
Table nameFilter = sourceTable.filter($("name").like("John%"));
138

139
// Null checks
140
Table nonNull = sourceTable.filter($("email").isNotNull());
141

142
// IN predicates
143
Table departments = sourceTable.filter(
144
    $("department").in("Engineering", "Sales", "Marketing")
145
);
146
```
147

148
### Joins
149

150
Join operations for combining data from multiple tables.
151

152
```java { .api }
153
/**
154
 * Inner join with another table
155
 * @param right Table to join with
156
 * @param joinPredicate Join condition expression
157
 * @return New Table with joined data
158
 */
159
public Table join(Table right, Expression joinPredicate);
160

161
/**
162
 * Left outer join with another table
163
 * @param right Table to join with  
164
 * @param joinPredicate Join condition expression
165
 * @return New Table with left outer joined data
166
 */
167
public Table leftOuterJoin(Table right, Expression joinPredicate);
168

169
/**
170
 * Right outer join with another table
171
 * @param right Table to join with
172
 * @param joinPredicate Join condition expression
173
 * @return New Table with right outer joined data
174
 */
175
public Table rightOuterJoin(Table right, Expression joinPredicate);
176

177
/**
178
 * Full outer join with another table
179
 * @param right Table to join with
180
 * @param joinPredicate Join condition expression
181
 * @return New Table with full outer joined data
182
 */
183
public Table fullOuterJoin(Table right, Expression joinPredicate);
184

185
/**
186
 * Inner join with a table function (lateral join)
187
 * @param tableFunctionCall Table function call expression
188
 * @return New Table with lateral joined data
189
 */
190
public Table joinLateral(Expression tableFunctionCall);
191

192
/**
193
 * Inner join with a table function and join predicate
194
 * @param tableFunctionCall Table function call expression
195
 * @param joinPredicate Join condition expression
196
 * @return New Table with lateral joined data
197
 */
198
public Table joinLateral(Expression tableFunctionCall, Expression joinPredicate);
199

200
/**
201
 * Left outer join with a table function (lateral join)
202
 * @param tableFunctionCall Table function call expression
203
 * @return New Table with left outer lateral joined data
204
 */
205
public Table leftOuterJoinLateral(Expression tableFunctionCall);
206

207
/**
208
 * Left outer join with a table function and join predicate
209
 * @param tableFunctionCall Table function call expression
210
 * @param joinPredicate Join condition expression
211
 * @return New Table with left outer lateral joined data
212
 */
213
public Table leftOuterJoinLateral(Expression tableFunctionCall, Expression joinPredicate);
214
```
215

216
**Usage Examples:**
217

218
```java
219
Table customers = tableEnv.from("customers");
220
Table orders = tableEnv.from("orders");
221

222
// Inner join
223
Table customerOrders = customers.join(
224
    orders,
225
    $("customers.id").isEqual($("orders.customer_id"))
226
);
227

228
// Left outer join with column selection
229
Table allCustomers = customers
230
    .leftOuterJoin(orders, $("customers.id").isEqual($("orders.customer_id")))
231
    .select($("customers.name"), $("customers.email"), $("orders.order_id"), $("orders.amount"));
232

233
// Multiple join conditions
234
Table complexJoin = customers.join(
235
    orders,
236
    $("customers.id").isEqual($("orders.customer_id"))
237
    .and($("customers.region").isEqual($("orders.shipping_region")))
238
);
239

240
// Lateral join with table function (UDTF)
241
// Assuming you have a SplitFunction that splits strings
242
Table lateralResult = sourceTable
243
    .joinLateral(call("split_string", $("tags"), lit(",")))
244
    .select($("id"), $("name"), $("f0").as("tag"), $("f1").as("position"));
245

246
// Left outer lateral join with predicate
247
Table leftLateralResult = sourceTable
248
    .leftOuterJoinLateral(
249
        call("split_string", $("categories"), lit(";")),
250
        $("id").isGreater(100)
251
    )
252
    .select($("id"), $("name"), $("f0").as("category"));
253
```
254

255
### Grouping Operations
256

257
Group table data for aggregation operations.
258

259
```java { .api }
260
/**
261
 * Groups the table by the given fields
262
 * @param fields Fields to group by
263
 * @return GroupedTable for aggregation operations
264
 */
265
public GroupedTable groupBy(Expression... fields);
266

267
/**
268
 * Groups the table using string field references (deprecated)
269
 * @param fields Field names as strings
270
 * @return GroupedTable for aggregation operations
271
 * @deprecated Use groupBy(Expression...) instead
272
 */
273
@Deprecated
274
public GroupedTable groupBy(String fields);
275
```
276

277
**Usage Examples:**
278

279
```java
280
// Basic grouping
281
GroupedTable byDepartment = sourceTable.groupBy($("department"));
282

283
// Multiple grouping fields
284
GroupedTable byDeptAndLevel = sourceTable.groupBy($("department"), $("level"));
285

286
// Grouping with computed fields
287
GroupedTable byYearMonth = sourceTable.groupBy(
288
    $("hire_date").extract(IntervalUnit.YEAR).as("hire_year"),
289
    $("hire_date").extract(IntervalUnit.MONTH).as("hire_month")
290
);
291
```
292

293
### Sorting and Ordering
294

295
Sort table data by specified fields and ordering criteria.
296

297
```java { .api }
298
/**
299
 * Orders the table by the given fields in ascending order
300
 * @param fields Fields to order by
301
 * @return New Table with ordered data
302
 */
303
public Table orderBy(Expression... fields);
304

305
/**
306
 * Orders the table using string field references (deprecated)
307
 * @param fields Field names as strings
308
 * @return New Table with ordered data
309
 * @deprecated Use orderBy(Expression...) instead
310
 */
311
@Deprecated
312
public Table orderBy(String fields);
313
```
314

315
**Usage Examples:**
316

317
```java
318
// Single field ordering (ascending by default)
319
Table sorted = sourceTable.orderBy($("name"));
320

321
// Multiple fields with explicit ordering
322
Table multiSort = sourceTable.orderBy($("department").asc(), $("salary").desc());
323

324
// Order by computed expressions
325
Table computedSort = sourceTable.orderBy(
326
    $("salary").multiply($("bonus_factor")).desc(),
327
    $("hire_date").asc()
328
);
329
```
330

331
### Limiting and Offset
332

333
Limit the number of rows returned from table operations.
334

335
```java { .api }
336
/**
337
 * Limits the table to the first n rows
338
 * @param fetch Number of rows to return
339
 * @return New Table with limited rows
340
 */
341
public Table limit(int fetch);
342

343
/**
344
 * Limits the table with offset and fetch count
345
 * @param offset Number of rows to skip
346
 * @param fetch Number of rows to return after offset
347
 * @return New Table with limited rows
348
 */
349
public Table limit(int offset, int fetch);
350
```
351

352
**Usage Examples:**
353

354
```java
355
// Get first 10 rows
356
Table top10 = sourceTable
357
    .orderBy($("salary").desc())
358
    .limit(10);
359

360
// Pagination: skip 20 rows, take next 10
361
Table page3 = sourceTable
362
    .orderBy($("id"))
363
    .limit(20, 10);
364
```
365

366
### Set Operations
367

368
Combine tables using set operations like union and intersect.
369

370
```java { .api }
371
/**
372
 * Union with another table (removes duplicates)
373
 * @param right Table to union with
374
 * @return New Table with union of both tables
375
 */
376
public Table union(Table right);
377

378
/**
379
 * Union all with another table (keeps duplicates)
380
 * @param right Table to union with
381
 * @return New Table with union of both tables including duplicates
382
 */
383
public Table unionAll(Table right);
384

385
/**
386
 * Intersect with another table
387
 * @param right Table to intersect with
388
 * @return New Table with intersection of both tables
389
 */
390
public Table intersect(Table right);
391

392
/**
393
 * Minus operation with another table
394
 * @param right Table to subtract
395
 * @return New Table with rows from left table not in right table
396
 */
397
public Table minus(Table right);
398
```
399

400
### Distinct Operations
401

402
Remove duplicate rows from table data.
403

404
```java { .api }
405
/**
406
 * Returns distinct rows from the table
407
 * @return New Table with duplicate rows removed
408
 */
409
public Table distinct();
410
```
411

412
**Usage Examples:**
413

414
```java
415
// Remove duplicates
416
Table uniqueCustomers = sourceTable.distinct();
417

418
// Distinct on specific columns (via groupBy)
419
Table uniqueDepartments = sourceTable
420
    .groupBy($("department"))
421
    .select($("department"));
422
```
423

424
### Execution Operations
425

426
Execute table operations and retrieve results.
427

428
```java { .api }
429
/**
430
 * Executes the table operation and returns results
431
 * @return TableResult containing the execution results
432
 */
433
public TableResult execute();
434

435
/**
436
 * Executes the table as an insert operation into the specified table
437
 * @param tablePath Target table path for insertion
438
 * @return TableResult containing execution status
439
 */
440
public TableResult executeInsert(String tablePath);
441

442
/**
443
 * Explains the execution plan for this table
444
 * @return String representation of the execution plan
445
 */
446
public String explain();
447

448
/**
449
 * Explains the execution plan with specified format and details
450
 * @param format Format for the explanation output
451
 * @param extraDetails Additional details to include
452
 * @return String representation of the execution plan
453
 */
454
public String explain(ExplainFormat format, ExplainDetail... extraDetails);
455
```
456

457
**Usage Examples:**
458

459
```java
460
// Execute and print results
461
Table result = sourceTable
462
    .filter($("age").isGreater(25))
463
    .select($("name"), $("age"), $("department"));
464

465
TableResult tableResult = result.execute();
466
tableResult.print();
467

468
// Insert into target table
469
sourceTable
470
    .filter($("status").isEqual("ACTIVE"))
471
    .executeInsert("target_table");
472

473
// Explain query plan
474
String plan = result.explain();
475
System.out.println(plan);
476

477
// Detailed explanation
478
String detailedPlan = result.explain(
479
    ExplainFormat.JSON,
480
    ExplainDetail.COST_ATTRS,
481
    ExplainDetail.CHANGELOG_MODE
482
);
483
```
484

485
### Schema and Metadata
486

487
Access table schema and metadata information.
488

489
```java { .api }
490
/**
491
 * Gets the resolved schema of this table
492
 * @return ResolvedSchema containing column information and constraints
493
 */
494
public ResolvedSchema getResolvedSchema();
495

496
/**
497
 * Gets the legacy table schema (deprecated)
498
 * @return TableSchema with column types and names
499
 * @deprecated Use getResolvedSchema() instead
500
 */
501
@Deprecated
502
public TableSchema getSchema();
503

504
/**
505
 * Prints the schema of this table to the console
506
 */
507
public void printSchema();
508
```
509

510
## Table Result Operations
511

512
```java { .api }
513
public interface TableResult {
514
    /**
515
     * Prints the table results to the console
516
     */
517
    void print();
518
    
519
    /**
520
     * Collects table results as an iterator
521
     * @return CloseableIterator over result rows
522
     */
523
    CloseableIterator<Row> collect();
524
    
525
    /**
526
     * Gets the result kind (success, success with info, etc.)
527
     * @return ResultKind enum value
528
     */
529
    ResultKind getResultKind();
530
    
531
    /**
532
     * Gets the schema of the result table
533
     * @return ResolvedSchema of the result
534
     */
535
    ResolvedSchema getResolvedSchema();
536
    
537
    /**
538
     * Gets the job client for monitoring execution (if available)
539
     * @return Optional JobClient for job monitoring
540
     */
541
    Optional<JobClient> getJobClient();
542
}
543

544
public enum ResultKind {
545
    /** Operation completed successfully */
546
    SUCCESS,
547
    /** Operation completed successfully with additional information */
548
    SUCCESS_WITH_INFO
549
}
550
```
551

552
## Execution Interfaces
553

554
```java { .api }
555
public interface Executable {
556
    /**
557
     * Executes the operation and returns results
558
     * @return TableResult with execution results
559
     */
560
    TableResult execute();
561
}
562

563
public interface Explainable<T> {
564
    /**
565
     * Explains the execution plan for this operation
566
     * @return String representation of the execution plan
567
     */
568
    String explain();
569
    
570
    /**
571
     * Explains with specific format and details
572
     * @param format Output format for explanation
573
     * @param extraDetails Additional details to include
574
     * @return Formatted explanation string
575
     */
576
    String explain(ExplainFormat format, ExplainDetail... extraDetails);
577
}
578

579
public enum ExplainFormat {
580
    /** Plain text format */
581
    TEXT,
582
    /** JSON format */
583
    JSON
584
}
585

586
public enum ExplainDetail {
587
    /** Include cost attributes */
588
    COST_ATTRS,
589
    /** Include changelog mode information */
590
    CHANGELOG_MODE,
591
    /** Include estimated row count */
592
    ESTIMATED_COST
593
}
594
```