A service to execute SQL statements. More...

#include <sql_service.h>

Public Member Functions
template<typename... Params>
boost::future< std::shared_ptr< sql_result > >	execute (const std::string &query, const Params &... params)
	Convenient method to execute a distributed query with the given parameter values.
boost::future< std::shared_ptr< sql_result > >	execute (const sql_statement &statement)
	Executes an SQL statement.

Public Attributes
std::shared_ptr< impl::read_optimized_lru_cache< std::string, int32_t > >	partition_argument_index_cache_

Detailed Description

A service to execute SQL statements.

In order to use the service, Jet engine must be enabled on the server side - SQL statements are executed as Jet jobs. On members, the hazelcast-sql.jar must be on the classpath, otherwise an exception will be thrown; on client, it is not necessary.

Overview

Hazelcast is currently able to execute distributed SQL queries using the following connectors:

IMap
Kafka
Files

When an SQL statement is submitted to a member, it is parsed and optimized hazelcast-sql module, that is based on Apache Calcite. During optimization a statement is converted into a directed acyclic graph (DAG) that is sent to cluster members for execution. Results are sent back to the originating member asynchronously and returned to the user via sql_result.

SQL statements are not atomic. INSERT/SINK can fail and commit part of the data.

Usage

Before you can access any object using SQL, a mapping has to be created. See the reference manual for the CREATE MAPPING command.

When a query is executed, an sql_result is returned. You may get row iterator from the result. The result must be closed at the end. The code snippet below demonstrates a typical usage pattern:

    auto hz = hazelcast::new_client().get();

    try {
        // Get the SQL service from the client and execute a query
        auto result = hz.get_sql().execute("SELECT * FROM person").get();
        for (auto it = result.page_iterator(); it; (++it).get()) {
             // iterate over the rows in the page
             for (auto const &row : (*it).rows()) {
                 auto person_id = row.get<int64_t>("personId");
                 auto name = row.get<std::string>("name");
                 ...
             }
        }

        // Close the result when done.
        result.close().get();
    } catch (hazelcast::client::exception &e) {
         std::cerr << "Query failed: " << e.what() << std::endl;
    }

Definition at line 89 of file sql_service.h.

Member Function Documentation

◆ execute() [1/2]

boost::future< std::shared_ptr< sql_result > > hazelcast::client::sql::sql_service::execute ( const sql_statement & statement )

Executes an SQL statement.

Parameters

statement statement to be executed

Returns: result of the execution

Exceptions

hazelcast_sql_exception in case of execution error

See also: sql_service

Definition at line 69 of file sql.cpp.

{
    using protocol::ClientMessage;
 
    auto statement_par_arg_index_ptr = statement.partition_argument_index();
    int32_t statement_par_arg_index = statement_par_arg_index_ptr != nullptr
                                        ? statement_par_arg_index_ptr->load()
                                        : -1;
 
    auto arg_index = statement_par_arg_index != -1
                       ? statement_par_arg_index
                       : (partition_argument_index_cache_->get_or_default(
                           statement.sql(), -1));
 
    auto partition_id = extract_partition_id(statement, arg_index);
    std::shared_ptr<connection::Connection> query_conn =
      partition_id ? query_connection(partition_id.value())
                   : query_connection();
 
    sql::impl::query_id qid = create_query_id(query_conn);
 
    auto request = protocol::codec::sql_execute_encode(
      statement.sql(),
      statement.serialized_parameters_,
      static_cast<int64_t>(statement.timeout().count()),
      static_cast<int32_t>(statement.cursor_buffer_size()),
      statement.schema() ? &statement.schema().value() : nullptr,
      static_cast<byte>(statement.expected_result_type()),
      qid,
      false);
 
    auto invocation = spi::impl::ClientInvocation::create(
      client_context_, request, "", query_conn);
 
    auto cursor_buffer_size = statement.cursor_buffer_size();
 
    std::weak_ptr<std::atomic<int32_t>> statement_par_arg_index_weak_ptr =
      statement_par_arg_index_ptr;
 
    auto sql_query = statement.sql();
    return invocation->invoke().then(
      boost::launch::sync,
      [this,
       query_conn,
       qid,
       cursor_buffer_size,
       sql_query,
       arg_index,
       statement_par_arg_index_weak_ptr](
        boost::future<ClientMessage> response_fut) {
          try {
              auto response = response_fut.get();
              return handle_execute_response(sql_query,
                                             arg_index,
                                             response,
                                             query_conn,
                                             qid,
                                             cursor_buffer_size,
                                             statement_par_arg_index_weak_ptr);
          } catch (const std::exception& e) {
              rethrow(e, query_conn);
          }
          assert(0);
          return std::shared_ptr<sql_result>();
      });
}

◆ execute() [2/2]

template<typename... Params>

boost::future< std::shared_ptr< sql_result > > hazelcast::client::sql::sql_service::execute	(	const std::string &	query,
		const Params &...	params )

inline

Convenient method to execute a distributed query with the given parameter values.

Converts passed SQL string and parameter values into an sql_statement object and invokes execute(const sql_statement& statement).

Parameters

sql	SQL string
arguments	query parameter values that will be passed to sql_statement::add_parameter(const Param& param)

Returns: result of the execution

Exceptions

illegal_argument	if the SQL string is empty
hazelcast_sql_exception	in case of execution error

See also: sql_service; sql_statement; execute(const sql_statement& statement)

Definition at line 111 of file sql_service.h.

    {
        sql_statement s{ client_context_, query };
        int _[] = { 0, (s.add_parameter(params), 0)... };
        (void)_;
        return execute(s);
    }

Member Data Documentation

◆ partition_argument_index_cache_

std::shared_ptr<impl::read_optimized_lru_cache<std::string, int32_t> > hazelcast::client::sql::sql_service::partition_argument_index_cache_

Definition at line 132 of file sql_service.h.

The documentation for this class was generated from the following files:

hazelcast/include/hazelcast/client/sql/sql_service.h
hazelcast/src/hazelcast/client/sql.cpp

Public Member Functions

Public Attributes