beeswax.thrift 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172
  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. include "hive_metastore.thrift"
  23. // A Query
  24. struct Query {
  25. 1: string query;
  26. // A list of HQL commands to execute before the query.
  27. // This is typically defining UDFs, setting settings, and loading resources.
  28. 3: list<string> configuration;
  29. // User and groups to "act as" for purposes of Hadoop.
  30. 4: string hadoop_user;
  31. }
  32. typedef string LogContextId
  33. enum QueryState {
  34. CREATED,
  35. INITIALIZED,
  36. COMPILED,
  37. RUNNING,
  38. FINISHED,
  39. EXCEPTION
  40. }
  41. struct QueryHandle {
  42. 1: string id;
  43. 2: LogContextId log_context;
  44. }
  45. struct QueryExplanation {
  46. 1: string textual
  47. }
  48. struct Results {
  49. // If set, data is valid. Otherwise, results aren't ready yet.
  50. 1: bool ready,
  51. // Columns for the results
  52. 2: list<string> columns,
  53. // A set of results
  54. 3: list<string> data,
  55. // The starting row of the results
  56. 4: i64 start_row,
  57. // Whether there are more results to fetch
  58. 5: bool has_more
  59. }
  60. /**
  61. * Metadata information about the results.
  62. * Applicable only for SELECT.
  63. */
  64. struct ResultsMetadata {
  65. /** The schema of the results */
  66. 1: hive_metastore.Schema schema,
  67. /** The directory containing the results. Not applicable for partition table. */
  68. 2: string table_dir,
  69. /** If the results are straight from an existing table, the table name. */
  70. 3: string in_tablename,
  71. /** Field delimiter */
  72. 4: string delim,
  73. }
  74. exception BeeswaxException {
  75. 1: string message,
  76. // Use get_log(log_context) to retrieve any log related to this exception
  77. 2: LogContextId log_context,
  78. // (Optional) The QueryHandle that caused this exception
  79. 3: QueryHandle handle,
  80. 4: optional i32 errorCode = 0,
  81. 5: optional string SQLState = " "
  82. }
  83. exception QueryNotFoundException {
  84. }
  85. /** Represents a Hadoop-style configuration variable. */
  86. struct ConfigVariable {
  87. 1: string key,
  88. 2: string value,
  89. 3: string description
  90. }
  91. service BeeswaxService {
  92. /**
  93. * Submit a query and return a handle (QueryHandle). The query runs asynchronously.
  94. */
  95. QueryHandle query(1:Query query) throws(1:BeeswaxException error),
  96. /**
  97. * run a query synchronously and return a handle (QueryHandle).
  98. */
  99. QueryHandle executeAndWait(1:Query query, 2:LogContextId clientCtx)
  100. throws(1:BeeswaxException error),
  101. /**
  102. * Get the query plan for a query.
  103. */
  104. QueryExplanation explain(1:Query query)
  105. throws(1:BeeswaxException error),
  106. /**
  107. * Get the results of a query. This is non-blocking. Caller should check
  108. * Results.ready to determine if the results are in yet. The call requests
  109. * the batch size of fetch.
  110. */
  111. Results fetch(1:QueryHandle query_id, 2:bool start_over, 3:i32 fetch_size=-1)
  112. throws(1:QueryNotFoundException error, 2:BeeswaxException error2),
  113. /**
  114. * Get the state of the query
  115. */
  116. QueryState get_state(1:QueryHandle handle) throws(1:QueryNotFoundException error),
  117. /**
  118. * Get the result metadata
  119. */
  120. ResultsMetadata get_results_metadata(1:QueryHandle handle)
  121. throws(1:QueryNotFoundException error),
  122. /**
  123. * Used to test connection to server. A "noop" command.
  124. */
  125. string echo(1:string s)
  126. /**
  127. * Returns a string representation of the configuration object being used.
  128. * Handy for debugging.
  129. */
  130. string dump_config()
  131. /**
  132. * Get the log messages related to the given context.
  133. */
  134. string get_log(1:LogContextId context) throws(1:QueryNotFoundException error)
  135. /*
  136. * Returns "default" configuration.
  137. */
  138. list<ConfigVariable> get_default_configuration(1:bool include_hadoop)
  139. /*
  140. * closes the query with given handle
  141. */
  142. void close(1:QueryHandle handle) throws(1:QueryNotFoundException error,
  143. 2:BeeswaxException error2)
  144. /*
  145. * clean the log context for given id
  146. */
  147. void clean(1:LogContextId log_context)
  148. }