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