TCLIService.thrift 27 KB

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