0
# Apache Flink Table Calcite Bridge
1

2
Bridge module containing Calcite dependencies for writing planner plugins (e.g., SQL dialects) that interact with Calcite APIs. This module provides the ability to create RelNode instances by accessing RelOptCluster, RelBuilder, and other Calcite components provided by Flink's planner context, enabling custom SQL dialect development and advanced query planning extensions.
3

4
## Package Information
5

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

18
## Core Imports
19

20
```java
21
import org.apache.flink.table.calcite.bridge.CalciteContext;
22
import org.apache.flink.table.calcite.bridge.PlannerExternalQueryOperation;
23
```
24

25
## Basic Usage
26

27
```java
28
import org.apache.flink.table.calcite.bridge.CalciteContext;
29
import org.apache.flink.table.calcite.bridge.PlannerExternalQueryOperation;
30
import org.apache.calcite.rel.RelNode;
31
import org.apache.calcite.tools.RelBuilder;
32
import org.apache.calcite.plan.RelOptCluster;
33
import org.apache.flink.table.catalog.ResolvedSchema;
34
import org.apache.flink.table.operations.QueryOperationVisitor;
35

36
// CalciteContext is provided by Flink's table planner implementation
37
CalciteContext context = // ... obtained from planner context
38

39
// Access core Calcite components
40
RelOptCluster cluster = context.getCluster();
41
RelBuilder relBuilder = context.createRelBuilder();
42

43
// Build a relational expression programmatically
44
RelNode relNode = relBuilder
45
    .scan("MyTable")
46
    .filter(relBuilder.call("=", relBuilder.field("status"), relBuilder.literal("active")))
47
    .project(relBuilder.field("id"), relBuilder.field("name"))
48
    .build();
49

50
// Create resolved schema matching the projection
51
ResolvedSchema schema = // ... define schema with id and name columns
52

53
// Wrap in PlannerExternalQueryOperation for Flink integration
54
PlannerExternalQueryOperation operation = 
55
    new PlannerExternalQueryOperation(relNode, schema);
56

57
// Use the operation in Flink's query operation framework
58
RelNode calciteTree = operation.getCalciteTree();
59
ResolvedSchema resolvedSchema = operation.getResolvedSchema();
60
String summary = operation.asSummaryString();
61

62
// Visit the operation using visitor pattern
63
QueryOperationVisitor<String> visitor = // ... implement visitor
64
String result = operation.accept(visitor);
65
```
66

67
## Architecture
68

69
The module provides two key components that bridge Flink's Table API with Calcite's planning infrastructure:
70

71
- **CalciteContext**: Interface providing access to Calcite's planning components (RelOptCluster, RelBuilder, type factory, catalog reader) through Flink's table planner
72
- **PlannerExternalQueryOperation**: Wrapper that encapsulates Calcite RelNode instances with Flink's resolved schemas, enabling seamless integration with Flink's query operation model
73

74
This design enables plugin developers to leverage Calcite's full relational algebra capabilities while maintaining compatibility with Flink's distributed processing runtime.
75

76
**Note**: Both CalciteContext and PlannerExternalQueryOperation are marked with `@Internal` annotations, indicating they are intended for internal Flink use and may change without notice between versions.
77

78
## Capabilities
79

80
### Calcite Context Access
81

82
Provides access to Calcite's core planning infrastructure through Flink's table planner, enabling creation of RelNode instances and access to optimization components.
83

84
```java { .api }
85
public interface CalciteContext extends ParserFactory.Context {
86
    CalciteCatalogReader createCatalogReader(boolean lenientCaseSensitivity);
87
    RelOptCluster getCluster();
88
    FrameworkConfig createFrameworkConfig();
89
    RelDataTypeFactory getTypeFactory();
90
    RelBuilder createRelBuilder();
91
    TableConfig getTableConfig();
92
    ClassLoader getClassLoader();
93
    FunctionCatalog getFunctionCatalog();
94
    RelOptTable.ToRelContext createToRelContext();
95
    CatalogRegistry getCatalogRegistry(); // Inherited from ParserFactory.Context
96
}
97
```
98

99
#### CalciteCatalogReader createCatalogReader(boolean lenientCaseSensitivity)
100

101
Creates a Calcite catalog reader for metadata access during planning.
102

103
- **Parameters**: 
104
  - `lenientCaseSensitivity` (boolean): Whether to use lenient case sensitivity for identifiers
105
- **Returns**: `CalciteCatalogReader` - Catalog reader instance for accessing table and function metadata
106

107
#### RelOptCluster getCluster()
108

109
Returns the optimization cluster containing the planner, cost model, and metadata repository.
110

111
- **Returns**: `RelOptCluster` - The optimization cluster used for planning
112

113
#### FrameworkConfig createFrameworkConfig()
114

115
Creates Calcite framework configuration with Flink-specific settings.
116

117
- **Returns**: `FrameworkConfig` - Configuration object for Calcite framework
118

119
#### RelDataTypeFactory getTypeFactory()
120

121
Returns Calcite's type factory for creating and managing data types.
122

123
- **Returns**: `RelDataTypeFactory` - Type factory for creating Calcite data types
124

125
#### RelBuilder createRelBuilder()
126

127
Creates a RelBuilder for programmatic construction of relational expressions.
128

129
- **Returns**: `RelBuilder` - Builder for creating RelNode instances programmatically
130

131
#### TableConfig getTableConfig()
132

133
Returns Flink's table configuration.
134

135
- **Returns**: `TableConfig` - Flink table environment configuration
136

137
#### ClassLoader getClassLoader()
138

139
Returns the class loader defined in the table environment.
140

141
- **Returns**: `ClassLoader` - Class loader for loading user-defined classes
142

143
#### FunctionCatalog getFunctionCatalog()
144

145
Returns Flink's function catalog for accessing built-in and user-defined functions.
146

147
- **Returns**: `FunctionCatalog` - Catalog containing available functions
148

149
#### RelOptTable.ToRelContext createToRelContext()
150

151
Create a new instance of RelOptTable.ToRelContext provided by Flink's table planner. The ToRelContext is used to convert a table into a relational expression.
152

153
- **Returns**: `RelOptTable.ToRelContext` - Context for converting tables to relational expressions
154

155
#### CatalogRegistry getCatalogRegistry()
156

157
Return the CatalogRegistry defined in TableEnvironment. This method is inherited from ParserFactory.Context.
158

159
- **Returns**: `CatalogRegistry` - Registry for managing catalog instances in the table environment
160

161
### Planner Query Operation Wrapper
162

163
Wrapper for Calcite RelNode instances with resolved schemas, enabling integration with Flink's query operation model.
164

165
```java { .api }
166
public class PlannerExternalQueryOperation implements QueryOperation {
167
    public PlannerExternalQueryOperation(RelNode relNode, ResolvedSchema resolvedSchema);
168
    public RelNode getCalciteTree();
169
    public ResolvedSchema getResolvedSchema();
170
    public List<QueryOperation> getChildren();
171
    public <T> T accept(QueryOperationVisitor<T> visitor);
172
    public String asSummaryString();
173
    public String asSerializableString(); // Inherited default method
174
    public String asSerializableString(SqlFactory sqlFactory); // Inherited default method
175
}
176
```
177

178
#### Constructor PlannerExternalQueryOperation(RelNode relNode, ResolvedSchema resolvedSchema)
179

180
Wrapper for valid logical plans and resolved schema generated by Planner. It's mainly used by pluggable dialect which will generate Calcite RelNode in planning phase.
181

182
- **Parameters**:
183
  - `relNode` (RelNode): The Calcite relational expression representing the logical plan
184
  - `resolvedSchema` (ResolvedSchema): The resolved schema describing the operation's output structure
185

186
#### RelNode getCalciteTree()
187

188
Returns the wrapped Calcite RelNode representing the logical plan.
189

190
- **Returns**: `RelNode` - The Calcite relational expression
191

192
#### ResolvedSchema getResolvedSchema()
193

194
Returns the resolved schema describing the operation's output structure.
195

196
- **Returns**: `ResolvedSchema` - Schema with column names and types
197

198
#### List<QueryOperation> getChildren()
199

200
Returns child query operations (always empty for this wrapper).
201

202
- **Returns**: `List<QueryOperation>` - Empty list as this is a leaf operation
203

204
#### <T> T accept(QueryOperationVisitor<T> visitor)
205

206
Accepts a visitor for traversing the query operation tree.
207

208
- **Parameters**:
209
  - `visitor` (QueryOperationVisitor<T>): Visitor to accept
210
- **Returns**: `T` - Result of visitor's visit method
211

212
#### String asSummaryString()
213

214
Returns a string representation for debugging and logging. Implementation uses OperationUtils.formatWithChildren with "PlannerCalciteQueryOperation".
215

216
- **Returns**: `String` - Summary string representation for debugging
217

218
#### String asSerializableString()
219

220
Returns a serializable string representation of the operation. This is a default method inherited from QueryOperation.
221

222
- **Returns**: `String` - Serializable string representation
223

224
#### String asSerializableString(SqlFactory sqlFactory)
225

226
Returns a serializable string representation of the operation using the provided SQL factory. This is a default method inherited from QueryOperation.
227

228
- **Parameters**:
229
  - `sqlFactory` (SqlFactory): Factory for SQL string generation
230
- **Returns**: `String` - Serializable string representation using the provided factory
231

232
## Types
233

234
### Key Calcite Types
235

236
```java { .api }
237
// Calcite core types used in the API
238
interface RelNode {
239
    // Represents a relational expression in Calcite
240
}
241

242
interface RelOptCluster {
243
    // Container for planning environment
244
}
245

246
interface RelDataTypeFactory {
247
    // Factory for creating Calcite data types
248
}
249

250
interface CalciteCatalogReader {
251
    // Reader for accessing catalog metadata
252
}
253

254
class RelBuilder {
255
    // Builder for programmatic RelNode construction
256
}
257

258
interface FrameworkConfig {
259
    // Configuration for Calcite framework
260
}
261
```
262

263
### Key Flink Types
264

265
```java { .api }
266
// Flink types used in the API
267
interface QueryOperation {
268
    // Base interface for query operations in Flink
269
}
270

271
class ResolvedSchema {
272
    // Schema with resolved column names and types
273
}
274

275
interface QueryOperationVisitor<T> {
276
    // Visitor pattern for traversing query operations
277
}
278

279
class TableConfig {
280
    // Configuration for Flink table environment
281
}
282

283
class FunctionCatalog {
284
    // Catalog of available functions in Flink
285
}
286

287
interface ParserFactory.Context {
288
    // Context interface for parser factory
289
}
290

291
class CatalogRegistry {
292
    // Registry for managing catalog instances
293
}
294

295
interface SqlFactory {
296
    // Factory for SQL string generation
297
}
298
```