0
# CDAP Explore Client
1

2
CDAP Explore Client provides Java interfaces for exploring and querying datasets within the Cask Data Application Platform (CDAP) using Apache Hive SQL. It offers both synchronous and asynchronous query execution capabilities, metadata exploration, and dataset management operations.
3

4
## Package Information
5

6
- **Package Name**: cdap-explore-client
7
- **Package Type**: maven
8
- **Group ID**: co.cask.cdap
9
- **Artifact ID**: cdap-explore-client
10
- **Version**: 5.1.2
11
- **Language**: Java
12
- **Installation**: Include in Maven dependencies or access via CDAP platform
13

14
## Core Imports
15

16
```java
17
import co.cask.cdap.explore.client.ExploreClient;
18
import co.cask.cdap.explore.client.ExploreFacade;
19
import co.cask.cdap.explore.service.Explore;
20
import co.cask.cdap.explore.client.ExploreExecutionResult;
21
import co.cask.cdap.explore.service.ExploreException;
22
import co.cask.cdap.common.UnauthenticatedException;
23
import co.cask.cdap.common.ServiceUnavailableException;
24
```
25

26
Common client implementations:
27
```java
28
import co.cask.cdap.explore.client.DiscoveryExploreClient;
29
import co.cask.cdap.explore.client.FixedAddressExploreClient;
30
```
31

32
## Basic Usage
33

34
```java
35
import co.cask.cdap.explore.client.ExploreClient;
36
import co.cask.cdap.explore.client.ExploreExecutionResult;
37
import co.cask.cdap.proto.QueryResult;
38
import co.cask.cdap.proto.id.NamespaceId;
39
import com.google.common.util.concurrent.ListenableFuture;
40

41
// Initialize client (typically via dependency injection)
42
ExploreClient client = // obtained via Guice injection
43

44
// Execute SQL query asynchronously
45
NamespaceId namespace = new NamespaceId("default");
46
ListenableFuture<ExploreExecutionResult> future = 
47
    client.submit(namespace, "SELECT * FROM dataset_table LIMIT 10");
48

49
// Handle results
50
try {
51
    ExploreExecutionResult result = future.get();
52
    
53
    // Check if results are available
54
    if (result.canContainResults()) {
55
        // Iterate through results
56
        while (result.hasNext()) {
57
            QueryResult row = result.next();
58
            // Process row data
59
            System.out.println(row.toString());
60
        }
61
    }
62
    
63
    // Always close resources
64
    result.close();
65
} catch (Exception e) {
66
    // Handle exploration errors
67
    System.err.println("Query failed: " + e.getMessage());
68
}
69
```
70

71
## Architecture
72

73
CDAP Explore Client is built around several key architectural components:
74

75
- **Client Layer**: `ExploreClient` implementations providing HTTP-based communication with CDAP explore service
76
- **Service Interface**: `Explore` interface defining the contract for Hive SQL operations  
77
- **Result Handling**: `ExploreExecutionResult` for streaming and managing query results
78
- **Service Discovery**: Dynamic endpoint resolution via Twill service discovery
79
- **Facade Pattern**: `ExploreFacade` providing simplified operations for common use cases
80
- **Dependency Injection**: Guice-based configuration and client instantiation
81

82
## Capabilities
83

84
### Client Operations
85

86
Core client functionality for executing SQL queries, managing connections, and handling dataset operations. Provides both direct client interfaces and simplified facade patterns.
87

88
```java { .api }
89
interface ExploreClient extends Closeable {
90
    void ping() throws UnauthenticatedException, ServiceUnavailableException, ExploreException;
91
    ListenableFuture<ExploreExecutionResult> submit(NamespaceId namespace, String statement);
92
    ListenableFuture<Void> enableExploreDataset(DatasetId datasetInstance);
93
    ListenableFuture<Void> disableExploreDataset(DatasetId datasetInstance);
94
}
95
```
96

97
[Client Operations](./client-operations.md)
98

99
### Query Execution
100

101
Synchronous and asynchronous SQL query execution with comprehensive result handling, status monitoring, and resource management.
102

103
```java { .api }
104
interface Explore {
105
    QueryHandle execute(NamespaceId namespace, String statement) throws ExploreException, SQLException;
106
    QueryStatus getStatus(QueryHandle handle) throws HandleNotFoundException, SQLException;
107
    List<QueryResult> nextResults(QueryHandle handle, int size) throws HandleNotFoundException, SQLException;
108
    void close(QueryHandle handle) throws HandleNotFoundException, SQLException;
109
}
110
```
111

112
[Query Execution](./query-execution.md)
113

114
### Metadata Operations
115

116
Database metadata exploration including table discovery, column information, schema browsing, and catalog management.
117

118
```java { .api }
119
interface Explore {
120
    QueryHandle getColumns(String catalog, String schemaPattern, 
121
                          String tableNamePattern, String columnNamePattern) throws ExploreException, SQLException;
122
    QueryHandle getTables(String catalog, String schemaPattern, 
123
                         String tableNamePattern, List<String> tableTypes) throws ExploreException, SQLException;
124
    List<TableNameInfo> getTables(String namespace) throws ExploreException, SQLException;
125
    TableInfo getTableInfo(String namespace, String table) throws ExploreException, SQLException, TableNotFoundException;
126
}
127
```
128

129
[Metadata Operations](./metadata-operations.md)
130

131
### Dataset Management
132

133
Enable and disable exploration capabilities on CDAP datasets, manage partitions, and handle dataset lifecycle operations.
134

135
```java { .api }
136
interface ExploreClient {
137
    ListenableFuture<Void> enableExploreDataset(DatasetId datasetInstance, 
138
                                               DatasetSpecification spec, boolean truncating);
139
    ListenableFuture<Void> updateExploreDataset(DatasetId datasetInstance, 
140
                                               DatasetSpecification oldSpec, DatasetSpecification newSpec);
141
    ListenableFuture<Void> addPartition(DatasetId datasetInstance, DatasetSpecification spec, 
142
                                       PartitionKey key, String path);
143
}
144
```
145

146
[Dataset Management](./dataset-management.md)
147

148
## Core Types
149

150
```java { .api }
151
interface ExploreExecutionResult extends Iterator<QueryResult>, Closeable {
152
    List<ColumnDesc> getResultSchema() throws ExploreException;
153
    QueryStatus getStatus();
154
    boolean canContainResults();
155
    int getFetchSize();
156
    void setFetchSize(int fetchSize);
157
}
158

159
class QueryHandle {
160
    // Immutable handle for tracking query execution
161
}
162

163
class QueryStatus {
164
    public enum OpStatus { INITIALIZED, RUNNING, FINISHED, CANCELED, CLOSED, ERROR, UNKNOWN, PENDING }
165
    public OpStatus getStatus();
166
    public boolean hasResultSet();
167
}
168

169
class ColumnDesc {
170
    public String getName();
171
    public String getType();
172
    public int getPosition();
173
    public String getComment();
174
}
175

176
class QueryResult {
177
    public List<Object> getColumns();
178
}
179

180
class ExploreException extends Exception {
181
    public ExploreException(String message);
182
    public ExploreException(String message, Throwable cause);
183
}
184

185
class UnauthenticatedException extends Exception {
186
    // Exception thrown when the client is not authenticated
187
}
188

189
class ServiceUnavailableException extends Exception {
190
    // Exception thrown when the explore service is not available
191
}
192

193
class HandleNotFoundException extends Exception {
194
    public boolean isInactive();
195
}
196

197
class TableNotFoundException extends Exception {
198
    // Exception for table not found errors
199
}
200

201
class DatasetId {
202
    public DatasetId(String namespace, String dataset);
203
    public String getNamespace();
204
    public String getDataset();
205
}
206

207
class StreamId {
208
    public StreamId(String namespace, String stream);
209
    public String getNamespace();
210
    public String getStream();
211
}
212

213
class NamespaceId {
214
    public NamespaceId(String namespace);
215
    public String getNamespace();
216
}
217

218
class DatasetSpecification {
219
    public String getName();
220
    public String getType();
221
    public Map<String, String> getProperties();
222
}
223

224
class PartitionKey {
225
    public static Builder builder();
226
    public static class Builder {
227
        Builder addStringField(String name, String value);
228
        Builder addIntField(String name, int value);
229
        Builder addLongField(String name, long value);
230
        PartitionKey build();
231
    }
232
}
233

234
class FormatSpecification {
235
    public static Builder builder(String name);
236
    public String getName();
237
    public Schema getSchema();
238
    public static class Builder {
239
        Builder setSchema(Schema schema);
240
        FormatSpecification build();
241
    }
242
}
243

244
class NamespaceMeta {
245
    public NamespaceMeta(String name, String displayName, String description);
246
    public String getName();
247
    public String getDisplayName();
248
    public String getDescription();
249
}
250
```