0
# Metadata Operations
1

2
Database metadata exploration including table discovery, column information, schema browsing, catalog management, and database system information retrieval. Provides comprehensive metadata access for both interactive exploration and programmatic database introspection.
3

4
## Capabilities
5

6
### Table Discovery
7

8
Discover and list tables available for exploration within namespaces and schemas.
9

10
```java { .api }
11
/**
12
 * Table discovery and information retrieval
13
 */
14
interface Explore {
15
    /**
16
     * Get table descriptions matching pattern
17
     * @param catalog catalog name (can be null)
18
     * @param schemaPattern schema name pattern (can be null)
19
     * @param tableNamePattern table name pattern (can be null) 
20
     * @param tableTypes list of table types to include (can be null)
21
     * @return query handle for table metadata results
22
     * @throws ExploreException if operation fails
23
     */
24
    QueryHandle getTables(String catalog, String schemaPattern, 
25
                         String tableNamePattern, List<String> tableTypes) throws ExploreException, SQLException;
26
    
27
    /**
28
     * Get table names in a specific namespace
29
     * @param namespace namespace to search
30
     * @return list of table name information
31
     * @throws ExploreException if operation fails
32
     * @throws SQLException if SQL error occurs
33
     */
34
    List<TableNameInfo> getTables(String namespace) throws ExploreException, SQLException;
35
    
36
    /**
37
     * Get detailed information about a specific table
38
     * @param namespace namespace containing the table
39
     * @param table table name
40
     * @return table information
41
     * @throws ExploreException if operation fails
42
     * @throws SQLException if SQL error occurs
43
     * @throws TableNotFoundException if table does not exist
44
     */
45
    TableInfo getTableInfo(String namespace, String table) 
46
        throws ExploreException, SQLException, TableNotFoundException;
47
    
48
    /**
49
     * Get table information with database specification
50
     * @param namespace namespace containing the table
51
     * @param database database name
52
     * @param table table name
53
     * @return table information
54
     * @throws ExploreException if operation fails
55
     * @throws TableNotFoundException if table does not exist
56
     */
57
    TableInfo getTableInfo(String namespace, String database, String table) 
58
        throws ExploreException, SQLException, TableNotFoundException;
59
    
60
    /**
61
     * Get available table types
62
     * @return query handle for table type results
63
     * @throws ExploreException if operation fails
64
     * @throws SQLException if SQL error occurs
65
     */
66
    QueryHandle getTableTypes() throws ExploreException, SQLException;
67
}
68

69
/**
70
 * Asynchronous table operations via ExploreClient
71
 */
72
interface ExploreClient {
73
    /**
74
     * Get table descriptions asynchronously
75
     * @param catalog catalog name
76
     * @param schemaPattern schema pattern
77
     * @param tableNamePattern table name pattern
78
     * @param tableTypes table types to include
79
     * @return future containing table metadata results
80
     */
81
    ListenableFuture<ExploreExecutionResult> tables(String catalog, String schemaPattern, 
82
                                                   String tableNamePattern, List<String> tableTypes);
83
    
84
    /**
85
     * Get table types asynchronously
86
     * @return future containing table type results
87
     */
88
    ListenableFuture<ExploreExecutionResult> tableTypes();
89
}
90
```
91

92
### Column Metadata
93

94
Retrieve detailed column information including types, constraints, and descriptions.
95

96
```java { .api }
97
/**
98
 * Column metadata operations
99
 */
100
interface Explore {
101
    /**
102
     * Get column descriptions matching patterns
103
     * @param catalog catalog name (can be null)
104
     * @param schemaPattern schema name pattern (can be null)
105
     * @param tableNamePattern table name pattern (can be null)
106
     * @param columnNamePattern column name pattern (can be null)
107
     * @return query handle for column metadata results
108
     * @throws ExploreException if operation fails
109
     */
110
    QueryHandle getColumns(String catalog, String schemaPattern, 
111
                          String tableNamePattern, String columnNamePattern) throws ExploreException, SQLException;
112
}
113

114
/**
115
 * Asynchronous column operations
116
 */
117
interface ExploreClient {
118
    /**
119
     * Get column descriptions asynchronously
120
     * @param catalog catalog name
121
     * @param schemaPattern schema pattern
122
     * @param tableNamePattern table name pattern  
123
     * @param columnNamePattern column name pattern
124
     * @return future containing column metadata results
125
     */
126
    ListenableFuture<ExploreExecutionResult> columns(String catalog, String schemaPattern,
127
                                                    String tableNamePattern, String columnNamePattern);
128
}
129

130
/**
131
 * Column description information
132
 */
133
class ColumnDesc {
134
    /**
135
     * Get column name
136
     * @return column name
137
     */
138
    public String getName();
139
    
140
    /**
141
     * Get column data type
142
     * @return column type (e.g., "string", "int", "double")
143
     */
144
    public String getType();
145
    
146
    /**
147
     * Get column position in table
148
     * @return 1-based column position
149
     */
150
    public int getPosition();
151
    
152
    /**
153
     * Get column comment/description
154
     * @return column comment or null if none
155
     */
156
    public String getComment();
157
    
158
    /**
159
     * Check if column allows null values
160
     * @return true if nullable
161
     */
162
    public boolean isNullable();
163
}
164
```
165

166
### Schema and Catalog Management
167

168
Browse database schemas, catalogs, and organizational structures.
169

170
```java { .api }
171
/**
172
 * Schema and catalog operations
173
 */
174
interface Explore {
175
    /**
176
     * Get catalog names
177
     * @return query handle for catalog results
178
     * @throws ExploreException if operation fails
179
     */
180
    QueryHandle getCatalogs() throws ExploreException, SQLException;
181
    
182
    /**
183
     * Get schema names matching pattern
184
     * @param catalog catalog name (can be null)
185
     * @param schemaPattern schema name pattern (can be null)
186
     * @return query handle for schema results
187
     * @throws ExploreException if operation fails
188
     * @throws SQLException if SQL error occurs
189
     */
190
    QueryHandle getSchemas(String catalog, String schemaPattern) throws ExploreException, SQLException;
191
}
192

193
/**
194
 * Asynchronous schema and catalog operations
195
 */
196
interface ExploreClient {
197
    /**
198
     * Get catalogs asynchronously
199
     * @return future containing catalog results
200
     */
201
    ListenableFuture<ExploreExecutionResult> catalogs();
202
    
203
    /**
204
     * Get schemas asynchronously
205
     * @param catalog catalog name
206
     * @param schemaPattern schema pattern
207
     * @return future containing schema results
208
     */
209
    ListenableFuture<ExploreExecutionResult> schemas(String catalog, String schemaPattern);
210
}
211
```
212

213
### Function Discovery
214

215
Discover available functions and their metadata.
216

217
```java { .api }
218
/**
219
 * Function metadata operations
220
 */
221
interface Explore {
222
    /**
223
     * Get function descriptions matching patterns
224
     * @param catalog catalog name (can be null)
225
     * @param schemaPattern schema name pattern (can be null)
226
     * @param functionNamePattern function name pattern (can be null)
227
     * @return query handle for function metadata results
228
     * @throws ExploreException if operation fails
229
     */
230
    QueryHandle getFunctions(String catalog, String schemaPattern, 
231
                           String functionNamePattern) throws ExploreException, SQLException;
232
}
233

234
/**
235
 * Asynchronous function operations
236
 */
237
interface ExploreClient {
238
    /**
239
     * Get functions asynchronously
240
     * @param catalog catalog name
241
     * @param schemaPattern schema pattern
242
     * @param functionNamePattern function name pattern
243
     * @return future containing function metadata results
244
     */
245
    ListenableFuture<ExploreExecutionResult> functions(String catalog, String schemaPattern,
246
                                                      String functionNamePattern);
247
}
248
```
249

250
### Database Information
251

252
Retrieve database system information and capabilities.
253

254
```java { .api }
255
/**
256
 * Database information operations
257
 */
258
interface Explore {
259
    /**
260
     * Get database information by type
261
     * @param infoType type of information to retrieve
262
     * @return metadata information
263
     * @throws ExploreException if operation fails
264
     */
265
    MetaDataInfo getInfo(MetaDataInfo.InfoType infoType) throws ExploreException, SQLException;
266
    
267
    /**
268
     * Get data type information
269
     * @return query handle for data type results
270
     * @throws ExploreException if operation fails
271
     * @throws SQLException if SQL error occurs
272
     */
273
    QueryHandle getTypeInfo() throws ExploreException, SQLException;
274
}
275

276
/**
277
 * Asynchronous database information operations
278
 */
279
interface ExploreClient {
280
    /**
281
     * Get database information asynchronously
282
     * @param infoType information type to retrieve
283
     * @return future containing metadata information
284
     */
285
    ListenableFuture<MetaDataInfo> info(MetaDataInfo.InfoType infoType);
286
    
287
    /**
288
     * Get data types asynchronously
289
     * @return future containing data type results
290
     */
291
    ListenableFuture<ExploreExecutionResult> dataTypes();
292
}
293

294
/**
295
 * Database metadata information
296
 */
297
class MetaDataInfo {
298
    /**
299
     * Information type enumeration
300
     */
301
    public enum InfoType {
302
        TABLE_TERM, SCHEMA_TERM, CATALOG_TERM, PROCEDURE_TERM,
303
        MAX_CATALOG_NAME_LENGTH, MAX_SCHEMA_NAME_LENGTH, MAX_TABLE_NAME_LENGTH,
304
        MAX_COLUMN_NAME_LENGTH, MAX_PROCEDURE_NAME_LENGTH, MAX_USER_NAME_LENGTH,
305
        // ... additional info types
306
    }
307
    
308
    /**
309
     * Get string value for the information
310
     * @return string value or null if not applicable
311
     */
312
    public String getStringValue();
313
    
314
    /**
315
     * Get integer value for the information
316
     * @return integer value or -1 if not applicable
317
     */
318
    public int getIntValue();
319
    
320
    /**
321
     * Get long value for the information
322
     * @return long value or -1 if not applicable
323
     */
324
    public long getLongValue();
325
    
326
    /**
327
     * Get short value for the information
328
     * @return short value or -1 if not applicable
329
     */
330
    public short getShortValue();
331
}
332
```
333

334
### Utility Classes
335

336
Helper classes for metadata operations and table naming.
337

338
```java { .api }
339
/**
340
 * Utility for generating explore table names
341
 */
342
class ExploreTableNaming {
343
    /**
344
     * Get table name for a stream
345
     * @param streamId stream identifier
346
     * @return explore table name
347
     */
348
    public static String getTableName(StreamId streamId);
349
    
350
    /**
351
     * Get table name for a dataset
352
     * @param datasetId dataset identifier
353
     * @return explore table name
354
     */
355
    public static String getTableName(DatasetId datasetId);
356
    
357
    /**
358
     * Get table name for dataset with properties
359
     * @param datasetId dataset identifier
360
     * @param properties dataset properties
361
     * @return explore table name
362
     */
363
    public static String getTableName(DatasetId datasetId, Map<String, String> properties);
364
    
365
    /**
366
     * Clean table name for Hive compatibility
367
     * @param name original name
368
     * @return cleaned name suitable for Hive
369
     */
370
    public static String cleanTableName(String name);
371
}
372

373
/**
374
 * Table name information
375
 */
376
class TableNameInfo {
377
    /**
378
     * Get table name
379
     * @return table name
380
     */
381
    public String getTableName();
382
    
383
    /**
384
     * Get database name
385
     * @return database name
386
     */
387
    public String getDatabaseName();
388
    
389
    /**
390
     * Get schema name
391
     * @return schema name or null if not applicable
392
     */
393
    public String getSchemaName();
394
}
395

396
/**
397
 * Detailed table information
398
 */
399
class TableInfo {
400
    /**
401
     * Get table name
402
     * @return table name
403
     */
404
    public String getName();
405
    
406
    /**
407
     * Get database name
408
     * @return database name
409
     */
410
    public String getDbName();
411
    
412
    /**
413
     * Get table owner
414
     * @return owner name
415
     */
416
    public String getOwner();
417
    
418
    /**
419
     * Get creation time
420
     * @return creation timestamp
421
     */
422
    public long getCreationTime();
423
    
424
    /**
425
     * Get last access time
426
     * @return last access timestamp
427
     */
428
    public long getLastAccessTime();
429
    
430
    /**
431
     * Get table location
432
     * @return table location path
433
     */
434
    public String getLocation();
435
    
436
    /**
437
     * Get table schema (columns)
438
     * @return list of column descriptors
439
     */
440
    public List<ColumnDesc> getSchema();
441
}
442
```
443

444
**Usage Examples:**
445

446
```java
447
import co.cask.cdap.explore.service.Explore;
448
import co.cask.cdap.explore.client.ExploreClient;
449
import co.cask.cdap.proto.ColumnDesc;
450
import co.cask.cdap.proto.QueryResult;
451

452
// Synchronous metadata exploration
453
Explore explore = // obtained via dependency injection
454

455
try {
456
    // Discover all tables
457
    QueryHandle tablesHandle = explore.getTables(null, null, null, null);
458
    List<QueryResult> tableResults = explore.nextResults(tablesHandle, 100);
459
    
460
    for (QueryResult result : tableResults) {
461
        List<Object> columns = result.getColumns();
462
        String tableName = (String) columns.get(2); // TABLE_NAME column
463
        System.out.println("Found table: " + tableName);
464
    }
465
    explore.close(tablesHandle);
466
    
467
    // Get column information for a specific table
468
    QueryHandle columnsHandle = explore.getColumns(null, null, "my_table", null);
469
    List<QueryResult> columnResults = explore.nextResults(columnsHandle, 50);
470
    
471
    for (QueryResult result : columnResults) {
472
        List<Object> cols = result.getColumns();
473
        String colName = (String) cols.get(3); // COLUMN_NAME
474
        String colType = (String) cols.get(5); // TYPE_NAME
475
        System.out.println("Column: " + colName + " (" + colType + ")");
476
    }
477
    explore.close(columnsHandle);
478
    
479
    // Get table information using convenience method
480
    List<TableNameInfo> tableNames = explore.getTables("default");
481
    for (TableNameInfo info : tableNames) {
482
        System.out.println("Table: " + info.getTableName() + 
483
                          " in database: " + info.getDatabaseName());
484
    }
485
    
486
} catch (ExploreException e) {
487
    System.err.println("Metadata operation failed: " + e.getMessage());
488
}
489

490
// Asynchronous metadata operations
491
ExploreClient client = // obtained via dependency injection
492

493
try {
494
    // Get database information
495
    ListenableFuture<MetaDataInfo> future = 
496
        client.info(MetaDataInfo.InfoType.MAX_TABLE_NAME_LENGTH);
497
    MetaDataInfo info = future.get();
498
    System.out.println("Max table name length: " + info.getIntValue());
499
    
500
    // Get all catalogs
501
    ListenableFuture<ExploreExecutionResult> catalogsFuture = client.catalogs();
502
    ExploreExecutionResult catalogsResult = catalogsFuture.get();
503
    
504
    while (catalogsResult.hasNext()) {
505
        QueryResult result = catalogsResult.next();
506
        String catalogName = (String) result.getColumns().get(0);
507
        System.out.println("Catalog: " + catalogName);
508
    }
509
    catalogsResult.close();
510
    
511
} catch (Exception e) {
512
    System.err.println("Async metadata operation failed: " + e.getMessage());
513
}
514

515
// Table naming utilities
516
import co.cask.cdap.explore.utils.ExploreTableNaming;
517
import co.cask.cdap.proto.id.DatasetId;
518
import co.cask.cdap.proto.id.StreamId;
519

520
// Generate table names for CDAP entities
521
DatasetId dataset = new DatasetId("default", "user_events");
522
String tableName = ExploreTableNaming.getTableName(dataset);
523
System.out.println("Dataset table name: " + tableName);
524

525
StreamId stream = new StreamId("default", "log_stream");
526
String streamTableName = ExploreTableNaming.getTableName(stream);
527
System.out.println("Stream table name: " + streamTableName);
528

529
// Clean names for Hive compatibility
530
String cleanName = ExploreTableNaming.cleanTableName("my-special.table_name");
531
System.out.println("Clean table name: " + cleanName);
532
```