cli_service.thrift 26 KB

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