cli_service.thrift 29 KB

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