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. More...

boost::future< std::shared_ptr< sql_result > >	execute (const sql_statement &statement)
	Executes an SQL statement. More...

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 88 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 57 of file sql.cpp.

 {
     using protocol::ClientMessage;
  
     auto query_conn = 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();
  
     return invocation->invoke().then(
       boost::launch::sync,
       [this, query_conn, qid, cursor_buffer_size](
         boost::future<ClientMessage> response_fut) {
           try {
               auto response = response_fut.get();
               return handle_execute_response(
                 response, query_conn, qid, cursor_buffer_size);
           } 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).