0
# Flink SQL Client
1

2
Flink SQL Client provides an interactive command-line interface for exploring, analyzing, and executing SQL statements against Apache Flink streaming and batch data processing jobs. This library enables developers to submit SQL queries through embedded execution mode, offering comprehensive table ecosystem integration with Flink's streaming-first runtime that supports both batch processing and data streaming programs.
3

4
## Package Information
5

6
- **Package Name**: flink-sql-client_2.12
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `mvn dependency` with `org.apache.flink:flink-sql-client_2.12:1.14.6`
10

11
## Core Imports
12

13
```java
14
import org.apache.flink.table.client.SqlClient;
15
import org.apache.flink.table.client.cli.CliClient;
16
import org.apache.flink.table.client.cli.CliOptions;
17
import org.apache.flink.table.client.gateway.Executor;
18
import org.apache.flink.table.client.gateway.local.LocalExecutor;
19
import org.apache.flink.configuration.Configuration;
20
import org.apache.flink.configuration.ReadableConfig;
21
import org.apache.flink.table.operations.ModifyOperation;
22
import org.apache.flink.types.Row;
23
```
24

25
## Basic Usage
26

27
```java
28
import org.apache.flink.table.client.SqlClient;
29
import org.apache.flink.table.client.cli.CliOptions;
30
import org.apache.flink.table.client.cli.CliOptionsParser;
31

32
// Start SQL Client from command line
33
public class Example {
34
    public static void main(String[] args) {
35
        // Parse command line options
36
        CliOptions options = CliOptionsParser.parseEmbeddedModeClient(args);
37
        
38
        // Start SQL Client in embedded mode
39
        SqlClient.main(new String[]{"embedded", "--jar", "path/to/flink-sql-client.jar"});
40
    }
41
}
42

43
// Programmatic usage
44
import org.apache.flink.table.client.gateway.local.LocalExecutor;
45
import org.apache.flink.table.client.gateway.context.DefaultContext;
46
import org.apache.flink.table.client.gateway.local.LocalContextUtils;
47
import org.apache.flink.table.operations.Operation;
48
import org.apache.flink.table.operations.QueryOperation;
49
import org.apache.flink.table.api.TableResult;
50
import org.apache.flink.table.client.gateway.ResultDescriptor;
51

52
// Create executor and session
53
DefaultContext context = LocalContextUtils.buildDefaultContext(options);
54
Executor executor = new LocalExecutor(context);
55
executor.start();
56

57
// Open session and execute SQL
58
String sessionId = executor.openSession(null);
59
try {
60
    // Parse and execute SQL statements
61
    Operation operation = executor.parseStatement(sessionId, "CREATE TABLE MyTable (id INT, name STRING)");
62
    TableResult result = executor.executeOperation(sessionId, operation);
63
    
64
    // Execute queries with result retrieval
65
    QueryOperation query = (QueryOperation) executor.parseStatement(sessionId, "SELECT * FROM MyTable");
66
    ResultDescriptor resultDesc = executor.executeQuery(sessionId, query);
67
} finally {
68
    executor.closeSession(sessionId);
69
}
70
```
71

72
## Architecture
73

74
Flink SQL Client is built around several key components:
75

76
- **SqlClient**: Main application entry point supporting embedded and gateway modes
77
- **Executor Interface**: Abstraction for SQL execution backends with session management
78
- **CLI Client**: Interactive and non-interactive command-line interface with terminal support
79
- **Context System**: Configuration and dependency management for execution environments
80
- **Result Handling**: Type-safe result containers with materialized and streaming result support
81
- **Session Management**: Isolated execution contexts with property management and JAR loading
82

83
## Capabilities
84

85
### SQL Client Application
86

87
Main application entry point providing embedded execution mode for SQL operations against Flink clusters.
88

89
```java { .api }
90
public class SqlClient {
91
    public static void main(String[] args);
92
    
93
    public static void startClient(String[] args, Supplier<Terminal> terminalFactory);
94
    
95
    public static final String MODE_EMBEDDED = "embedded";
96
    public static final String MODE_GATEWAY = "gateway";
97
}
98
```
99

100
[SQL Client Application](./sql-client-application.md)
101

102
### Command Line Interface
103

104
Interactive and non-interactive CLI for executing SQL statements with terminal support and result display.
105

106
```java { .api }
107
public class CliClient implements AutoCloseable {
108
    public void executeInInteractiveMode();
109
    public void executeInNonInteractiveMode(String content);
110
    public boolean executeInitialization(String content);
111
    public Terminal getTerminal();
112
    public String getSessionId();
113
    public Executor getExecutor();
114
}
115

116
public class CliOptions {
117
    public boolean isPrintHelp();
118
    public String getSessionId();
119
    public URL getInitFile();
120
    public URL getSqlFile();
121
    public List<URL> getJars();
122
    public List<URL> getLibraryDirs();
123
    public String getUpdateStatement();
124
    public String getHistoryFilePath();
125
    public Configuration getPythonConfiguration();
126
}
127
```
128

129
[Command Line Interface](./command-line-interface.md)
130

131
### SQL Execution Gateway
132

133
Core execution interface providing session management, SQL parsing, and operation execution.
134

135
```java { .api }
136
public interface Executor {
137
    void start() throws SqlExecutionException;
138
    String openSession(String sessionId) throws SqlExecutionException;
139
    void closeSession(String sessionId) throws SqlExecutionException;
140
    
141
    Map<String, String> getSessionConfigMap(String sessionId) throws SqlExecutionException;
142
    ReadableConfig getSessionConfig(String sessionId) throws SqlExecutionException;
143
    void resetSessionProperties(String sessionId) throws SqlExecutionException;
144
    void resetSessionProperty(String sessionId, String key) throws SqlExecutionException;
145
    void setSessionProperty(String sessionId, String key, String value) throws SqlExecutionException;
146
    
147
    Operation parseStatement(String sessionId, String statement) throws SqlExecutionException;
148
    List<String> completeStatement(String sessionId, String statement, int position);
149
    TableResult executeOperation(String sessionId, Operation operation) throws SqlExecutionException;
150
    TableResult executeModifyOperations(String sessionId, List<ModifyOperation> operations) throws SqlExecutionException;
151
    ResultDescriptor executeQuery(String sessionId, QueryOperation query) throws SqlExecutionException;
152
    
153
    TypedResult<List<Row>> retrieveResultChanges(String sessionId, String resultId) throws SqlExecutionException;
154
    TypedResult<Integer> snapshotResult(String sessionId, String resultId, int pageSize) throws SqlExecutionException;
155
    List<Row> retrieveResultPage(String resultId, int page) throws SqlExecutionException;
156
    void cancelQuery(String sessionId, String resultId) throws SqlExecutionException;
157
    
158
    void addJar(String sessionId, String jarPath);
159
    void removeJar(String sessionId, String jarPath);
160
    List<String> listJars(String sessionId);
161
}
162

163
public class LocalExecutor implements Executor {
164
    public LocalExecutor(DefaultContext defaultContext);
165
}
166
```
167

168
[SQL Execution Gateway](./sql-execution-gateway.md)
169

170
### Session and Context Management
171

172
Configuration and context management for execution environments with property handling and dependency management.
173

174
```java { .api }
175
public class DefaultContext {
176
    public Configuration getFlinkConfig();
177
    public List<URL> getDependencies();
178
}
179

180
public class SessionContext {
181
    public String getSessionId();
182
    public Map<String, String> getConfigMap();
183
    public ReadableConfig getReadableConfig();
184
    public void set(String key, String value);
185
    public void reset();
186
    public void reset(String key);
187
    public void addJar(String jarUrl);
188
    public void removeJar(String jarUrl);
189
    public List<String> listJars();
190
    public void close();
191
}
192
```
193

194
[Session and Context Management](./session-context-management.md)
195

196
### Result Handling and Display
197

198
Type-safe result containers with support for materialized and streaming results, plus multiple display formats.
199

200
```java { .api }
201
public class ResultDescriptor {
202
    public String getResultId();
203
    public ResolvedSchema getResultSchema();
204
    public boolean isMaterialized();
205
    public boolean isTableauMode();
206
    public boolean isStreamingMode();
207
}
208

209
public class TypedResult<P> {
210
    public ResultType getType();
211
    public P getPayload();
212
    
213
    public static <T> TypedResult<T> empty();
214
    public static <T> TypedResult<T> payload(T payload);
215
    public static <T> TypedResult<T> endOfStream();
216
}
217

218
public enum ResultType {
219
    PAYLOAD, EMPTY, EOS
220
}
221
```
222

223
[Result Handling and Display](./result-handling-display.md)
224

225
### Configuration and Options
226

227
Configuration system for SQL client behavior including result modes, display options, and execution parameters.
228

229
```java { .api }
230
public class SqlClientOptions {
231
    public static final ConfigOption<Integer> EXECUTION_MAX_TABLE_RESULT_ROWS;
232
    public static final ConfigOption<ResultMode> EXECUTION_RESULT_MODE;
233
    public static final ConfigOption<Boolean> VERBOSE;
234
    public static final ConfigOption<Integer> DISPLAY_MAX_COLUMN_WIDTH;
235
}
236

237
public enum ResultMode {
238
    TABLE, CHANGELOG, TABLEAU
239
}
240
```
241

242
[Configuration and Options](./configuration-options.md)
243

244
## Exception Handling
245

246
```java { .api }
247
public class SqlClientException extends RuntimeException {
248
    public SqlClientException(String message);
249
    public SqlClientException(String message, Throwable cause);
250
    public SqlClientException(Throwable cause);
251
}
252

253
public class SqlExecutionException extends Exception {
254
    public SqlExecutionException(String message);
255
    public SqlExecutionException(String message, Throwable cause);
256
}
257
```
258

259
## Utility Classes
260

261
```java { .api }
262
public class LocalContextUtils {
263
    public static DefaultContext buildDefaultContext(CliOptions options);
264
    public static SessionContext buildSessionContext(String sessionId, DefaultContext defaultContext);
265
}
266

267
public class CliOptionsParser {
268
    public static CliOptions parseEmbeddedModeClient(String[] args);
269
    public static void printHelpEmbeddedModeClient();
270
}
271

272
public class TerminalUtils {
273
    public static Terminal createDefaultTerminal();
274
    public static Terminal createDumbTerminal(OutputStream outputStream);
275
}
276
```