beeswax.thrift 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174
  1. /*
  2. * Licensed to Cloudera, Inc. under one
  3. * or more contributor license agreements. See the NOTICE file
  4. * distributed with this work for additional information
  5. * regarding copyright ownership. Cloudera, Inc. licenses this file
  6. * to you under the Apache License, Version 2.0 (the
  7. * "License"); you may not use this file except in compliance
  8. * with the License. You may obtain a copy of the License at
  9. *
  10. * http://www.apache.org/licenses/LICENSE-2.0
  11. *
  12. * Unless required by applicable law or agreed to in writing, software
  13. * distributed under the License is distributed on an "AS IS" BASIS,
  14. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15. * See the License for the specific language governing permissions and
  16. * limitations under the License.
  17. *
  18. * Interface for interacting with Beeswax Server
  19. */
  20. namespace java com.cloudera.beeswax.api
  21. namespace py beeswaxd
  22. namespace cpp beeswax
  23. include "hive_metastore.thrift"
  24. // A Query
  25. struct Query {
  26. 1: string query;
  27. // A list of HQL commands to execute before the query.
  28. // This is typically defining UDFs, setting settings, and loading resources.
  29. 3: list<string> configuration;
  30. // User and groups to "act as" for purposes of Hadoop.
  31. 4: string hadoop_user;
  32. }
  33. typedef string LogContextId
  34. enum QueryState {
  35. CREATED,
  36. INITIALIZED,
  37. COMPILED,
  38. RUNNING,
  39. FINISHED,
  40. EXCEPTION
  41. }
  42. struct QueryHandle {
  43. 1: string id;
  44. 2: LogContextId log_context;
  45. }
  46. struct QueryExplanation {
  47. 1: string textual
  48. }
  49. struct Results {
  50. // If set, data is valid. Otherwise, results aren't ready yet.
  51. 1: bool ready,
  52. // Columns for the results
  53. 2: list<string> columns,
  54. // A set of results
  55. 3: list<string> data,
  56. // The starting row of the results
  57. 4: i64 start_row,
  58. // Whether there are more results to fetch
  59. 5: bool has_more
  60. }
  61. /**
  62. * Metadata information about the results.
  63. * Applicable only for SELECT.
  64. */
  65. struct ResultsMetadata {
  66. /** The schema of the results */
  67. 1: hive_metastore.Schema schema,
  68. /** The directory containing the results. Not applicable for partition table. */
  69. 2: string table_dir,
  70. /** If the results are straight from an existing table, the table name. */
  71. 3: string in_tablename,
  72. /** Field delimiter */
  73. 4: string delim,
  74. }
  75. exception BeeswaxException {
  76. 1: string message,
  77. // Use get_log(log_context) to retrieve any log related to this exception
  78. 2: LogContextId log_context,
  79. // (Optional) The QueryHandle that caused this exception
  80. 3: QueryHandle handle,
  81. 4: optional i32 errorCode = 0,
  82. 5: optional string SQLState = " "
  83. }
  84. exception QueryNotFoundException {
  85. }
  86. /** Represents a Hadoop-style configuration variable. */
  87. struct ConfigVariable {
  88. 1: string key,
  89. 2: string value,
  90. 3: string description
  91. }
  92. service BeeswaxService {
  93. /**
  94. * Submit a query and return a handle (QueryHandle). The query runs asynchronously.
  95. */
  96. QueryHandle query(1:Query query) throws(1:BeeswaxException error),
  97. /**
  98. * run a query synchronously and return a handle (QueryHandle).
  99. */
  100. QueryHandle executeAndWait(1:Query query, 2:LogContextId clientCtx)
  101. throws(1:BeeswaxException error),
  102. /**
  103. * Get the query plan for a query.
  104. */
  105. QueryExplanation explain(1:Query query)
  106. throws(1:BeeswaxException error),
  107. /**
  108. * Get the results of a query. This is non-blocking. Caller should check
  109. * Results.ready to determine if the results are in yet. The call requests
  110. * the batch size of fetch.
  111. */
  112. Results fetch(1:QueryHandle query_id, 2:bool start_over, 3:i32 fetch_size=-1)
  113. throws(1:QueryNotFoundException error, 2:BeeswaxException error2),
  114. /**
  115. * Get the state of the query
  116. */
  117. QueryState get_state(1:QueryHandle handle) throws(1:QueryNotFoundException error),
  118. /**
  119. * Get the result metadata
  120. */
  121. ResultsMetadata get_results_metadata(1:QueryHandle handle)
  122. throws(1:QueryNotFoundException error),
  123. /**
  124. * Used to test connection to server. A "noop" command.
  125. */
  126. string echo(1:string s)
  127. /**
  128. * Returns a string representation of the configuration object being used.
  129. * Handy for debugging.
  130. */
  131. string dump_config()
  132. /**
  133. * Get the log messages related to the given context.
  134. */
  135. string get_log(1:LogContextId context) throws(1:QueryNotFoundException error)
  136. /*
  137. * Returns "default" configuration.
  138. */
  139. list<ConfigVariable> get_default_configuration(1:bool include_hadoop)
  140. /*
  141. * closes the query with given handle
  142. */
  143. void close(1:QueryHandle handle) throws(1:QueryNotFoundException error,
  144. 2:BeeswaxException error2)
  145. /*
  146. * clean the log context for given id
  147. */
  148. void clean(1:LogContextId log_context)
  149. }