ImpalaService.thrift 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264
  1. // Copyright 2012 Cloudera Inc.
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. namespace cpp impala
  15. namespace java com.cloudera.impala.thrift
  16. include "ExecStats.thrift"
  17. include "Status.thrift"
  18. include "Types.thrift"
  19. include "beeswax.thrift"
  20. include "TCLIService.thrift"
  21. // ImpalaService accepts query execution options through beeswax.Query.configuration in
  22. // key:value form. For example, the list of strings could be:
  23. // "num_nodes:1", "abort_on_error:false"
  24. // The valid keys are listed in this enum. They map to TQueryOptions.
  25. // Note: If you add an option or change the default, you also need to update:
  26. // - ImpalaInternalService.thrift: TQueryOptions
  27. // - ImpaladClientExecutor.getBeeswaxQueryConfigurations()
  28. // - SetQueryOption()
  29. // - TQueryOptionsToMap()
  30. enum TImpalaQueryOptions {
  31. // if true, abort execution on the first error
  32. ABORT_ON_ERROR,
  33. // maximum # of errors to be reported; Unspecified or 0 indicates backend default
  34. MAX_ERRORS,
  35. // if true, disable llvm codegen
  36. DISABLE_CODEGEN,
  37. // batch size to be used by backend; Unspecified or a size of 0 indicates backend
  38. // default
  39. BATCH_SIZE,
  40. // a per-machine approximate limit on the memory consumption of this query;
  41. // unspecified or a limit of 0 means no limit;
  42. // otherwise specified either as:
  43. // a) an int (= number of bytes);
  44. // b) a float followed by "M" (MB) or "G" (GB)
  45. MEM_LIMIT,
  46. // specifies the degree of parallelism with which to execute the query;
  47. // 1: single-node execution
  48. // NUM_NODES_ALL: executes on all nodes that contain relevant data
  49. // NUM_NODES_ALL_RACKS: executes on one node per rack that holds relevant data
  50. // > 1: executes on at most that many nodes at any point in time (ie, there can be
  51. // more nodes than numNodes with plan fragments for this query, but at most
  52. // numNodes would be active at any point in time)
  53. // Constants (NUM_NODES_ALL, NUM_NODES_ALL_RACKS) are defined in JavaConstants.thrift.
  54. NUM_NODES,
  55. // maximum length of the scan range; only applicable to HDFS scan range; Unspecified or
  56. // a length of 0 indicates backend default;
  57. MAX_SCAN_RANGE_LENGTH,
  58. // Maximum number of io buffers (per disk)
  59. MAX_IO_BUFFERS,
  60. // Number of scanner threads.
  61. NUM_SCANNER_THREADS,
  62. // If true, Impala will try to execute on file formats that are not fully supported yet
  63. ALLOW_UNSUPPORTED_FORMATS,
  64. // if set and > -1, specifies the default limit applied to a top-level SELECT statement
  65. // with an ORDER BY but without a LIMIT clause (ie, if the SELECT statement also has
  66. // a LIMIT clause, this default is ignored)
  67. DEFAULT_ORDER_BY_LIMIT,
  68. // DEBUG ONLY:
  69. // If set to
  70. // "[<backend number>:]<node id>:<TExecNodePhase>:<TDebugAction>",
  71. // the exec node with the given id will perform the specified action in the given
  72. // phase. If the optional backend number (starting from 0) is specified, only that
  73. // backend instance will perform the debug action, otherwise all backends will behave
  74. // in that way.
  75. // If the string doesn't have the required format or if any of its components is
  76. // invalid, the option is ignored.
  77. DEBUG_ACTION,
  78. // If true, raise an error when the DEFAULT_ORDER_BY_LIMIT has been reached.
  79. ABORT_ON_DEFAULT_LIMIT_EXCEEDED,
  80. // Compression codec when inserting into tables.
  81. // Valid values are "snappy", "gzip", "bzip2" and "none"
  82. // Leave blank to use default.
  83. COMPRESSION_CODEC,
  84. // Mode for compressing sequence files; either BLOCK, RECORD, or DEFAULT
  85. SEQ_COMPRESSION_MODE,
  86. // HBase scan query option. If set and > 0, HBASE_CACHING is the value for
  87. // "hbase.client.Scan.setCaching()" when querying HBase table. Otherwise, use backend
  88. // default.
  89. // If the value is too high, then the hbase region server will have a hard time (GC
  90. // pressure and long response times). If the value is too small, then there will be
  91. // extra trips to the hbase region server.
  92. HBASE_CACHING,
  93. // HBase scan query option. If set, HBase scan will always set
  94. // "hbase.client.setCacheBlocks" to CACHE_BLOCKS. Default is false.
  95. // If the table is large and the query is doing big scan, set it to false to
  96. // avoid polluting the cache in the hbase region server.
  97. // If the table is small and the table is used several time, set it to true to improve
  98. // performance.
  99. HBASE_CACHE_BLOCKS,
  100. // Target file size for inserts into parquet tables. 0 uses the default.
  101. PARQUET_FILE_SIZE,
  102. // Level of detail for explain output (NORMAL, VERBOSE).
  103. EXPLAIN_LEVEL,
  104. // If true, waits for the result of all catalog operations to be processed by all
  105. // active impalad in the cluster before completing.
  106. SYNC_DDL,
  107. // Request pool this request should be submitted to. If not set
  108. // the pool is determined based on the user.
  109. REQUEST_POOL,
  110. // Per-host virtual CPU cores required for query (only relevant with RM).
  111. V_CPU_CORES,
  112. // Max time in milliseconds the resource broker should wait for
  113. // a resource request to be granted by Llama/Yarn (only relevant with RM).
  114. RESERVATION_REQUEST_TIMEOUT,
  115. // if true, disables cached reads
  116. DISABLE_CACHED_READS,
  117. // Temporary testing flag
  118. DISABLE_OUTERMOST_TOPN,
  119. // Size of initial memory reservation when RM is enabled
  120. RM_INITIAL_MEM,
  121. // Time, in s, before a query will be timed out if it is inactive. May not exceed
  122. // --idle_query_timeout if that flag > 0.
  123. QUERY_TIMEOUT_S
  124. // Test hook for spill to disk operators
  125. MAX_BLOCK_MGR_MEMORY,
  126. // Transforms all count(distinct) aggregations into NDV()
  127. APPX_COUNT_DISTINCT
  128. // If true, allows Impala to internally disable spilling for potentially
  129. // disastrous query plans. Impala will excercise this option if a query
  130. // has no plan hints, and at least one table is missing relevant stats.
  131. DISABLE_UNSAFE_SPILLS
  132. // If the number of rows that are processed for a single query is below the
  133. // threshold, it will be executed on the coordinator only with codegen disabled
  134. EXEC_SINGLE_NODE_ROWS_THRESHOLD
  135. }
  136. // The summary of an insert.
  137. struct TInsertResult {
  138. // Number of appended rows per modified partition. Only applies to HDFS tables.
  139. // The keys represent partitions to create, coded as k1=v1/k2=v2/k3=v3..., with the
  140. // root in an unpartitioned table being the empty string.
  141. 1: required map<string, i64> rows_appended
  142. }
  143. // Response from a call to PingImpalaService
  144. struct TPingImpalaServiceResp {
  145. // The Impala service's version string.
  146. 1: string version
  147. }
  148. // Parameters for a ResetTable request which will invalidate a table's metadata.
  149. // DEPRECATED.
  150. struct TResetTableReq {
  151. // Name of the table's parent database.
  152. 1: required string db_name
  153. // Name of the table.
  154. 2: required string table_name
  155. }
  156. // For all rpc that return a TStatus as part of their result type,
  157. // if the status_code field is set to anything other than OK, the contents
  158. // of the remainder of the result type is undefined (typically not set)
  159. service ImpalaService extends beeswax.BeeswaxService {
  160. // Cancel execution of query. Returns RUNTIME_ERROR if query_id
  161. // unknown.
  162. // This terminates all threads running on behalf of this query at
  163. // all nodes that were involved in the execution.
  164. // Throws BeeswaxException if the query handle is invalid (this doesn't
  165. // necessarily indicate an error: the query might have finished).
  166. Status.TStatus Cancel(1:beeswax.QueryHandle query_id)
  167. throws(1:beeswax.BeeswaxException error);
  168. // Invalidates all catalog metadata, forcing a reload
  169. // DEPRECATED; execute query "invalidate metadata" to refresh metadata
  170. Status.TStatus ResetCatalog();
  171. // Invalidates a specific table's catalog metadata, forcing a reload on the next access
  172. // DEPRECATED; execute query "refresh <table>" to refresh metadata
  173. Status.TStatus ResetTable(1:TResetTableReq request)
  174. // Returns the runtime profile string for the given query handle.
  175. string GetRuntimeProfile(1:beeswax.QueryHandle query_id)
  176. throws(1:beeswax.BeeswaxException error);
  177. // Closes the query handle and return the result summary of the insert.
  178. TInsertResult CloseInsert(1:beeswax.QueryHandle handle)
  179. throws(1:beeswax.QueryNotFoundException error, 2:beeswax.BeeswaxException error2);
  180. // Client calls this RPC to verify that the server is an ImpalaService. Returns the
  181. // server version.
  182. TPingImpalaServiceResp PingImpalaService();
  183. // Returns the summary of the current execution.
  184. ExecStats.TExecSummary GetExecSummary(1:beeswax.QueryHandle handle)
  185. throws(1:beeswax.QueryNotFoundException error, 2:beeswax.BeeswaxException error2);
  186. }
  187. // Impala HiveServer2 service
  188. struct TGetExecSummaryReq {
  189. 1: optional TCLIService.TOperationHandle operationHandle
  190. 2: optional TCLIService.TSessionHandle sessionHandle
  191. }
  192. struct TGetExecSummaryResp {
  193. 1: required TCLIService.TStatus status
  194. 2: optional ExecStats.TExecSummary summary
  195. }
  196. struct TGetRuntimeProfileReq {
  197. 1: optional TCLIService.TOperationHandle operationHandle
  198. 2: optional TCLIService.TSessionHandle sessionHandle
  199. }
  200. struct TGetRuntimeProfileResp {
  201. 1: required TCLIService.TStatus status
  202. 2: optional string profile
  203. }
  204. service ImpalaHiveServer2Service extends TCLIService.TCLIService {
  205. // Returns the exec summary for the given query
  206. TGetExecSummaryResp GetExecSummary(1:TGetExecSummaryReq req);
  207. // Returns the runtime profile string for the given query
  208. TGetRuntimeProfileResp GetRuntimeProfile(1:TGetRuntimeProfileReq req);
  209. }