0
# Query Execution
1

2
Synchronous and asynchronous SQL query execution with comprehensive result handling, status monitoring, and resource management. Supports both blocking operations via the Explore interface and non-blocking operations via ExploreClient.
3

4
## Capabilities
5

6
### Synchronous Query Execution
7

8
Direct SQL execution with immediate result handling via the Explore service interface.
9

10
```java { .api }
11
/**
12
 * Core explore service interface for synchronous operations
13
 */
14
interface Explore {
15
    /**
16
     * Execute SQL statement synchronously
17
     * @param namespace namespace context for the query
18
     * @param statement SQL statement to execute
19
     * @return query handle for result retrieval
20
     * @throws ExploreException if query execution fails
21
     */
22
    QueryHandle execute(NamespaceId namespace, String statement) throws ExploreException, SQLException;
23
    
24
    /**
25
     * Execute SQL with additional session configuration
26
     * @param namespace namespace context
27
     * @param statement SQL statement
28
     * @param additionalSessionConf additional Hive session configuration
29
     * @return query handle for result retrieval
30
     * @throws ExploreException if query execution fails
31
     * @throws SQLException if SQL error occurs
32
     */
33
    QueryHandle execute(NamespaceId namespace, String statement, 
34
                       Map<String, String> additionalSessionConf) throws ExploreException, SQLException;
35
    
36
    /**
37
     * Get current status of a query
38
     * @param handle query handle
39
     * @return current query status
40
     * @throws HandleNotFoundException if handle is not found
41
     * @throws SQLException if SQL error occurs
42
     */
43
    QueryStatus getStatus(QueryHandle handle) throws HandleNotFoundException, SQLException;
44
    
45
    /**
46
     * Get result schema for a query
47
     * @param handle query handle
48
     * @return list of column descriptions
49
     * @throws HandleNotFoundException if handle is not found
50
     */
51
    List<ColumnDesc> getResultSchema(QueryHandle handle) throws HandleNotFoundException, SQLException;
52
    
53
    /**
54
     * Fetch next batch of results
55
     * @param handle query handle
56
     * @param size maximum number of results to fetch
57
     * @return list of query results
58
     * @throws HandleNotFoundException if handle is not found
59
     * @throws SQLException if SQL error occurs
60
     */
61
    List<QueryResult> nextResults(QueryHandle handle, int size) throws HandleNotFoundException, SQLException;
62
    
63
    /**
64
     * Preview results without advancing cursor
65
     * @param handle query handle
66
     * @return preview of query results
67
     * @throws HandleNotFoundException if handle is not found
68
     * @throws SQLException if SQL error occurs
69
     */
70
    List<QueryResult> previewResults(QueryHandle handle) throws HandleNotFoundException, SQLException;
71
    
72
    /**
73
     * Close query handle and release resources
74
     * @param handle query handle to close
75
     * @throws HandleNotFoundException if handle is not found
76
     * @throws SQLException if SQL error occurs
77
     */
78
    void close(QueryHandle handle) throws HandleNotFoundException, SQLException;
79
    
80
    /**
81
     * Get information about active queries in namespace
82
     * @param namespace namespace to query
83
     * @return list of query information
84
     * @throws ExploreException if operation fails
85
     * @throws SQLException if SQL error occurs
86
     */
87
    List<QueryInfo> getQueries(NamespaceId namespace) throws ExploreException, SQLException;
88
    
89
    /**
90
     * Get count of active queries in namespace
91
     * @param namespace namespace to check
92
     * @return number of active queries
93
     * @throws ExploreException if operation fails
94
     * @throws SQLException if SQL error occurs
95
     */
96
    int getActiveQueryCount(NamespaceId namespace) throws ExploreException, SQLException;
97
}
98
```
99

100
### Asynchronous Query Execution
101

102
Non-blocking query execution via ExploreClient with ListenableFuture results.
103

104
```java { .api }
105
/**
106
 * Asynchronous query execution methods
107
 */
108
interface ExploreClient {
109
    /**
110
     * Submit SQL statement for asynchronous execution
111
     * @param namespace namespace context for the query
112
     * @param statement SQL statement to execute
113
     * @return future containing execution results
114
     */
115
    ListenableFuture<ExploreExecutionResult> submit(NamespaceId namespace, String statement);
116
}
117
```
118

119
### Result Handling
120

121
Comprehensive result processing with streaming support and schema access.
122

123
```java { .api }
124
/**
125
 * Results of an explore statement execution
126
 */
127
interface ExploreExecutionResult extends Iterator<QueryResult>, Closeable {
128
    /**
129
     * Get current fetch size hint
130
     * @return current fetch size
131
     */
132
    int getFetchSize();
133
    
134
    /**
135
     * Set fetch size hint for result retrieval
136
     * @param fetchSize hint for number of rows to fetch per batch
137
     */
138
    void setFetchSize(int fetchSize);
139
    
140
    /**
141
     * Get schema information for result set
142
     * @return list of column descriptions
143
     * @throws ExploreException if schema cannot be retrieved
144
     */
145
    List<ColumnDesc> getResultSchema() throws ExploreException;
146
    
147
    /**
148
     * Check if query can contain result data
149
     * @return true if results may be available
150
     */
151
    boolean canContainResults();
152
    
153
    /**
154
     * Get current execution status
155
     * @return query execution status
156
     */
157
    QueryStatus getStatus();
158
}
159

160
/**
161
 * Query execution status information
162
 */
163
class QueryStatus {
164
    public enum OpStatus { 
165
        INITIALIZED, RUNNING, FINISHED, CANCELED, CLOSED, ERROR, UNKNOWN, PENDING 
166
    }
167
    
168
    /**
169
     * Get current operation status
170
     * @return status enum value
171
     */
172
    public OpStatus getStatus();
173
    
174
    /**
175
     * Check if query has result set available
176
     * @return true if results are available
177
     */
178
    public boolean hasResultSet();
179
    
180
    /**
181
     * Get error message if query failed
182
     * @return error message or null if no error
183
     */
184
    public String getErrorMessage();
185
    
186
    /**
187
     * Get SQL state if query failed
188
     * @return SQL state or null if no error
189
     */
190
    public String getSqlState();
191
    
192
    /**
193
     * Get operation handle
194
     * @return query handle
195
     */
196
    public QueryHandle getOperationHandle();
197
}
198

199
/**
200
 * Individual query result row
201
 */
202
class QueryResult {
203
    /**
204
     * Get column values for this result row
205
     * @return list of column values
206
     */
207
    public List<Object> getColumns();
208
}
209

210
/**
211
 * Information about an active query
212
 */
213
class QueryInfo {
214
    /**
215
     * Get query handle
216
     * @return query handle
217
     */
218
    public QueryHandle getQueryHandle();
219
    
220
    /**
221
     * Get SQL statement
222
     * @return SQL statement text
223
     */
224
    public String getStatement();
225
    
226
    /**
227
     * Get query timestamp
228
     * @return query start timestamp
229
     */
230
    public long getTimestamp();
231
    
232
    /**
233
     * Check if query is active
234
     * @return true if query is active
235
     */
236
    public boolean isActive();
237
}
238
```
239

240
**Usage Examples:**
241

242
```java
243
import co.cask.cdap.explore.service.Explore;
244
import co.cask.cdap.explore.client.ExploreClient;
245
import co.cask.cdap.explore.client.ExploreExecutionResult;
246
import co.cask.cdap.proto.QueryResult;
247
import co.cask.cdap.proto.QueryStatus;
248
import co.cask.cdap.proto.id.NamespaceId;
249

250
// Synchronous execution via Explore interface
251
Explore explore = // obtained via dependency injection
252
NamespaceId namespace = new NamespaceId("default");
253

254
try {
255
    // Execute query and get handle
256
    QueryHandle handle = explore.execute(namespace, "SELECT * FROM my_table LIMIT 100");
257
    
258
    // Check query status
259
    QueryStatus status = explore.getStatus(handle);
260
    while (status.getStatus() == QueryStatus.OpStatus.RUNNING) {
261
        Thread.sleep(1000);
262
        status = explore.getStatus(handle);
263
    }
264
    
265
    if (status.hasResultSet()) {
266
        // Get result schema
267
        List<ColumnDesc> schema = explore.getResultSchema(handle);
268
        System.out.println("Columns: " + schema.size());
269
        
270
        // Fetch results in batches
271
        List<QueryResult> results;
272
        do {
273
            results = explore.nextResults(handle, 50);
274
            for (QueryResult row : results) {
275
                System.out.println("Row: " + row.getColumns());
276
            }
277
        } while (!results.isEmpty());
278
    }
279
    
280
    // Always close handle
281
    explore.close(handle);
282
    
283
} catch (ExploreException e) {
284
    System.err.println("Query execution failed: " + e.getMessage());
285
}
286

287
// Asynchronous execution via ExploreClient
288
ExploreClient client = // obtained via dependency injection
289

290
try {
291
    // Submit query asynchronously
292
    ListenableFuture<ExploreExecutionResult> future = 
293
        client.submit(namespace, "SELECT COUNT(*) FROM large_dataset");
294
    
295
    // Process results when ready
296
    ExploreExecutionResult result = future.get(30, TimeUnit.SECONDS);
297
    
298
    // Check if results are available
299
    if (result.canContainResults()) {
300
        // Set fetch size for performance
301
        result.setFetchSize(1000);
302
        
303
        // Stream through results
304
        while (result.hasNext()) {
305
            QueryResult row = result.next();
306
            // Process each row
307
            System.out.println("Result: " + row.getColumns());
308
        }
309
    }
310
    
311
    // Always close resources
312
    result.close();
313
    
314
} catch (Exception e) {
315
    System.err.println("Async query failed: " + e.getMessage());
316
}
317

318
// Query monitoring
319
try {
320
    List<QueryInfo> activeQueries = explore.getQueries(namespace);
321
    System.out.println("Active queries: " + activeQueries.size());
322
    
323
    int queryCount = explore.getActiveQueryCount(namespace);
324
    System.out.println("Total active: " + queryCount);
325
    
326
} catch (ExploreException e) {
327
    System.err.println("Query monitoring failed: " + e.getMessage());
328
}
329
```
330

331
### Error Handling
332

333
Comprehensive error handling for query execution scenarios.
334

335
```java { .api }
336
/**
337
 * General explore operation exception
338
 */
339
class ExploreException extends Exception {
340
    public ExploreException(String message);
341
    public ExploreException(String message, Throwable cause);
342
    public ExploreException(Throwable cause);
343
}
344

345
/**
346
 * Exception thrown when query handle is not found
347
 */
348
class HandleNotFoundException extends Exception {
349
    /**
350
     * Check if handle became inactive
351
     * @return true if handle is inactive
352
     */
353
    public boolean isInactive();
354
}
355
```
356

357
**Common Error Scenarios:**
358
- **Service Unavailable**: Explore service is not running or unreachable
359
- **Handle Not Found**: Query handle expired or was never created
360
- **SQL Errors**: Malformed SQL or table/column not found
361
- **Timeout Errors**: Query execution exceeds configured timeouts
362
- **Authentication Errors**: Insufficient permissions for query execution