TCLIService.thrift 30 KB

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