0
# Table API & SQL
1

2
Declarative programming model for relational data processing with SQL support, catalog integration, and comprehensive type system for structured data operations. The Table API provides both programmatic and SQL interfaces for data processing.
3

4
## Capabilities
5

6
### Table Environment
7

8
Main entry point for Table API programs.
9

10
```java { .api }
11
/**
12
 * Main interface for Table API programs
13
 */
14
interface TableEnvironment {
15
    /**
16
     * Create table environment
17
     * @return Table environment instance
18
     */
19
    static TableEnvironment create();
20
    
21
    /**
22
     * Execute SQL query
23
     * @param query SQL query string
24
     * @return Table result
25
     */
26
    Table sqlQuery(String query);
27
    
28
    /**
29
     * Execute SQL statement
30
     * @param statement SQL statement
31
     * @return Table result
32
     */
33
    TableResult executeSql(String statement);
34
    
35
    /**
36
     * Get table from identifier
37
     * @param path Table path
38
     * @return Table
39
     */
40
    Table from(String path);
41
    
42
    /**
43
     * Create temporary view from table
44
     * @param path View path
45
     * @param table Table to create view from
46
     */
47
    void createTemporaryView(String path, Table table);
48
    
49
    /**
50
     * Register table
51
     * @param name Table name
52
     * @param table Table to register
53
     */
54
    void registerTable(String name, Table table);
55
    
56
    /**
57
     * Register function
58
     * @param name Function name
59
     * @param function User-defined function
60
     */
61
    void registerFunction(String name, UserDefinedFunction function);
62
}
63

64
/**
65
 * Stream table environment bridging Table and DataStream APIs
66
 */
67
interface StreamTableEnvironment extends TableEnvironment {
68
    /**
69
     * Create stream table environment from stream execution environment
70
     * @param executionEnvironment Stream execution environment
71
     * @return Stream table environment
72
     */
73
    static StreamTableEnvironment create(StreamExecutionEnvironment executionEnvironment);
74
    
75
    /**
76
     * Create stream table environment with settings
77
     * @param executionEnvironment Stream execution environment
78
     * @param settings Environment settings
79
     * @return Stream table environment
80
     */
81
    static StreamTableEnvironment create(
82
        StreamExecutionEnvironment executionEnvironment,
83
        EnvironmentSettings settings);
84
    
85
    /**
86
     * Convert table to append data stream
87
     * @param table Table to convert
88
     * @param clazz Target type class
89
     * @param <T> Target type
90
     * @return Data stream in append mode
91
     */
92
    <T> DataStream<T> toAppendStream(Table table, Class<T> clazz);
93
    
94
    /**
95
     * Convert table to retract data stream
96
     * @param table Table to convert
97
     * @param clazz Target type class
98
     * @param <T> Target type
99
     * @return Data stream with retract records
100
     */
101
    <T> DataStream<Tuple2<Boolean, T>> toRetractStream(Table table, Class<T> clazz);
102
    
103
    /**
104
     * Create table from data stream
105
     * @param dataStream Data stream
106
     * @param fields Field expressions
107
     * @param <T> Stream element type
108
     * @return Table
109
     */
110
    <T> Table fromDataStream(DataStream<T> dataStream, Expression... fields);
111
    
112
    /**
113
     * Register data stream as table
114
     * @param name Table name
115
     * @param dataStream Data stream
116
     * @param fields Field expressions
117
     * @param <T> Stream element type
118
     */
119
    <T> void registerDataStream(String name, DataStream<T> dataStream, Expression... fields);
120
}
121

122
/**
123
 * Environment settings for configuring table environments
124
 */
125
class EnvironmentSettings {
126
    /**
127
     * Create new builder for environment settings
128
     * @return Settings builder
129
     */
130
    public static Builder newInstance();
131
    
132
    /**
133
     * Create settings for streaming mode
134
     * @return Environment settings for streaming
135
     */
136
    public static EnvironmentSettings inStreamingMode();
137
    
138
    /**
139
     * Create settings for batch mode
140
     * @return Environment settings for batch
141
     */
142
    public static EnvironmentSettings inBatchMode();
143
    
144
    /**
145
     * Builder for environment settings
146
     */
147
    public static class Builder {
148
        /**
149
         * Use streaming planner
150
         * @return Builder
151
         */
152
        public Builder useStreamingPlanner();
153
        
154
        /**
155
         * Use batch planner
156
         * @return Builder
157
         */
158
        public Builder useBatchPlanner();
159
        
160
        /**
161
         * Use blink planner
162
         * @return Builder
163
         */
164
        public Builder useBlinkPlanner();
165
        
166
        /**
167
         * Use old planner
168
         * @return Builder
169
         */
170
        public Builder useOldPlanner();
171
        
172
        /**
173
         * Build environment settings
174
         * @return Environment settings
175
         */
176
        public EnvironmentSettings build();
177
    }
178
}
179
```
180

181
### Table Operations
182

183
Core table transformation and query operations.
184

185
```java { .api }
186
/**
187
 * Table interface for relational operations
188
 */
189
interface Table {
190
    /**
191
     * Select columns
192
     * @param fields Column expressions
193
     * @return Table with selected columns
194
     */
195
    Table select(Expression... fields);
196
    
197
    /**
198
     * Filter rows
199
     * @param predicate Filter predicate
200
     * @return Filtered table
201
     */
202
    Table where(Expression predicate);
203
    
204
    /**
205
     * Group by columns
206
     * @param fields Grouping columns
207
     * @return Grouped table
208
     */
209
    GroupedTable groupBy(Expression... fields);
210
    
211
    /**
212
     * Order by columns
213
     * @param fields Ordering expressions
214
     * @return Ordered table
215
     */
216
    Table orderBy(Expression... fields);
217
    
218
    /**
219
     * Limit number of rows
220
     * @param fetch Number of rows to fetch
221
     * @return Limited table
222
     */
223
    Table limit(int fetch);
224
    
225
    /**
226
     * Limit with offset
227
     * @param offset Number of rows to skip
228
     * @param fetch Number of rows to fetch
229
     * @return Limited table
230
     */
231
    Table limit(int offset, int fetch);
232
    
233
    /**
234
     * Join with another table
235
     * @param right Right table
236
     * @param joinPredicate Join condition
237
     * @return Joined table
238
     */
239
    Table join(Table right, Expression joinPredicate);
240
    
241
    /**
242
     * Left outer join
243
     * @param right Right table
244
     * @param joinPredicate Join condition
245
     * @return Joined table
246
     */
247
    Table leftOuterJoin(Table right, Expression joinPredicate);
248
    
249
    /**
250
     * Execute table and return result
251
     * @return Table result
252
     */
253
    TableResult execute();
254
    
255
    /**
256
     * Get table schema
257
     * @return Table schema
258
     */
259
    TableSchema getSchema();
260
}
261
```
262

263
### Grouped Table Operations
264

265
Operations available on grouped tables.
266

267
```java { .api }
268
/**
269
 * Grouped table operations
270
 */
271
interface GroupedTable {
272
    /**
273
     * Select with aggregations
274
     * @param fields Selection expressions with aggregations
275
     * @return Aggregated table
276
     */
277
    Table select(Expression... fields);
278
    
279
    /**
280
     * Aggregate using aggregate function
281
     * @param aggregateFunction Aggregate function
282
     * @return Aggregated table
283
     */
284
    AggregatedTable aggregate(Expression aggregateFunction);
285
}
286

287
/**
288
 * Aggregated table operations
289
 */
290
interface AggregatedTable {
291
    /**
292
     * Select from aggregated results
293
     * @param fields Selection expressions
294
     * @return Selected table
295
     */
296
    Table select(Expression... fields);
297
}
298
```
299

300
### User-Defined Functions
301

302
Base classes for creating custom functions.
303

304
```java { .api }
305
/**
306
 * Base class for user-defined functions
307
 */
308
abstract class UserDefinedFunction {
309
    /**
310
     * Get function kind
311
     * @return Function kind
312
     */
313
    public abstract FunctionKind getKind();
314
    
315
    /**
316
     * Get type inference
317
     * @return Type inference
318
     */
319
    public TypeInference getTypeInference(DataTypeFactory typeFactory);
320
}
321

322
/**
323
 * Scalar function base class
324
 */
325
abstract class ScalarFunction extends UserDefinedFunction {
326
    /**
327
     * Evaluation method - implement with desired signature
328
     * @param params Function parameters
329
     * @return Function result
330
     */
331
    public Object eval(Object... params);
332
    
333
    @Override
334
    public FunctionKind getKind() {
335
        return FunctionKind.SCALAR;
336
    }
337
}
338

339
/**
340
 * Table function base class
341
 * @param <T> Output row type
342
 */
343
abstract class TableFunction<T> extends UserDefinedFunction {
344
    /**
345
     * Emit row to collector
346
     * @param row Row to emit
347
     */
348
    protected void collect(T row);
349
    
350
    /**
351
     * Evaluation method - implement with desired signature
352
     * @param params Function parameters
353
     */
354
    public void eval(Object... params);
355
    
356
    @Override
357
    public FunctionKind getKind() {
358
        return FunctionKind.TABLE;
359
    }
360
}
361

362
/**
363
 * Aggregate function base class
364
 * @param <T> Result type
365
 * @param <ACC> Accumulator type
366
 */
367
abstract class AggregateFunction<T, ACC> extends UserDefinedFunction {
368
    /**
369
     * Create accumulator
370
     * @return New accumulator
371
     */
372
    public abstract ACC createAccumulator();
373
    
374
    /**
375
     * Get result from accumulator
376
     * @param accumulator Accumulator
377
     * @return Result
378
     */
379
    public abstract T getValue(ACC accumulator);
380
    
381
    /**
382
     * Accumulate value
383
     * @param accumulator Accumulator
384
     * @param params Input values
385
     */
386
    public abstract void accumulate(ACC accumulator, Object... params);
387
    
388
    @Override
389
    public FunctionKind getKind() {
390
        return FunctionKind.AGGREGATE;
391
    }
392
}
393
```
394

395
### Expressions
396

397
Expression system for table operations.
398

399
```java { .api }
400
/**
401
 * Base interface for table expressions
402
 */
403
interface Expression {
404
    /**
405
     * Get expression SQL representation
406
     * @return SQL string
407
     */
408
    String asSummaryString();
409
}
410

411
/**
412
 * Factory methods for table expressions
413
 */
414
class Expressions {
415
    /**
416
     * Create column reference
417
     * @param name Column name
418
     * @return Column expression
419
     */
420
    public static Expression $(String name);
421
    
422
    /**
423
     * Create literal value
424
     * @param value Literal value
425
     * @return Literal expression
426
     */
427
    public static Expression lit(Object value);
428
    
429
    /**
430
     * Create range expression
431
     * @param from Start column
432
     * @param to End column
433
     * @return Range expression
434
     */
435
    public static Expression range(String from, String to);
436
    
437
    /**
438
     * Create all columns expression
439
     * @return All columns expression
440
     */
441
    public static Expression $star();
442
    
443
    // Arithmetic operations
444
    public static Expression plus(Expression left, Expression right);
445
    public static Expression minus(Expression left, Expression right);
446
    public static Expression times(Expression left, Expression right);
447
    public static Expression div(Expression left, Expression right);
448
    
449
    // Comparison operations
450
    public static Expression isEqual(Expression left, Expression right);
451
    public static Expression isNotEqual(Expression left, Expression right);
452
    public static Expression isLess(Expression left, Expression right);
453
    public static Expression isGreater(Expression left, Expression right);
454
    
455
    // Logical operations
456
    public static Expression and(Expression left, Expression right);
457
    public static Expression or(Expression left, Expression right);
458
    public static Expression not(Expression expression);
459
    
460
    // String operations
461
    public static Expression like(Expression str, Expression pattern);
462
    public static Expression upper(Expression str);
463
    public static Expression lower(Expression str);
464
    
465
    // Aggregate functions
466
    public static Expression count(Expression expression);
467
    public static Expression sum(Expression expression);
468
    public static Expression avg(Expression expression);
469
    public static Expression max(Expression expression);
470
    public static Expression min(Expression expression);
471
}
472
```
473

474
### Table Result
475

476
Result of table operations and queries.
477

478
```java { .api }
479
/**
480
 * Result of table operations and queries
481
 */
482
interface TableResult {
483
    /**
484
     * Get result schema
485
     * @return Table schema
486
     */
487
    TableSchema getTableSchema();
488
    
489
    /**
490
     * Print result to console
491
     */
492
    void print();
493
    
494
    /**
495
     * Get job client for result
496
     * @return Optional job client
497
     */
498
    Optional<JobClient> getJobClient();
499
    
500
    /**
501
     * Collect results
502
     * @return Iterator over rows
503
     */
504
    CloseableIterator<Row> collect();
505
    
506
    /**
507
     * Get result kind
508
     * @return Result kind
509
     */
510
    ResultKind getResultKind();
511
}
512

513
/**
514
 * Result kind enumeration
515
 */
516
enum ResultKind {
517
    SUCCESS,
518
    SUCCESS_WITH_CONTENT
519
}
520
```
521

522
### Data Types
523

524
Type system for table operations.
525

526
```java { .api }
527
/**
528
 * Logical data type representation
529
 */
530
abstract class DataType {
531
    /**
532
     * Get logical type
533
     * @return Logical type
534
     */
535
    public abstract LogicalType getLogicalType();
536
    
537
    /**
538
     * Get conversion class
539
     * @return Conversion class
540
     */
541
    public abstract Class<?> getConversionClass();
542
    
543
    /**
544
     * Create nullable version
545
     * @return Nullable data type
546
     */
547
    public abstract DataType nullable();
548
    
549
    /**
550
     * Create non-nullable version
551
     * @return Non-nullable data type
552
     */
553
    public abstract DataType notNull();
554
}
555

556
/**
557
 * Logical type system
558
 */
559
abstract class LogicalType {
560
    /**
561
     * Check if type is nullable
562
     * @return true if nullable
563
     */
564
    public abstract boolean isNullable();
565
    
566
    /**
567
     * Get type root
568
     * @return Type root
569
     */
570
    public abstract LogicalTypeRoot getTypeRoot();
571
    
572
    /**
573
     * Copy type
574
     * @param isNullable Nullable setting
575
     * @return Copied type
576
     */
577
    public abstract LogicalType copy(boolean isNullable);
578
}
579

580
/**
581
 * Row type for structured data
582
 */
583
class RowType extends LogicalType {
584
    /**
585
     * Get field names
586
     * @return List of field names
587
     */
588
    public List<String> getFieldNames();
589
    
590
    /**
591
     * Get field types
592
     * @return List of field types
593
     */
594
    public List<LogicalType> getFieldTypes();
595
    
596
    /**
597
     * Get field by name
598
     * @param fieldName Field name
599
     * @return Optional field
600
     */
601
    public Optional<RowType.RowField> getField(String fieldName);
602
}
603
```