0
# Apache Flink Table API Java
1

2
Apache Flink Table API Java provides a unified table-centric programming interface for both batch and streaming data processing. It offers a comprehensive ecosystem for creating, manipulating, and querying tables with type-safe Java APIs, SQL support, and seamless integration with Flink's distributed processing engine.
3

4
## Package Information
5

6
- **Package Name**: flink-table-api-java
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.apache.flink</groupId>
13
    <artifactId>flink-table-api-java</artifactId>
14
    <version>2.1.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.apache.flink.table.api.*;
22
import org.apache.flink.table.expressions.Expression;
23
import static org.apache.flink.table.api.Expressions.*;
24
```
25

26
For catalog operations:
27
```java
28
import org.apache.flink.table.catalog.*;
29
```
30

31
For user-defined functions:
32
```java
33
import org.apache.flink.table.functions.*;
34
```
35

36
## Basic Usage
37

38
```java
39
import org.apache.flink.table.api.*;
40
import static org.apache.flink.table.api.Expressions.*;
41

42
// Create table environment
43
EnvironmentSettings settings = EnvironmentSettings
44
    .newInstance()
45
    .inStreamingMode()
46
    .build();
47
TableEnvironment tableEnv = TableEnvironment.create(settings);
48

49
// Create table from source
50
Table sourceTable = tableEnv.from("input_table");
51

52
// Perform transformations
53
Table result = sourceTable
54
    .select($("name"), $("age"), $("salary"))
55
    .filter($("age").isGreater(25))
56
    .groupBy($("name"))
57
    .select($("name"), $("age").max(), $("salary").avg());
58

59
// Execute and collect results
60
TableResult tableResult = result.execute();
61
tableResult.print();
62

63
// SQL alternative
64
Table sqlResult = tableEnv.sqlQuery(
65
    "SELECT name, MAX(age), AVG(salary) " +
66
    "FROM input_table " +
67
    "WHERE age > 25 " +
68
    "GROUP BY name"
69
);
70
```
71

72
## Architecture
73

74
The Flink Table API is built around several key components:
75

76
- **TableEnvironment**: Central entry point for all table operations, catalog management, and SQL execution
77
- **Table**: Core abstraction representing data transformation pipelines with lazy evaluation
78
- **Expression System**: Type-safe column references and function calls for table operations
79
- **Catalog System**: Metadata management for tables, functions, and data sources
80
- **SQL Integration**: Full SQL support with query parsing and execution
81
- **Window Operations**: Time-based and count-based windowing for streaming aggregations
82
- **User-Defined Functions**: Extensible function system for custom logic
83

84
## Capabilities
85

86
### Table Environment and Setup
87

88
Core functionality for creating and configuring table environments, managing catalogs, and establishing execution contexts.
89

90
```java { .api }
91
public interface TableEnvironment {
92
    static TableEnvironment create(EnvironmentSettings settings);
93
    
94
    Table from(String path);
95
    TableResult executeSql(String statement);
96
    Table sqlQuery(String query);
97
    
98
    void createTable(String path, TableDescriptor descriptor);
99
    void createTemporaryView(String path, Table view);
100
}
101

102
public class EnvironmentSettings {
103
    public static Builder newInstance();
104
    
105
    public static class Builder {
106
        public Builder inStreamingMode();
107
        public Builder inBatchMode();
108
        public EnvironmentSettings build();
109
    }
110
}
111
```
112

113
[Table Environment and Setup](./table-environment.md)
114

115
### Table Operations and Transformations
116

117
Core table transformation operations including selection, filtering, joining, and data manipulation with type-safe expression handling.
118

119
```java { .api }
120
public interface Table extends Explainable<Table>, Executable {
121
    Table select(Expression... fields);
122
    Table filter(Expression predicate);
123
    Table join(Table right, Expression joinPredicate);
124
    Table leftOuterJoin(Table right, Expression joinPredicate);
125
    
126
    GroupedTable groupBy(Expression... fields);
127
    Table orderBy(Expression... fields);
128
    Table limit(int fetch);
129
    
130
    TableResult execute();
131
    TableResult executeInsert(String tablePath);
132
}
133
```
134

135
[Table Operations and Transformations](./table-operations.md)
136

137
### Expressions and Column References
138

139
Type-safe expression system for building column references, function calls, and complex predicates in table operations.
140

141
```java { .api }
142
public final class Expressions {
143
    public static Expression $(String name);
144
    public static Expression lit(Object value);
145
    public static Expression call(String name, Object... args);
146
    
147
    // Comparison operators
148
    public static Expression isEqual(Expression left, Expression right);
149
    public static Expression isGreater(Expression left, Expression right);
150
    public static Expression isLess(Expression left, Expression right);
151
    
152
    // Logical operators  
153
    public static Expression and(Expression left, Expression right);
154
    public static Expression or(Expression left, Expression right);
155
    public static Expression not(Expression expression);
156
}
157

158
public interface Expression {
159
    Expression as(String alias);
160
    Expression isEqual(Object other);
161
    Expression isGreater(Object other);
162
    Expression plus(Object other);
163
    Expression minus(Object other);
164
}
165
```
166

167
[Expressions and Column References](./expressions.md)
168

169
### Aggregation and Grouping
170

171
Aggregation operations with support for grouping, window functions, and advanced aggregation patterns for both batch and streaming scenarios.
172

173
```java { .api }
174
public interface GroupedTable {
175
    Table select(Expression... fields);
176
    AggregatedTable aggregate(Expression aggregateFunction);
177
    FlatAggregateTable flatAggregate(Expression tableAggregateFunction);
178
}
179

180
public interface AggregatedTable {
181
    Table select(Expression... fields);
182
}
183

184
public interface FlatAggregateTable {
185
    Table select(Expression... fields);
186
}
187
```
188

189
[Aggregation and Grouping](./aggregation-grouping.md)
190

191
### Window Operations
192

193
Time-based and count-based windowing operations for streaming data processing, including tumbling, sliding, and session windows.
194

195
```java { .api }
196
public abstract class GroupWindow {
197
    public abstract GroupWindow as(String alias);
198
}
199

200
public final class Tumble {
201
    public static TumbleWithSize over(Expression size);
202
}
203

204
public final class Slide {
205
    public static SlideWithSize over(Expression size);
206
}
207

208
public final class Session {
209
    public static SessionWithGap withGap(Expression gap);
210
}
211

212
public interface WindowGroupedTable {
213
    Table select(Expression... fields);
214
}
215
```
216

217
[Window Operations](./window-operations.md)
218

219
### Catalog and Metadata Management
220

221
Catalog system for managing table metadata, data sources, functions, and multi-catalog environments with persistent storage.
222

223
```java { .api }
224
public class CatalogManager {
225
    public void registerCatalog(String catalogName, Catalog catalog);
226
    public Optional<Catalog> getCatalog(String catalogName);
227
    public void setCurrentCatalog(String catalogName);
228
    public void setCurrentDatabase(String databaseName);
229
}
230

231
public interface Catalog {
232
    void createDatabase(String name, CatalogDatabase database, boolean ignoreIfExists);
233
    void createTable(ObjectPath tablePath, CatalogTable table, boolean ignoreIfExists);
234
    CatalogTable getTable(ObjectPath tablePath);
235
}
236
```
237

238
[Catalog and Metadata Management](./catalog-management.md)
239

240
### User-Defined Functions
241

242
Framework for creating and registering custom scalar, table, and aggregate functions to extend the built-in function library.
243

244
```java { .api }
245
public abstract class ScalarFunction extends UserDefinedFunction {
246
    // User implements eval() methods with various signatures
247
}
248

249
public abstract class TableFunction<T> extends UserDefinedFunction {
250
    public void eval(Object... args);
251
    protected void collect(T result);
252
}
253

254
public abstract class AggregateFunction<T, ACC> extends UserDefinedFunction {
255
    public ACC createAccumulator();
256
    public void accumulate(ACC accumulator, Object... args);
257
    public T getValue(ACC accumulator);
258
}
259
```
260

261
[User-Defined Functions](./user-defined-functions.md)
262

263
### SQL Integration
264

265
Native SQL support with query parsing, execution planning, and seamless integration between Table API and SQL operations.
266

267
```java { .api }
268
public interface TableEnvironment {
269
    Table sqlQuery(String query);
270
    TableResult executeSql(String statement);
271
    void executeSql(String statement);
272
    
273
    StatementSet createStatementSet();
274
}
275

276
public interface StatementSet {
277
    StatementSet addInsertSql(String statement);
278
    TableResult execute();
279
}
280
```
281

282
[SQL Integration](./sql-integration.md)
283

284
## Types
285

286
### Core Types
287

288
```java { .api }
289
public interface TableResult {
290
    void print();
291
    CloseableIterator<Row> collect();
292
    ResultKind getResultKind();
293
    TableSchema getTableSchema();
294
}
295

296
public enum ResultKind {
297
    SUCCESS,
298
    SUCCESS_WITH_INFO
299
}
300

301
public final class TableConfig implements WritableConfig, ReadableConfig {
302
    public Configuration getConfiguration();
303
    public void setSqlDialect(SqlDialect dialect);
304
}
305

306
public enum SqlDialect {
307
    DEFAULT,
308
    HIVE
309
}
310

311
public class TableDescriptor {
312
    public static Builder forConnector(String connector);
313
    
314
    public static class Builder {
315
        public Builder schema(Schema schema);
316
        public Builder option(String key, String value);
317
        public TableDescriptor build();
318
    }
319
}
320
```
321

322
### Exception Types
323

324
```java { .api }
325
public class SqlParserException extends RuntimeException {
326
    public SqlParserException(String message);
327
    public SqlParserException(String message, Throwable cause);
328
}
329

330
public class SqlParserEOFException extends SqlParserException {
331
    public SqlParserEOFException(String message);
332
}
333
```