blob: 45dd5317be2c526a8d0b97ef411224a900d2ee07 [file] [log] [blame]
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.
#pragma once
#include <map>
#include <string>
#include <vector>
#include "common/status.h"
#include "gen-cpp/Query_types.h"
#include "gen-cpp/TCLIService_types.h"
#include "gen-cpp/Types_types.h"
#include "rpc/thrift-server.h"
namespace impala {
typedef std::vector<std::pair<std::string, std::string>> results_columns;
/// Enables Impala coordinators to submit queries to themselves.
///
/// Internally, this class directly calls the methods on ImpalaServer that are called by
/// the Beeswax and HS2 servers. Thus, it does not strictly adhere to either protocol.
/// Since Impala requires sessions to have a defined type, sessions created by
/// InternalServer show up as Beeswax sessions.
///
/// Since this class directly calls ImpalaServer methods, it bypasses all authentication
/// methods.
///
/// Usage:
/// The easiest way to use this class is to call the `ExecuteAndFetchAllHS2` function
/// which runs the provided sql, returns all the results, and closes the query and
/// session. This function is useful for running create/insert/update queries that do
/// not return many results.
///
/// The next way is to call the `SubmitAndWait` function. This function runs the
/// provided sql and blocks until results become available. Retrieving the results can
/// be done by leveraging the query id returned by this method. The `CloseQuery` and
/// `CloseSession` functions must be called by clients once all results are read.
///
/// The lowest level function is `SubmitQuery`. This function starts a query running
/// and returns immediately. Opening a connection/session, waiting for results,
/// retrieving results, and closing the query/session is left up to the client.
class InternalServer {
public:
virtual ~InternalServer() {}
using QueryOptionMap = std::map<TImpalaQueryOptions::type, string>;
/// Creates and registers a new connection and session.
///
/// Parameters:
/// `user_name` Specifies the username that will be reported as running this
/// query.
/// `new_session_id` Output parameter that will be populated with the id of the
/// newly created session.
/// `query_opts` Optional, contains query options that will apply to all
/// queries executed during this session.
///
/// Return:
/// `impala::Status` Indicates the result of opening the new session.
virtual Status OpenSession(const std::string& user_name, TUniqueId& new_session_id,
const QueryOptionMap& query_opts = {}) = 0;
/// Closes a given session cleaning up all associated resources.
///
/// Parameters:
/// `session_id` Id of the session that will be closed.
///
/// Return:
/// `bool` Indicates if the provided session id was for a known session created
/// by the `OpenSession` function.
virtual bool CloseSession(const impala::TUniqueId& session_id) = 0;
/// Executes a given query cleaning up after the query has completed. Results are
/// never retrieved.
///
/// Parameters:
/// `user_name` Specifies the username that will be reported as running this
/// query.
/// `sql` Text of the sql query/ddl/dml to run.
/// `query_opts` Optional, contains query options that will apply to all
/// queries executed during this session.
/// `persist_in_db` Optional boolean indicating if the query data should be
/// written to the completed queries table after it is closed.
/// Defaults to `true`.
/// `query_id` Optional output parameter, if specified, it will be
/// overwritten with the id of the query that was executed. Since
/// the query is closed by this function, the query id is
/// informational only.
///
/// Return:
/// `impala::Status` Indicates the result of submitting the query and waiting for
/// it to return.
virtual Status ExecuteIgnoreResults(const std::string& user_name,
const std::string& sql, const QueryOptionMap& query_opts = {},
const bool persist_in_db = true, TUniqueId* query_id = nullptr) = 0;
/// Creates a new session under the specified user and submits a query under that
/// session. No authentication is performed. Blocks until result rows are available.
/// Then, populates all result rows. Finally, cleans up the query and session.
///
/// Parameters:
/// `user_name` Specifies the username that will be reported as running this
/// query.
/// `sql` Text of the sql query/ddl/dml to run.
/// `results` Output parameter containing all result rows from the query.
/// If this vector has existing elements, they will be left in
/// place with result rows added at the end of the vector.
/// `query_opts` Optional, contains query options that will apply to all
/// queries executed by this session opened by this function.
/// `persist_in_db` Optional boolean indicating if the query data should be
/// written to the completed queries table after it is closed.
/// Defaults to `true`.
/// `columns` Optional output parameter where each element is a pair with
/// the first element being the name of the column and the second
/// element being the column type. Existing elements in the vector
/// will be left in place with column pairs appended to the end of
/// the vector. If this parameter is `nullptr`, then the list of
/// columns is not generated and this parameter's value will
/// remain `nullptr`.
/// `query_id` Optional output parameter, if specified, it will be
/// overwritten with the id of the query that was executed. Since
/// the query is closed by this function, the query id is
/// informational only.
///
/// Return:
/// `impala::Status` indicating the result of submitting the query and waiting for
/// it to return.
virtual Status ExecuteAndFetchAllHS2(const std::string& user_name,
const std::string& sql,
std::vector<apache::hive::service::cli::thrift::TRow>& results,
const QueryOptionMap& query_opts = {}, const bool persist_in_db = true,
results_columns* columns = nullptr, TUniqueId* query_id = nullptr) = 0;
/// Creates a new session under the specified user and submits a query under that
/// session. No authentication is performed. Blocks until result rows are available.
///
/// After retrieving the results, clients must call `CloseQuery` and `CloseSession`
/// to properly close and clean up the query and session.
///
/// Parameters:
/// `user_name` Specifies the username that will be reported as running this
/// query.
/// `sql` Text of the sql query/ddl/dml to run.
/// `new_session_id` Output parameter that will be set to the id of the
/// newly created session.
/// `new_query_id` Output parameter that will be set to the id of the
/// newly started query.
/// `query_opts` Optional, contains query options that will apply to all
/// queries executed by this session opened by this function.
/// `persist_in_db` Optional boolean indicating if the query data should be
/// written to the completed queries table after it is closed.
/// Defaults to `true`.
///
/// Return:
/// `impala::Status` Indicates the result of submitting and waiting for the query.
virtual Status SubmitAndWait(const std::string& user_name, const std::string& sql,
TUniqueId& new_session_id, TUniqueId& new_query_id,
const QueryOptionMap& query_opts = {}, const bool persist_in_db = true) = 0;
/// Waits until the given query has results available.
///
/// Parameters:
/// `query_id` Input/output parameter that contains the id of a query to wait for
/// it to produce results. The value of this parameter will change if
/// the query was automatically retried by the coordinator.
virtual Status WaitForResults(TUniqueId& query_id) = 0;
/// Submits a query to the current Impala coordinator under the provided session and
/// sets the query as in-flight before returning.
///
/// Parameters:
/// `sql` Text of the sql query/ddl/dml to run.
/// `session_id` Id of the session that will run the query.
/// `new_query_id` Output parameter that will be set to the id of the newly
/// started query.
/// `persist_in_db` Optional boolean indicating if the query data should be
/// written to the completed queries table after it is closed.
/// Defaults to `true`.
///
/// Return:
/// `impala::Status` Indicates the result of submitting the query.
virtual Status SubmitQuery(const std::string& sql,
const impala::TUniqueId& session_id, TUniqueId& new_query_id,
const bool persist_in_db = true) = 0;
/// Retrieves all result rows for a given query. The rows are retrieved using HS2
/// objects. Thus, each row and column is stored within its own object. The query
/// must have already been submitted and one of the Wait methods called on the query
/// to ensure results are available.
///
/// Note: Assumes the query represented by `query_id` was successful as this
/// function does not check that the query status is a successful status.
///
/// Parameters:
/// `query_id` Id of a query that was submitted and has results available.
/// `query_results` Output parameter containing all result rows from the query. If
/// this vector has existing elements, they will be left in place
/// with result rows added at the end of the vector.
/// `columns` Optional output parameter where each element is a pair with
/// the first element being the name of the column and the second
/// element being the column type. Existing elements in the vector
/// will be left in place with column pairs appended to the end of
/// the vector. If this parameter is `nullptr`, then the list of
/// columns is not generated and this parameter's value will
/// remain `nullptr`.
/// Return:
/// `impala::Status` Indicates the result of fetching rows.
virtual Status FetchAllRowsHS2(const TUniqueId& query_id,
std::vector<apache::hive::service::cli::thrift::TRow>& query_results,
results_columns* columns = nullptr) = 0;
/// Closes and cleans up the query and its associated session.
///
/// Parameters:
/// `query_id` Query that was submitted and has finished.
virtual void CloseQuery(const TUniqueId& query_id) = 0;
/// Populates the provided list with all connections currently managed by the
/// internal server.
///
/// Parameters:
/// `connection_contexts` Input/output parameter that will have all internal
/// server connections added to the end.
virtual void GetConnectionContextList(
ThriftServer::ConnectionContextList* connection_contexts) = 0;
}; // InternalServer class
} // namespace impala