1// Licensed to the Apache Software Foundation (ASF) under one 2// or more contributor license agreements. See the NOTICE file 3// distributed with this work for additional information 4// regarding copyright ownership. The ASF licenses this file 5// to you under the Apache License, Version 2.0 (the 6// "License"); you may not use this file except in compliance 7// with the License. You may obtain a copy of the License at 8// 9// http://www.apache.org/licenses/LICENSE-2.0 10// 11// Unless required by applicable law or agreed to in writing, software 12// distributed under the License is distributed on an "AS IS" BASIS, 13// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14// See the License for the specific language governing permissions and 15// limitations under the License. 16 17// Coding Conventions for this file: 18// 19// Structs/Enums/Unions 20// * Struct, Enum, and Union names begin with a "T", 21// and use a capital letter for each new word, with no underscores. 22// * All fields should be declared as either optional or required. 23// 24// Functions 25// * Function names start with a capital letter and have a capital letter for 26// each new word, with no underscores. 27// * Each function should take exactly one parameter, named TFunctionNameReq, 28// and should return either void or TFunctionNameResp. This convention allows 29// incremental updates. 30// 31// Services 32// * Service names begin with the letter "T", use a capital letter for each 33// new word (with no underscores), and end with the word "Service". 34 35namespace java org.apache.hive.service.cli.thrift 36namespace cpp apache.hive.service.cli.thrift 37 38// List of protocol versions. A new token should be 39// added to the end of this list every time a change is made. 40enum TProtocolVersion { 41 HIVE_CLI_SERVICE_PROTOCOL_V1, 42 43 // V2 adds support for asynchronous execution 44 HIVE_CLI_SERVICE_PROTOCOL_V2 45 46 // V3 add varchar type, primitive type qualifiers 47 HIVE_CLI_SERVICE_PROTOCOL_V3 48 49 // V4 add decimal precision/scale, char type 50 HIVE_CLI_SERVICE_PROTOCOL_V4 51 52 // V5 adds error details when GetOperationStatus returns in error state 53 HIVE_CLI_SERVICE_PROTOCOL_V5 54 55 // V6 uses binary type for binary payload (was string) and uses columnar result set 56 HIVE_CLI_SERVICE_PROTOCOL_V6 57 58 // V7 adds support for delegation token based connection 59 HIVE_CLI_SERVICE_PROTOCOL_V7 60 61 // V8 adds support for interval types 62 HIVE_CLI_SERVICE_PROTOCOL_V8 63} 64 65enum TTypeId { 66 BOOLEAN_TYPE, 67 TINYINT_TYPE, 68 SMALLINT_TYPE, 69 INT_TYPE, 70 BIGINT_TYPE, 71 FLOAT_TYPE, 72 DOUBLE_TYPE, 73 STRING_TYPE, 74 TIMESTAMP_TYPE, 75 BINARY_TYPE, 76 ARRAY_TYPE, 77 MAP_TYPE, 78 STRUCT_TYPE, 79 UNION_TYPE, 80 USER_DEFINED_TYPE, 81 DECIMAL_TYPE, 82 NULL_TYPE, 83 DATE_TYPE, 84 VARCHAR_TYPE, 85 CHAR_TYPE, 86 INTERVAL_YEAR_MONTH_TYPE, 87 INTERVAL_DAY_TIME_TYPE 88} 89 90const set<TTypeId> PRIMITIVE_TYPES = [ 91 TTypeId.BOOLEAN_TYPE, 92 TTypeId.TINYINT_TYPE, 93 TTypeId.SMALLINT_TYPE, 94 TTypeId.INT_TYPE, 95 TTypeId.BIGINT_TYPE, 96 TTypeId.FLOAT_TYPE, 97 TTypeId.DOUBLE_TYPE, 98 TTypeId.STRING_TYPE, 99 TTypeId.TIMESTAMP_TYPE, 100 TTypeId.BINARY_TYPE, 101 TTypeId.DECIMAL_TYPE, 102 TTypeId.NULL_TYPE, 103 TTypeId.DATE_TYPE, 104 TTypeId.VARCHAR_TYPE, 105 TTypeId.CHAR_TYPE, 106 TTypeId.INTERVAL_YEAR_MONTH_TYPE, 107 TTypeId.INTERVAL_DAY_TIME_TYPE 108] 109 110const set<TTypeId> COMPLEX_TYPES = [ 111 TTypeId.ARRAY_TYPE 112 TTypeId.MAP_TYPE 113 TTypeId.STRUCT_TYPE 114 TTypeId.UNION_TYPE 115 TTypeId.USER_DEFINED_TYPE 116] 117 118const set<TTypeId> COLLECTION_TYPES = [ 119 TTypeId.ARRAY_TYPE 120 TTypeId.MAP_TYPE 121] 122 123const map<TTypeId,string> TYPE_NAMES = { 124 TTypeId.BOOLEAN_TYPE: "BOOLEAN", 125 TTypeId.TINYINT_TYPE: "TINYINT", 126 TTypeId.SMALLINT_TYPE: "SMALLINT", 127 TTypeId.INT_TYPE: "INT", 128 TTypeId.BIGINT_TYPE: "BIGINT", 129 TTypeId.FLOAT_TYPE: "FLOAT", 130 TTypeId.DOUBLE_TYPE: "DOUBLE", 131 TTypeId.STRING_TYPE: "STRING", 132 TTypeId.TIMESTAMP_TYPE: "TIMESTAMP", 133 TTypeId.BINARY_TYPE: "BINARY", 134 TTypeId.ARRAY_TYPE: "ARRAY", 135 TTypeId.MAP_TYPE: "MAP", 136 TTypeId.STRUCT_TYPE: "STRUCT", 137 TTypeId.UNION_TYPE: "UNIONTYPE", 138 TTypeId.DECIMAL_TYPE: "DECIMAL", 139 TTypeId.NULL_TYPE: "NULL" 140 TTypeId.DATE_TYPE: "DATE" 141 TTypeId.VARCHAR_TYPE: "VARCHAR" 142 TTypeId.CHAR_TYPE: "CHAR" 143 TTypeId.INTERVAL_YEAR_MONTH_TYPE: "INTERVAL_YEAR_MONTH" 144 TTypeId.INTERVAL_DAY_TIME_TYPE: "INTERVAL_DAY_TIME" 145} 146 147// Thrift does not support recursively defined types or forward declarations, 148// which makes it difficult to represent Hive's nested types. 149// To get around these limitations TTypeDesc employs a type list that maps 150// integer "pointers" to TTypeEntry objects. The following examples show 151// how different types are represented using this scheme: 152// 153// "INT": 154// TTypeDesc { 155// types = [ 156// TTypeEntry.primitive_entry { 157// type = INT_TYPE 158// } 159// ] 160// } 161// 162// "ARRAY<INT>": 163// TTypeDesc { 164// types = [ 165// TTypeEntry.array_entry { 166// object_type_ptr = 1 167// }, 168// TTypeEntry.primitive_entry { 169// type = INT_TYPE 170// } 171// ] 172// } 173// 174// "MAP<INT,STRING>": 175// TTypeDesc { 176// types = [ 177// TTypeEntry.map_entry { 178// key_type_ptr = 1 179// value_type_ptr = 2 180// }, 181// TTypeEntry.primitive_entry { 182// type = INT_TYPE 183// }, 184// TTypeEntry.primitive_entry { 185// type = STRING_TYPE 186// } 187// ] 188// } 189 190typedef i32 TTypeEntryPtr 191 192// Valid TTypeQualifiers key names 193const string CHARACTER_MAXIMUM_LENGTH = "characterMaximumLength" 194 195// Type qualifier key name for decimal 196const string PRECISION = "precision" 197const string SCALE = "scale" 198 199union TTypeQualifierValue { 200 1: optional i32 i32Value 201 2: optional string stringValue 202} 203 204// Type qualifiers for primitive type. 205struct TTypeQualifiers { 206 1: required map <string, TTypeQualifierValue> qualifiers 207} 208 209// Type entry for a primitive type. 210struct TPrimitiveTypeEntry { 211 // The primitive type token. This must satisfy the condition 212 // that type is in the PRIMITIVE_TYPES set. 213 1: required TTypeId type 214 2: optional TTypeQualifiers typeQualifiers 215} 216 217// Type entry for an ARRAY type. 218struct TArrayTypeEntry { 219 1: required TTypeEntryPtr objectTypePtr 220} 221 222// Type entry for a MAP type. 223struct TMapTypeEntry { 224 1: required TTypeEntryPtr keyTypePtr 225 2: required TTypeEntryPtr valueTypePtr 226} 227 228// Type entry for a STRUCT type. 229struct TStructTypeEntry { 230 1: required map<string, TTypeEntryPtr> nameToTypePtr 231} 232 233// Type entry for a UNIONTYPE type. 234struct TUnionTypeEntry { 235 1: required map<string, TTypeEntryPtr> nameToTypePtr 236} 237 238struct TUserDefinedTypeEntry { 239 // The fully qualified name of the class implementing this type. 240 1: required string typeClassName 241} 242 243// We use a union here since Thrift does not support inheritance. 244union TTypeEntry { 245 1: TPrimitiveTypeEntry primitiveEntry 246 2: TArrayTypeEntry arrayEntry 247 3: TMapTypeEntry mapEntry 248 4: TStructTypeEntry structEntry 249 5: TUnionTypeEntry unionEntry 250 6: TUserDefinedTypeEntry userDefinedTypeEntry 251} 252 253// Type descriptor for columns. 254struct TTypeDesc { 255 // The "top" type is always the first element of the list. 256 // If the top type is an ARRAY, MAP, STRUCT, or UNIONTYPE 257 // type, then subsequent elements represent nested types. 258 1: required list<TTypeEntry> types 259} 260 261// A result set column descriptor. 262struct TColumnDesc { 263 // The name of the column 264 1: required string columnName 265 266 // The type descriptor for this column 267 2: required TTypeDesc typeDesc 268 269 // The ordinal position of this column in the schema 270 3: required i32 position 271 272 4: optional string comment 273} 274 275// Metadata used to describe the schema (column names, types, comments) 276// of result sets. 277struct TTableSchema { 278 1: required list<TColumnDesc> columns 279} 280 281// A Boolean column value. 282struct TBoolValue { 283 // NULL if value is unset. 284 1: optional bool value 285} 286 287// A Byte column value. 288struct TByteValue { 289 // NULL if value is unset. 290 1: optional byte value 291} 292 293// A signed, 16 bit column value. 294struct TI16Value { 295 // NULL if value is unset 296 1: optional i16 value 297} 298 299// A signed, 32 bit column value 300struct TI32Value { 301 // NULL if value is unset 302 1: optional i32 value 303} 304 305// A signed 64 bit column value 306struct TI64Value { 307 // NULL if value is unset 308 1: optional i64 value 309} 310 311// A floating point 64 bit column value 312struct TDoubleValue { 313 // NULL if value is unset 314 1: optional double value 315} 316 317struct TStringValue { 318 // NULL if value is unset 319 1: optional string value 320} 321 322// A single column value in a result set. 323// Note that Hive's type system is richer than Thrift's, 324// so in some cases we have to map multiple Hive types 325// to the same Thrift type. On the client-side this is 326// disambiguated by looking at the Schema of the 327// result set. 328union TColumnValue { 329 1: TBoolValue boolVal // BOOLEAN 330 2: TByteValue byteVal // TINYINT 331 3: TI16Value i16Val // SMALLINT 332 4: TI32Value i32Val // INT 333 5: TI64Value i64Val // BIGINT, TIMESTAMP 334 6: TDoubleValue doubleVal // FLOAT, DOUBLE 335 7: TStringValue stringVal // STRING, LIST, MAP, STRUCT, UNIONTYPE, BINARY, DECIMAL, NULL, INTERVAL_YEAR_MONTH, INTERVAL_DAY_TIME 336} 337 338// Represents a row in a rowset. 339struct TRow { 340 1: required list<TColumnValue> colVals 341} 342 343struct TBoolColumn { 344 1: required list<bool> values 345 2: required binary nulls 346} 347 348struct TByteColumn { 349 1: required list<byte> values 350 2: required binary nulls 351} 352 353struct TI16Column { 354 1: required list<i16> values 355 2: required binary nulls 356} 357 358struct TI32Column { 359 1: required list<i32> values 360 2: required binary nulls 361} 362 363struct TI64Column { 364 1: required list<i64> values 365 2: required binary nulls 366} 367 368struct TDoubleColumn { 369 1: required list<double> values 370 2: required binary nulls 371} 372 373struct TStringColumn { 374 1: required list<string> values 375 2: required binary nulls 376} 377 378struct TBinaryColumn { 379 1: required list<binary> values 380 2: required binary nulls 381} 382 383// Note that Hive's type system is richer than Thrift's, 384// so in some cases we have to map multiple Hive types 385// to the same Thrift type. On the client-side this is 386// disambiguated by looking at the Schema of the 387// result set. 388union TColumn { 389 1: TBoolColumn boolVal // BOOLEAN 390 2: TByteColumn byteVal // TINYINT 391 3: TI16Column i16Val // SMALLINT 392 4: TI32Column i32Val // INT 393 5: TI64Column i64Val // BIGINT, TIMESTAMP 394 6: TDoubleColumn doubleVal // FLOAT, DOUBLE 395 7: TStringColumn stringVal // STRING, LIST, MAP, STRUCT, UNIONTYPE, DECIMAL, NULL 396 8: TBinaryColumn binaryVal // BINARY 397} 398 399// Represents a rowset 400struct TRowSet { 401 // The starting row offset of this rowset. 402 1: required i64 startRowOffset 403 2: required list<TRow> rows 404 3: optional list<TColumn> columns 405} 406 407// The return status code contained in each response. 408enum TStatusCode { 409 SUCCESS_STATUS, 410 SUCCESS_WITH_INFO_STATUS, 411 STILL_EXECUTING_STATUS, 412 ERROR_STATUS, 413 INVALID_HANDLE_STATUS 414} 415 416// The return status of a remote request 417struct TStatus { 418 1: required TStatusCode statusCode 419 420 // If status is SUCCESS_WITH_INFO, info_msgs may be populated with 421 // additional diagnostic information. 422 2: optional list<string> infoMessages 423 424 // If status is ERROR, then the following fields may be set 425 3: optional string sqlState // as defined in the ISO/IEF CLI specification 426 4: optional i32 errorCode // internal error code 427 5: optional string errorMessage 428} 429 430// The state of an operation (i.e. a query or other 431// asynchronous operation that generates a result set) 432// on the server. 433enum TOperationState { 434 // The operation has been initialized 435 INITIALIZED_STATE, 436 437 // The operation is running. In this state the result 438 // set is not available. 439 RUNNING_STATE, 440 441 // The operation has completed. When an operation is in 442 // this state its result set may be fetched. 443 FINISHED_STATE, 444 445 // The operation was canceled by a client 446 CANCELED_STATE, 447 448 // The operation was closed by a client 449 CLOSED_STATE, 450 451 // The operation failed due to an error 452 ERROR_STATE, 453 454 // The operation is in an unrecognized state 455 UKNOWN_STATE, 456 457 // The operation is in an pending state 458 PENDING_STATE, 459} 460 461// A string identifier. This is interpreted literally. 462typedef string TIdentifier 463 464// A search pattern. 465// 466// Valid search pattern characters: 467// '_': Any single character. 468// '%': Any sequence of zero or more characters. 469// '\': Escape character used to include special characters, 470// e.g. '_', '%', '\'. If a '\' precedes a non-special 471// character it has no special meaning and is interpreted 472// literally. 473typedef string TPattern 474 475 476// A search pattern or identifier. Used as input 477// parameter for many of the catalog functions. 478typedef string TPatternOrIdentifier 479 480struct THandleIdentifier { 481 // 16 byte globally unique identifier 482 // This is the public ID of the handle and 483 // can be used for reporting. 484 1: required binary guid, 485 486 // 16 byte secret generated by the server 487 // and used to verify that the handle is not 488 // being hijacked by another user. 489 2: required binary secret, 490} 491 492// Client-side handle to persistent 493// session information on the server-side. 494struct TSessionHandle { 495 1: required THandleIdentifier sessionId 496} 497 498// The subtype of an OperationHandle. 499enum TOperationType { 500 EXECUTE_STATEMENT, 501 GET_TYPE_INFO, 502 GET_CATALOGS, 503 GET_SCHEMAS, 504 GET_TABLES, 505 GET_TABLE_TYPES, 506 GET_COLUMNS, 507 GET_FUNCTIONS, 508 UNKNOWN, 509} 510 511// Client-side reference to a task running 512// asynchronously on the server. 513struct TOperationHandle { 514 1: required THandleIdentifier operationId 515 2: required TOperationType operationType 516 517 // If hasResultSet = TRUE, then this operation 518 // generates a result set that can be fetched. 519 // Note that the result set may be empty. 520 // 521 // If hasResultSet = FALSE, then this operation 522 // does not generate a result set, and calling 523 // GetResultSetMetadata or FetchResults against 524 // this OperationHandle will generate an error. 525 3: required bool hasResultSet 526 527 // For operations that don't generate result sets, 528 // modifiedRowCount is either: 529 // 530 // 1) The number of rows that were modified by 531 // the DML operation (e.g. number of rows inserted, 532 // number of rows deleted, etc). 533 // 534 // 2) 0 for operations that don't modify or add rows. 535 // 536 // 3) < 0 if the operation is capable of modifiying rows, 537 // but Hive is unable to determine how many rows were 538 // modified. For example, Hive's LOAD DATA command 539 // doesn't generate row count information because 540 // Hive doesn't inspect the data as it is loaded. 541 // 542 // modifiedRowCount is unset if the operation generates 543 // a result set. 544 4: optional double modifiedRowCount 545} 546 547 548// OpenSession() 549// 550// Open a session (connection) on the server against 551// which operations may be executed. 552struct TOpenSessionReq { 553 // The version of the HiveServer2 protocol that the client is using. 554 1: required TProtocolVersion client_protocol = TProtocolVersion.HIVE_CLI_SERVICE_PROTOCOL_V8 555 556 // Username and password for authentication. 557 // Depending on the authentication scheme being used, 558 // this information may instead be provided by a lower 559 // protocol layer, in which case these fields may be 560 // left unset. 561 2: optional string username 562 3: optional string password 563 564 // Configuration overlay which is applied when the session is 565 // first created. 566 4: optional map<string, string> configuration 567} 568 569struct TOpenSessionResp { 570 1: required TStatus status 571 572 // The protocol version that the server is using. 573 2: required TProtocolVersion serverProtocolVersion = TProtocolVersion.HIVE_CLI_SERVICE_PROTOCOL_V8 574 575 // Session Handle 576 3: optional TSessionHandle sessionHandle 577 578 // The configuration settings for this session. 579 4: optional map<string, string> configuration 580} 581 582 583// CloseSession() 584// 585// Closes the specified session and frees any resources 586// currently allocated to that session. Any open 587// operations in that session will be canceled. 588struct TCloseSessionReq { 589 1: required TSessionHandle sessionHandle 590} 591 592struct TCloseSessionResp { 593 1: required TStatus status 594} 595 596 597 598enum TGetInfoType { 599 CLI_MAX_DRIVER_CONNECTIONS = 0, 600 CLI_MAX_CONCURRENT_ACTIVITIES = 1, 601 CLI_DATA_SOURCE_NAME = 2, 602 CLI_FETCH_DIRECTION = 8, 603 CLI_SERVER_NAME = 13, 604 CLI_SEARCH_PATTERN_ESCAPE = 14, 605 CLI_DBMS_NAME = 17, 606 CLI_DBMS_VER = 18, 607 CLI_ACCESSIBLE_TABLES = 19, 608 CLI_ACCESSIBLE_PROCEDURES = 20, 609 CLI_CURSOR_COMMIT_BEHAVIOR = 23, 610 CLI_DATA_SOURCE_READ_ONLY = 25, 611 CLI_DEFAULT_TXN_ISOLATION = 26, 612 CLI_IDENTIFIER_CASE = 28, 613 CLI_IDENTIFIER_QUOTE_CHAR = 29, 614 CLI_MAX_COLUMN_NAME_LEN = 30, 615 CLI_MAX_CURSOR_NAME_LEN = 31, 616 CLI_MAX_SCHEMA_NAME_LEN = 32, 617 CLI_MAX_CATALOG_NAME_LEN = 34, 618 CLI_MAX_TABLE_NAME_LEN = 35, 619 CLI_SCROLL_CONCURRENCY = 43, 620 CLI_TXN_CAPABLE = 46, 621 CLI_USER_NAME = 47, 622 CLI_TXN_ISOLATION_OPTION = 72, 623 CLI_INTEGRITY = 73, 624 CLI_GETDATA_EXTENSIONS = 81, 625 CLI_NULL_COLLATION = 85, 626 CLI_ALTER_TABLE = 86, 627 CLI_ORDER_BY_COLUMNS_IN_SELECT = 90, 628 CLI_SPECIAL_CHARACTERS = 94, 629 CLI_MAX_COLUMNS_IN_GROUP_BY = 97, 630 CLI_MAX_COLUMNS_IN_INDEX = 98, 631 CLI_MAX_COLUMNS_IN_ORDER_BY = 99, 632 CLI_MAX_COLUMNS_IN_SELECT = 100, 633 CLI_MAX_COLUMNS_IN_TABLE = 101, 634 CLI_MAX_INDEX_SIZE = 102, 635 CLI_MAX_ROW_SIZE = 104, 636 CLI_MAX_STATEMENT_LEN = 105, 637 CLI_MAX_TABLES_IN_SELECT = 106, 638 CLI_MAX_USER_NAME_LEN = 107, 639 CLI_OJ_CAPABILITIES = 115, 640 641 CLI_XOPEN_CLI_YEAR = 10000, 642 CLI_CURSOR_SENSITIVITY = 10001, 643 CLI_DESCRIBE_PARAMETER = 10002, 644 CLI_CATALOG_NAME = 10003, 645 CLI_COLLATION_SEQ = 10004, 646 CLI_MAX_IDENTIFIER_LEN = 10005, 647} 648 649union TGetInfoValue { 650 1: string stringValue 651 2: i16 smallIntValue 652 3: i32 integerBitmask 653 4: i32 integerFlag 654 5: i32 binaryValue 655 6: i64 lenValue 656} 657 658// GetInfo() 659// 660// This function is based on ODBC's CLIGetInfo() function. 661// The function returns general information about the data source 662// using the same keys as ODBC. 663struct TGetInfoReq { 664 // The session to run this request against 665 1: required TSessionHandle sessionHandle 666 667 2: required TGetInfoType infoType 668} 669 670struct TGetInfoResp { 671 1: required TStatus status 672 673 2: required TGetInfoValue infoValue 674} 675 676 677// ExecuteStatement() 678// 679// Execute a statement. 680// The returned OperationHandle can be used to check on the 681// status of the statement, and to fetch results once the 682// statement has finished executing. 683struct TExecuteStatementReq { 684 // The session to execute the statement against 685 1: required TSessionHandle sessionHandle 686 687 // The statement to be executed (DML, DDL, SET, etc) 688 2: required string statement 689 690 // Configuration properties that are overlayed on top of the 691 // the existing session configuration before this statement 692 // is executed. These properties apply to this statement 693 // only and will not affect the subsequent state of the Session. 694 3: optional map<string, string> confOverlay 695 696 // Execute asynchronously when runAsync is true 697 4: optional bool runAsync = false 698} 699 700struct TExecuteStatementResp { 701 1: required TStatus status 702 2: optional TOperationHandle operationHandle 703} 704 705// GetTypeInfo() 706// 707// Get information about types supported by the HiveServer instance. 708// The information is returned as a result set which can be fetched 709// using the OperationHandle provided in the response. 710// 711// Refer to the documentation for ODBC's CLIGetTypeInfo function for 712// the format of the result set. 713struct TGetTypeInfoReq { 714 // The session to run this request against. 715 1: required TSessionHandle sessionHandle 716} 717 718struct TGetTypeInfoResp { 719 1: required TStatus status 720 2: optional TOperationHandle operationHandle 721} 722 723 724// GetCatalogs() 725// 726// Returns the list of catalogs (databases) 727// Results are ordered by TABLE_CATALOG 728// 729// Resultset columns : 730// col1 731// name: TABLE_CAT 732// type: STRING 733// desc: Catalog name. NULL if not applicable. 734// 735struct TGetCatalogsReq { 736 // Session to run this request against 737 1: required TSessionHandle sessionHandle 738} 739 740struct TGetCatalogsResp { 741 1: required TStatus status 742 2: optional TOperationHandle operationHandle 743} 744 745 746// GetSchemas() 747// 748// Retrieves the schema names available in this database. 749// The results are ordered by TABLE_CATALOG and TABLE_SCHEM. 750// col1 751// name: TABLE_SCHEM 752// type: STRING 753// desc: schema name 754// col2 755// name: TABLE_CATALOG 756// type: STRING 757// desc: catalog name 758struct TGetSchemasReq { 759 // Session to run this request against 760 1: required TSessionHandle sessionHandle 761 762 // Name of the catalog. Must not contain a search pattern. 763 2: optional TIdentifier catalogName 764 765 // schema name or pattern 766 3: optional TPatternOrIdentifier schemaName 767} 768 769struct TGetSchemasResp { 770 1: required TStatus status 771 2: optional TOperationHandle operationHandle 772} 773 774 775// GetTables() 776// 777// Returns a list of tables with catalog, schema, and table 778// type information. The information is returned as a result 779// set which can be fetched using the OperationHandle 780// provided in the response. 781// Results are ordered by TABLE_TYPE, TABLE_CAT, TABLE_SCHEM, and TABLE_NAME 782// 783// Result Set Columns: 784// 785// col1 786// name: TABLE_CAT 787// type: STRING 788// desc: Catalog name. NULL if not applicable. 789// 790// col2 791// name: TABLE_SCHEM 792// type: STRING 793// desc: Schema name. 794// 795// col3 796// name: TABLE_NAME 797// type: STRING 798// desc: Table name. 799// 800// col4 801// name: TABLE_TYPE 802// type: STRING 803// desc: The table type, e.g. "TABLE", "VIEW", etc. 804// 805// col5 806// name: REMARKS 807// type: STRING 808// desc: Comments about the table 809// 810struct TGetTablesReq { 811 // Session to run this request against 812 1: required TSessionHandle sessionHandle 813 814 // Name of the catalog or a search pattern. 815 2: optional TPatternOrIdentifier catalogName 816 817 // Name of the schema or a search pattern. 818 3: optional TPatternOrIdentifier schemaName 819 820 // Name of the table or a search pattern. 821 4: optional TPatternOrIdentifier tableName 822 823 // List of table types to match 824 // e.g. "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", 825 // "LOCAL TEMPORARY", "ALIAS", "SYNONYM", etc. 826 5: optional list<string> tableTypes 827} 828 829struct TGetTablesResp { 830 1: required TStatus status 831 2: optional TOperationHandle operationHandle 832} 833 834 835// GetTableTypes() 836// 837// Returns the table types available in this database. 838// The results are ordered by table type. 839// 840// col1 841// name: TABLE_TYPE 842// type: STRING 843// desc: Table type name. 844struct TGetTableTypesReq { 845 // Session to run this request against 846 1: required TSessionHandle sessionHandle 847} 848 849struct TGetTableTypesResp { 850 1: required TStatus status 851 2: optional TOperationHandle operationHandle 852} 853 854 855// GetColumns() 856// 857// Returns a list of columns in the specified tables. 858// The information is returned as a result set which can be fetched 859// using the OperationHandle provided in the response. 860// Results are ordered by TABLE_CAT, TABLE_SCHEM, TABLE_NAME, 861// and ORDINAL_POSITION. 862// 863// Result Set Columns are the same as those for the ODBC CLIColumns 864// function. 865// 866struct TGetColumnsReq { 867 // Session to run this request against 868 1: required TSessionHandle sessionHandle 869 870 // Name of the catalog. Must not contain a search pattern. 871 2: optional TIdentifier catalogName 872 873 // Schema name or search pattern 874 3: optional TPatternOrIdentifier schemaName 875 876 // Table name or search pattern 877 4: optional TPatternOrIdentifier tableName 878 879 // Column name or search pattern 880 5: optional TPatternOrIdentifier columnName 881} 882 883struct TGetColumnsResp { 884 1: required TStatus status 885 2: optional TOperationHandle operationHandle 886} 887 888 889// GetFunctions() 890// 891// Returns a list of functions supported by the data source. The 892// behavior of this function matches 893// java.sql.DatabaseMetaData.getFunctions() both in terms of 894// inputs and outputs. 895// 896// Result Set Columns: 897// 898// col1 899// name: FUNCTION_CAT 900// type: STRING 901// desc: Function catalog (may be null) 902// 903// col2 904// name: FUNCTION_SCHEM 905// type: STRING 906// desc: Function schema (may be null) 907// 908// col3 909// name: FUNCTION_NAME 910// type: STRING 911// desc: Function name. This is the name used to invoke the function. 912// 913// col4 914// name: REMARKS 915// type: STRING 916// desc: Explanatory comment on the function. 917// 918// col5 919// name: FUNCTION_TYPE 920// type: SMALLINT 921// desc: Kind of function. One of: 922// * functionResultUnknown - Cannot determine if a return value or a table 923// will be returned. 924// * functionNoTable - Does not a return a table. 925// * functionReturnsTable - Returns a table. 926// 927// col6 928// name: SPECIFIC_NAME 929// type: STRING 930// desc: The name which uniquely identifies this function within its schema. 931// In this case this is the fully qualified class name of the class 932// that implements this function. 933// 934struct TGetFunctionsReq { 935 // Session to run this request against 936 1: required TSessionHandle sessionHandle 937 938 // A catalog name; must match the catalog name as it is stored in the 939 // database; "" retrieves those without a catalog; null means 940 // that the catalog name should not be used to narrow the search. 941 2: optional TIdentifier catalogName 942 943 // A schema name pattern; must match the schema name as it is stored 944 // in the database; "" retrieves those without a schema; null means 945 // that the schema name should not be used to narrow the search. 946 3: optional TPatternOrIdentifier schemaName 947 948 // A function name pattern; must match the function name as it is stored 949 // in the database. 950 4: required TPatternOrIdentifier functionName 951} 952 953struct TGetFunctionsResp { 954 1: required TStatus status 955 2: optional TOperationHandle operationHandle 956} 957 958 959// GetOperationStatus() 960// 961// Get the status of an operation running on the server. 962struct TGetOperationStatusReq { 963 // Session to run this request against 964 1: required TOperationHandle operationHandle 965} 966 967struct TGetOperationStatusResp { 968 1: required TStatus status 969 2: optional TOperationState operationState 970 971 // If operationState is ERROR_STATE, then the following fields may be set 972 // sqlState as defined in the ISO/IEF CLI specification 973 3: optional string sqlState 974 975 // Internal error code 976 4: optional i32 errorCode 977 978 // Error message 979 5: optional string errorMessage 980} 981 982 983// CancelOperation() 984// 985// Cancels processing on the specified operation handle and 986// frees any resources which were allocated. 987struct TCancelOperationReq { 988 // Operation to cancel 989 1: required TOperationHandle operationHandle 990} 991 992struct TCancelOperationResp { 993 1: required TStatus status 994} 995 996 997// CloseOperation() 998// 999// Given an operation in the FINISHED, CANCELED, 1000// or ERROR states, CloseOperation() will free 1001// all of the resources which were allocated on 1002// the server to service the operation. 1003struct TCloseOperationReq { 1004 1: required TOperationHandle operationHandle 1005} 1006 1007struct TCloseOperationResp { 1008 1: required TStatus status 1009} 1010 1011 1012// GetResultSetMetadata() 1013// 1014// Retrieves schema information for the specified operation 1015struct TGetResultSetMetadataReq { 1016 // Operation for which to fetch result set schema information 1017 1: required TOperationHandle operationHandle 1018} 1019 1020struct TGetResultSetMetadataResp { 1021 1: required TStatus status 1022 2: optional TTableSchema schema 1023} 1024 1025 1026enum TFetchOrientation { 1027 // Get the next rowset. The fetch offset is ignored. 1028 FETCH_NEXT, 1029 1030 // Get the previous rowset. The fetch offset is ignored. 1031 // NOT SUPPORTED 1032 FETCH_PRIOR, 1033 1034 // Return the rowset at the given fetch offset relative 1035 // to the current rowset. 1036 // NOT SUPPORTED 1037 FETCH_RELATIVE, 1038 1039 // Return the rowset at the specified fetch offset. 1040 // NOT SUPPORTED 1041 FETCH_ABSOLUTE, 1042 1043 // Get the first rowset in the result set. 1044 FETCH_FIRST, 1045 1046 // Get the last rowset in the result set. 1047 // NOT SUPPORTED 1048 FETCH_LAST 1049} 1050 1051// FetchResults() 1052// 1053// Fetch rows from the server corresponding to 1054// a particular OperationHandle. 1055struct TFetchResultsReq { 1056 // Operation from which to fetch results. 1057 1: required TOperationHandle operationHandle 1058 1059 // The fetch orientation. For V1 this must be either 1060 // FETCH_NEXT or FETCH_FIRST. Defaults to FETCH_NEXT. 1061 2: required TFetchOrientation orientation = TFetchOrientation.FETCH_NEXT 1062 1063 // Max number of rows that should be returned in 1064 // the rowset. 1065 3: required i64 maxRows 1066 1067 // The type of a fetch results request. 0 represents Query output. 1 represents Log 1068 4: optional i16 fetchType = 0 1069} 1070 1071struct TFetchResultsResp { 1072 1: required TStatus status 1073 1074 // TRUE if there are more rows left to fetch from the server. 1075 2: optional bool hasMoreRows 1076 1077 // The rowset. This is optional so that we have the 1078 // option in the future of adding alternate formats for 1079 // representing result set data, e.g. delimited strings, 1080 // binary encoded, etc. 1081 3: optional TRowSet results 1082} 1083 1084// GetDelegationToken() 1085// Retrieve delegation token for the current user 1086struct TGetDelegationTokenReq { 1087 // session handle 1088 1: required TSessionHandle sessionHandle 1089 1090 // userid for the proxy user 1091 2: required string owner 1092 1093 // designated renewer userid 1094 3: required string renewer 1095} 1096 1097struct TGetDelegationTokenResp { 1098 // status of the request 1099 1: required TStatus status 1100 1101 // delegation token string 1102 2: optional string delegationToken 1103} 1104 1105// CancelDelegationToken() 1106// Cancel the given delegation token 1107struct TCancelDelegationTokenReq { 1108 // session handle 1109 1: required TSessionHandle sessionHandle 1110 1111 // delegation token to cancel 1112 2: required string delegationToken 1113} 1114 1115struct TCancelDelegationTokenResp { 1116 // status of the request 1117 1: required TStatus status 1118} 1119 1120// RenewDelegationToken() 1121// Renew the given delegation token 1122struct TRenewDelegationTokenReq { 1123 // session handle 1124 1: required TSessionHandle sessionHandle 1125 1126 // delegation token to renew 1127 2: required string delegationToken 1128} 1129 1130struct TRenewDelegationTokenResp { 1131 // status of the request 1132 1: required TStatus status 1133} 1134 1135service TCLIService { 1136 1137 TOpenSessionResp OpenSession(1:TOpenSessionReq req); 1138 1139 TCloseSessionResp CloseSession(1:TCloseSessionReq req); 1140 1141 TGetInfoResp GetInfo(1:TGetInfoReq req); 1142 1143 TExecuteStatementResp ExecuteStatement(1:TExecuteStatementReq req); 1144 1145 TGetTypeInfoResp GetTypeInfo(1:TGetTypeInfoReq req); 1146 1147 TGetCatalogsResp GetCatalogs(1:TGetCatalogsReq req); 1148 1149 TGetSchemasResp GetSchemas(1:TGetSchemasReq req); 1150 1151 TGetTablesResp GetTables(1:TGetTablesReq req); 1152 1153 TGetTableTypesResp GetTableTypes(1:TGetTableTypesReq req); 1154 1155 TGetColumnsResp GetColumns(1:TGetColumnsReq req); 1156 1157 TGetFunctionsResp GetFunctions(1:TGetFunctionsReq req); 1158 1159 TGetOperationStatusResp GetOperationStatus(1:TGetOperationStatusReq req); 1160 1161 TCancelOperationResp CancelOperation(1:TCancelOperationReq req); 1162 1163 TCloseOperationResp CloseOperation(1:TCloseOperationReq req); 1164 1165 TGetResultSetMetadataResp GetResultSetMetadata(1:TGetResultSetMetadataReq req); 1166 1167 TFetchResultsResp FetchResults(1:TFetchResultsReq req); 1168 1169 TGetDelegationTokenResp GetDelegationToken(1:TGetDelegationTokenReq req); 1170 1171 TCancelDelegationTokenResp CancelDelegationToken(1:TCancelDelegationTokenReq req); 1172 1173 TRenewDelegationTokenResp RenewDelegationToken(1:TRenewDelegationTokenReq req); 1174} 1175