0
# Metadata Operations
1

2
Comprehensive metadata operations for catalogs, schemas, tables, columns, functions, and type information with full Spark SQL integration and HiveServer2 compatibility.
3

4
## Capabilities
5

6
### Catalog Operations
7

8
Retrieve available catalogs in the Spark SQL environment.
9

10
```java { .api }
11
/**
12
 * Get available catalogs
13
 * @param sessionHandle Session handle for the operation
14
 * @return OperationHandle for fetching catalog results
15
 * @throws HiveSQLException if operation fails
16
 */
17
OperationHandle getCatalogs(SessionHandle sessionHandle) throws HiveSQLException;
18
```
19

20
```scala { .api }
21
/**
22
 * Spark implementation for getting catalogs
23
 */
24
class SparkGetCatalogsOperation extends GetCatalogsOperation {
25
  /**
26
   * Run the catalog listing operation
27
   */
28
  def runInternal(): Unit
29
}
30
```
31

32
**Usage Examples:**
33

34
```java
35
// Get available catalogs
36
OperationHandle catalogOp = cliService.getCatalogs(sessionHandle);
37

38
// Fetch results
39
TRowSet catalogResults = cliService.fetchResults(catalogOp);
40
TTableSchema catalogSchema = cliService.getResultSetMetadata(catalogOp);
41

42
// Process catalog information
43
// Columns: TABLE_CAT (catalog name)
44
for (TRow row : catalogResults.getRows()) {
45
    String catalogName = row.getColVals().get(0).getStringVal().getValue();
46
    System.out.println("Catalog: " + catalogName);
47
}
48
```
49

50
### Schema Operations
51

52
Retrieve database schemas with optional filtering by catalog and schema patterns.
53

54
```java { .api }
55
/**
56
 * Get database schemas
57
 * @param sessionHandle Session handle for the operation
58
 * @param catalogName Catalog name filter (null for all catalogs)
59
 * @param schemaName Schema name pattern (null for all schemas, supports SQL wildcards)
60
 * @return OperationHandle for fetching schema results
61
 * @throws HiveSQLException if operation fails
62
 */
63
OperationHandle getSchemas(SessionHandle sessionHandle, String catalogName, String schemaName) throws HiveSQLException;
64
```
65

66
```scala { .api }
67
/**
68
 * Spark implementation for getting schemas
69
 */
70
class SparkGetSchemasOperation extends GetSchemasOperation {
71
  /**
72
   * Create schema operation with filters
73
   * @param parentSession Parent session for the operation
74
   * @param catalogName Catalog name filter
75
   * @param schemaName Schema name pattern
76
   */
77
  def this(parentSession: HiveSession, catalogName: String, schemaName: String)
78
  
79
  /**
80
   * Run the schema listing operation
81
   */
82
  def runInternal(): Unit
83
}
84
```
85

86
**Usage Examples:**
87

88
```java
89
// Get all schemas
90
OperationHandle schemaOp = cliService.getSchemas(sessionHandle, null, null);
91

92
// Get schemas matching pattern
93
OperationHandle filteredSchemaOp = cliService.getSchemas(sessionHandle, "spark_catalog", "test_%");
94

95
// Fetch results
96
TRowSet schemaResults = cliService.fetchResults(schemaOp);
97

98
// Process schema information  
99
// Columns: TABLE_SCHEM (schema name), TABLE_CATALOG (catalog name)
100
for (TRow row : schemaResults.getRows()) {
101
    String schemaName = row.getColVals().get(0).getStringVal().getValue();
102
    String catalogName = row.getColVals().get(1).getStringVal().getValue();
103
    System.out.println("Schema: " + catalogName + "." + schemaName);
104
}
105
```
106

107
### Table Operations
108

109
Retrieve table metadata with comprehensive filtering options.
110

111
```java { .api }
112
/**
113
 * Get tables with filtering options
114
 * @param sessionHandle Session handle for the operation
115
 * @param catalogName Catalog name filter (null for all catalogs)
116
 * @param schemaName Schema name pattern (null for all schemas, supports SQL wildcards)
117
 * @param tableName Table name pattern (null for all tables, supports SQL wildcards)
118
 * @param tableTypes List of table types to include (null for all types)
119
 * @return OperationHandle for fetching table results
120
 * @throws HiveSQLException if operation fails
121
 */
122
OperationHandle getTables(SessionHandle sessionHandle, String catalogName, String schemaName, String tableName, List<String> tableTypes) throws HiveSQLException;
123
```
124

125
```scala { .api }
126
/**
127
 * Spark implementation for getting tables
128
 */
129
class SparkGetTablesOperation extends GetTablesOperation {
130
  /**
131
   * Create table operation with comprehensive filters
132
   * @param parentSession Parent session for the operation
133
   * @param catalogName Catalog name filter
134
   * @param schemaName Schema name pattern
135
   * @param tableName Table name pattern
136
   * @param tableTypes List of table types to include
137
   */
138
  def this(parentSession: HiveSession, catalogName: String, schemaName: String, tableName: String, tableTypes: JList[String])
139
  
140
  /**
141
   * Run the table listing operation
142
   */
143
  def runInternal(): Unit
144
}
145
```
146

147
**Usage Examples:**
148

149
```java
150
import java.util.Arrays;
151

152
// Get all tables
153
OperationHandle tableOp = cliService.getTables(sessionHandle, null, null, null, null);
154

155
// Get only external tables in specific schema
156
List<String> tableTypes = Arrays.asList("EXTERNAL_TABLE");
157
OperationHandle extTableOp = cliService.getTables(sessionHandle, "spark_catalog", "default", null, tableTypes);
158

159
// Get tables matching pattern
160
OperationHandle patternTableOp = cliService.getTables(sessionHandle, null, "sales", "fact_%", null);
161

162
// Fetch results
163
TRowSet tableResults = cliService.fetchResults(tableOp);
164

165
// Process table information
166
// Columns: TABLE_CAT, TABLE_SCHEM, TABLE_NAME, TABLE_TYPE, REMARKS
167
for (TRow row : tableResults.getRows()) {
168
    String catalog = row.getColVals().get(0).getStringVal().getValue();
169
    String schema = row.getColVals().get(1).getStringVal().getValue();
170
    String tableName = row.getColVals().get(2).getStringVal().getValue();
171
    String tableType = row.getColVals().get(3).getStringVal().getValue();
172
    String remarks = row.getColVals().get(4).getStringVal().getValue();
173
    
174
    System.out.println(String.format("Table: %s.%s.%s (%s)", catalog, schema, tableName, tableType));
175
}
176
```
177

178
### Table Type Operations
179

180
Get supported table types in the current Spark SQL environment.
181

182
```java { .api }
183
/**
184
 * Get supported table types
185
 * @param sessionHandle Session handle for the operation
186
 * @return OperationHandle for fetching table type results
187
 * @throws HiveSQLException if operation fails
188
 */
189
OperationHandle getTableTypes(SessionHandle sessionHandle) throws HiveSQLException;
190
```
191

192
```scala { .api }
193
/**
194
 * Spark implementation for getting table types
195
 */
196
class SparkGetTableTypesOperation extends GetTableTypesOperation {
197
  /**
198
   * Run the table types operation
199
   */
200
  def runInternal(): Unit
201
}
202
```
203

204
**Usage Examples:**
205

206
```java
207
// Get supported table types
208
OperationHandle tableTypeOp = cliService.getTableTypes(sessionHandle);
209
TRowSet tableTypeResults = cliService.fetchResults(tableTypeOp);
210

211
// Process table types
212
// Columns: TABLE_TYPE
213
for (TRow row : tableTypeResults.getRows()) {
214
    String tableType = row.getColVals().get(0).getStringVal().getValue();
215
    System.out.println("Supported table type: " + tableType);
216
}
217
// Output: TABLE, VIEW, EXTERNAL_TABLE, etc.
218
```
219

220
### Column Operations
221

222
Retrieve detailed column information with filtering capabilities.
223

224
```java { .api }
225
/**
226
 * Get column information for tables
227
 * @param sessionHandle Session handle for the operation
228
 * @param catalogName Catalog name filter (null for all catalogs)
229
 * @param schemaName Schema name pattern (null for all schemas, supports SQL wildcards)
230
 * @param tableName Table name pattern (null for all tables, supports SQL wildcards)
231
 * @param columnName Column name pattern (null for all columns, supports SQL wildcards)
232
 * @return OperationHandle for fetching column results
233
 * @throws HiveSQLException if operation fails
234
 */
235
OperationHandle getColumns(SessionHandle sessionHandle, String catalogName, String schemaName, String tableName, String columnName) throws HiveSQLException;
236
```
237

238
```scala { .api }
239
/**
240
 * Spark implementation for getting columns
241
 */
242
class SparkGetColumnsOperation extends GetColumnsOperation {
243
  /**
244
   * Create column operation with filters
245
   * @param parentSession Parent session for the operation
246
   * @param catalogName Catalog name filter
247
   * @param schemaName Schema name pattern
248
   * @param tableName Table name pattern
249
   * @param columnName Column name pattern
250
   */
251
  def this(parentSession: HiveSession, catalogName: String, schemaName: String, tableName: String, columnName: String)
252
  
253
  /**
254
   * Run the column listing operation
255
   */
256
  def runInternal(): Unit
257
}
258
```
259

260
**Usage Examples:**
261

262
```java
263
// Get all columns for a specific table
264
OperationHandle columnOp = cliService.getColumns(sessionHandle, "spark_catalog", "default", "employees", null);
265

266
// Get columns matching pattern
267
OperationHandle patternColumnOp = cliService.getColumns(sessionHandle, null, null, "fact_%", "date_%");
268

269
// Fetch results
270
TRowSet columnResults = cliService.fetchResults(columnOp);
271

272
// Process column information
273
// Columns: TABLE_CAT, TABLE_SCHEM, TABLE_NAME, COLUMN_NAME, DATA_TYPE, TYPE_NAME, 
274
//          COLUMN_SIZE, BUFFER_LENGTH, DECIMAL_DIGITS, NUM_PREC_RADIX, NULLABLE,
275
//          REMARKS, COLUMN_DEF, SQL_DATA_TYPE, SQL_DATETIME_SUB, CHAR_OCTET_LENGTH,
276
//          ORDINAL_POSITION, IS_NULLABLE, SCOPE_CATALOG, SCOPE_SCHEMA, SCOPE_TABLE,
277
//          SOURCE_DATA_TYPE, IS_AUTO_INCREMENT
278
for (TRow row : columnResults.getRows()) {
279
    String catalog = row.getColVals().get(0).getStringVal().getValue();
280
    String schema = row.getColVals().get(1).getStringVal().getValue();
281
    String tableName = row.getColVals().get(2).getStringVal().getValue();
282
    String columnName = row.getColVals().get(3).getStringVal().getValue();
283
    int dataType = row.getColVals().get(4).getI32Val().getValue();
284
    String typeName = row.getColVals().get(5).getStringVal().getValue();
285
    int columnSize = row.getColVals().get(6).getI32Val().getValue();
286
    int ordinalPosition = row.getColVals().get(16).getI32Val().getValue();
287
    
288
    System.out.println(String.format("Column: %s.%s.%s.%s - %s(%d) at position %d", 
289
        catalog, schema, tableName, columnName, typeName, columnSize, ordinalPosition));
290
}
291
```
292

293
### Function Operations
294

295
Retrieve information about available functions with filtering support.
296

297
```java { .api }
298
/**
299
 * Get function information
300
 * @param sessionHandle Session handle for the operation
301
 * @param catalogName Catalog name filter (null for all catalogs)
302
 * @param schemaName Schema name pattern (null for all schemas, supports SQL wildcards)
303
 * @param functionName Function name pattern (null for all functions, supports SQL wildcards)
304
 * @return OperationHandle for fetching function results
305
 * @throws HiveSQLException if operation fails
306
 */
307
OperationHandle getFunctions(SessionHandle sessionHandle, String catalogName, String schemaName, String functionName) throws HiveSQLException;
308
```
309

310
```scala { .api }
311
/**
312
 * Spark implementation for getting functions
313
 */
314
class SparkGetFunctionsOperation extends GetFunctionsOperation {
315
  /**
316
   * Create function operation with filters
317
   * @param parentSession Parent session for the operation
318
   * @param catalogName Catalog name filter
319
   * @param schemaName Schema name pattern
320
   * @param functionName Function name pattern
321
   */
322
  def this(parentSession: HiveSession, catalogName: String, schemaName: String, functionName: String)
323
  
324
  /**
325
   * Run the function listing operation
326
   */
327
  def runInternal(): Unit
328
}
329
```
330

331
**Usage Examples:**
332

333
```java
334
// Get all functions
335
OperationHandle functionOp = cliService.getFunctions(sessionHandle, null, null, null);
336

337
// Get functions matching pattern
338
OperationHandle patternFunctionOp = cliService.getFunctions(sessionHandle, null, null, "date_%");
339

340
// Get built-in functions only
341
OperationHandle builtinFunctionOp = cliService.getFunctions(sessionHandle, "system", "builtin", null);
342

343
// Fetch results
344
TRowSet functionResults = cliService.fetchResults(functionOp);
345

346
// Process function information
347
// Columns: FUNCTION_CAT, FUNCTION_SCHEM, FUNCTION_NAME, REMARKS, FUNCTION_TYPE, SPECIFIC_NAME
348
for (TRow row : functionResults.getRows()) {
349
    String catalog = row.getColVals().get(0).getStringVal().getValue();
350
    String schema = row.getColVals().get(1).getStringVal().getValue();
351
    String functionName = row.getColVals().get(2).getStringVal().getValue();
352
    String remarks = row.getColVals().get(3).getStringVal().getValue();
353
    int functionType = row.getColVals().get(4).getI32Val().getValue();
354
    
355
    String typeDesc = switch (functionType) {
356
        case 1 -> "SQL Function";
357
        case 2 -> "Table Function";
358
        default -> "Unknown";
359
    };
360
    
361
    System.out.println(String.format("Function: %s.%s.%s (%s) - %s", 
362
        catalog, schema, functionName, typeDesc, remarks));
363
}
364
```
365

366
### Type Information Operations
367

368
Get comprehensive SQL type information supported by Spark SQL.
369

370
```java { .api }
371
/**
372
 * Get SQL type information
373
 * @param sessionHandle Session handle for the operation
374
 * @return OperationHandle for fetching type information results
375
 * @throws HiveSQLException if operation fails
376
 */
377
OperationHandle getTypeInfo(SessionHandle sessionHandle) throws HiveSQLException;
378
```
379

380
```scala { .api }
381
/**
382
 * Spark implementation for getting type information
383
 */
384
class SparkGetTypeInfoOperation extends GetTypeInfoOperation {
385
  /**
386
   * Run the type information operation
387
   */
388
  def runInternal(): Unit
389
}
390
```
391

392
**Usage Examples:**
393

394
```java
395
// Get all supported SQL types
396
OperationHandle typeInfoOp = cliService.getTypeInfo(sessionHandle);
397
TRowSet typeInfoResults = cliService.fetchResults(typeInfoOp);
398

399
// Process type information
400
// Columns: TYPE_NAME, DATA_TYPE, PRECISION, LITERAL_PREFIX, LITERAL_SUFFIX,
401
//          CREATE_PARAMS, NULLABLE, CASE_SENSITIVE, SEARCHABLE, UNSIGNED_ATTRIBUTE,
402
//          FIXED_PREC_SCALE, AUTO_INCREMENT, LOCAL_TYPE_NAME, MINIMUM_SCALE, MAXIMUM_SCALE,
403
//          SQL_DATA_TYPE, SQL_DATETIME_SUB, NUM_PREC_RADIX
404
for (TRow row : typeInfoResults.getRows()) {
405
    String typeName = row.getColVals().get(0).getStringVal().getValue();
406
    int dataType = row.getColVals().get(1).getI32Val().getValue();
407
    int precision = row.getColVals().get(2).getI32Val().getValue();
408
    String literalPrefix = row.getColVals().get(3).getStringVal().getValue();
409
    String literalSuffix = row.getColVals().get(4).getStringVal().getValue();
410
    boolean nullable = row.getColVals().get(6).getI16Val().getValue() != 0;
411
    boolean caseSensitive = row.getColVals().get(7).getBoolVal().getValue();
412
    
413
    System.out.println(String.format("Type: %s (JDBC type %d), precision=%d, nullable=%s, case_sensitive=%s", 
414
        typeName, dataType, precision, nullable, caseSensitive));
415
}
416
```
417

418
### Primary Key Operations
419

420
Retrieve primary key information for tables (HiveServer2 compatibility).
421

422
```java { .api }
423
/**
424
 * Get primary key information for a table
425
 * @param sessionHandle Session handle for the operation
426
 * @param catalog Catalog name
427
 * @param schema Schema name
428
 * @param table Table name
429
 * @return OperationHandle for fetching primary key results  
430
 * @throws HiveSQLException if operation fails
431
 */
432
OperationHandle getPrimaryKeys(SessionHandle sessionHandle, String catalog, String schema, String table) throws HiveSQLException;
433
```
434

435
### Cross Reference Operations
436

437
Retrieve foreign key relationships between tables.
438

439
```java { .api }
440
/**
441
 * Get cross reference information (foreign key relationships)
442
 * @param sessionHandle Session handle for the operation
443
 * @param primaryCatalog Primary table catalog
444
 * @param primarySchema Primary table schema  
445
 * @param primaryTable Primary table name
446
 * @param foreignCatalog Foreign table catalog
447
 * @param foreignSchema Foreign table schema
448
 * @param foreignTable Foreign table name
449
 * @return OperationHandle for fetching cross reference results
450
 * @throws HiveSQLException if operation fails
451
 */
452
OperationHandle getCrossReference(SessionHandle sessionHandle, 
453
    String primaryCatalog, String primarySchema, String primaryTable,
454
    String foreignCatalog, String foreignSchema, String foreignTable) throws HiveSQLException;
455
```
456

457
### Operation Management
458

459
Central management of all metadata operations through the operation manager.
460

461
```scala { .api }
462
/**
463
 * Operation manager for creating and managing metadata operations
464
 */
465
class SparkSQLOperationManager extends OperationManager {
466
  /**
467
   * Create a new catalog listing operation
468
   * @param parentSession Parent session for the operation
469
   * @return GetCatalogsOperation instance
470
   */
471
  def newGetCatalogsOperation(parentSession: HiveSession): GetCatalogsOperation
472
  
473
  /**
474
   * Create a new schema listing operation
475
   * @param parentSession Parent session for the operation
476
   * @param catalogName Catalog name filter
477
   * @param schemaName Schema name pattern
478
   * @return GetSchemasOperation instance
479
   */
480
  def newGetSchemasOperation(parentSession: HiveSession, catalogName: String, schemaName: String): GetSchemasOperation
481
  
482
  /**
483
   * Create a new table listing operation
484
   * @param parentSession Parent session for the operation
485
   * @param catalogName Catalog name filter
486
   * @param schemaName Schema name pattern
487
   * @param tableName Table name pattern
488
   * @param tableTypes List of table types to include
489
   * @return MetadataOperation instance
490
   */
491
  def newGetTablesOperation(parentSession: HiveSession, catalogName: String, schemaName: String, tableName: String, tableTypes: JList[String]): MetadataOperation
492
  
493
  /**
494
   * Create a new column listing operation
495
   * @param parentSession Parent session for the operation
496
   * @param catalogName Catalog name filter
497
   * @param schemaName Schema name pattern
498
   * @param tableName Table name pattern
499
   * @param columnName Column name pattern
500
   * @return GetColumnsOperation instance
501
   */
502
  def newGetColumnsOperation(parentSession: HiveSession, catalogName: String, schemaName: String, tableName: String, columnName: String): GetColumnsOperation
503
  
504
  /**
505
   * Create a new function listing operation
506
   * @param parentSession Parent session for the operation
507
   * @param catalogName Catalog name filter
508
   * @param schemaName Schema name pattern
509
   * @param functionName Function name pattern
510
   * @return GetFunctionsOperation instance
511
   */
512
  def newGetFunctionsOperation(parentSession: HiveSession, catalogName: String, schemaName: String, functionName: String): GetFunctionsOperation
513
  
514
  /**
515
   * Create a new type information operation
516
   * @param parentSession Parent session for the operation
517
   * @return GetTypeInfoOperation instance
518
   */
519
  def newGetTypeInfoOperation(parentSession: HiveSession): GetTypeInfoOperation
520
}
521
```
522

523
### Error Handling
524

525
Comprehensive error handling for metadata operations with specific error codes.
526

527
```java { .api }
528
// Common SQL states for metadata operation errors
529
public static final String INVALID_CATALOG_NAME = "HY000";
530
public static final String INVALID_SCHEMA_NAME = "3F000";
531
public static final String TABLE_NOT_FOUND = "42S02";
532
public static final String COLUMN_NOT_FOUND = "42S22";
533
public static final String FUNCTION_NOT_FOUND = "42000";
534
```
535

536
**Error Handling Examples:**
537

538
```java
539
try {
540
    OperationHandle tableOp = cliService.getTables(sessionHandle, "invalid_catalog", null, null, null);
541
    TRowSet results = cliService.fetchResults(tableOp);
542
} catch (HiveSQLException e) {
543
    switch (e.getSqlState()) {
544
        case "HY000":
545
            System.err.println("Invalid catalog name: " + e.getMessage());
546
            break;
547
        case "3F000":
548
            System.err.println("Invalid schema name: " + e.getMessage());
549
            break;
550
        default:
551
            System.err.println("Metadata operation failed: " + e.getMessage());
552
    }
553
}
554
```