TCLIService.thrift 34 KB

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