Definition of an SQL statement. More...

#include <sql_statement.h>

Public Member Functions
	sql_statement (hazelcast_client &client, std::string query)
	Creates a statement with the given query. More...

const std::string &	sql () const

sql_statement &	sql (std::string sql_string)
	Sets the SQL string to be executed. More...

template<typename... Param>
sql_statement &	set_parameters (Param... params)
	Sets the values for statement parameters. More...

template<typename Param >
sql_statement &	add_parameter (const Param &value)
	Adds a single parameter value to the end of the parameter values list. More...

sql_statement &	clear_parameters ()
	Clears statement parameter values. More...

int32_t	cursor_buffer_size () const
	Gets the cursor buffer size (measured in the number of rows). More...

sql_statement &	cursor_buffer_size (int32_t size)
	Sets the cursor buffer size (measured in the number of rows). More...

std::chrono::milliseconds	timeout () const
	Gets the execution timeout in milliseconds. More...

sql_statement &	timeout (std::chrono::milliseconds timeout)
	Sets the execution timeout in milliseconds. More...

sql_expected_result_type	expected_result_type () const
	Gets the expected result type. More...

sql_statement &	expected_result_type (sql_expected_result_type type)
	Sets the expected result type. More...

const boost::optional< std::string > &	schema () const
	Gets the schema name. More...

sql_statement &	schema (boost::optional< std::string > schema)
	Sets the schema name. More...

Static Public Attributes
static constexpr std::chrono::milliseconds	TIMEOUT_NOT_SET { -1 }
	Value for the timeout that is not set. More...

static constexpr std::chrono::milliseconds	TIMEOUT_DISABLED { 0 }
	Value for the timeout that is disabled, meaning there's no time limit to run a query.

static constexpr std::chrono::milliseconds	DEFAULT_TIMEOUT
	Default timeout. More...

static constexpr int32_t	DEFAULT_CURSOR_BUFFER_SIZE = 4096
	Default cursor buffer size.

Detailed Description

Definition of an SQL statement.

This object is mutable. Properties are read once before the execution is started. Changes to properties do not affect the behavior of already running statements.

Definition at line 41 of file sql_statement.h.

Constructor & Destructor Documentation

◆ sql_statement()

hazelcast::client::sql::sql_statement::sql_statement	(	hazelcast_client &	client,
		std::string	query
	)

Creates a statement with the given query.

Parameters

client	The hazelcast client to be used for the statement.
query	The query string.

Definition at line 337 of file sql.cpp.

   : serialized_parameters_{}
   , cursor_buffer_size_{ DEFAULT_CURSOR_BUFFER_SIZE }
   , timeout_{ TIMEOUT_NOT_SET }
   , expected_result_type_{ sql_expected_result_type::any }
   , schema_{}
   , serialization_service_(
       spi::ClientContext(client).get_serialization_service())
 {
     sql(std::move(query));
 }

Member Function Documentation

◆ add_parameter()

template<typename Param >

sql_statement & hazelcast::client::sql::sql_statement::add_parameter ( const Param & value )

Adds a single parameter value to the end of the parameter values list.

Parameters

value parameter value

Returns: this instance for chaining

See also: set_parameters(); clear_parameters()

Definition at line 241 of file sql_statement.h.

 {
     serialized_parameters_.emplace_back(serialization_service_.to_data(param));
  
     return *this;
 }

◆ clear_parameters()

sql_statement & hazelcast::client::sql::sql_statement::clear_parameters ( )

Clears statement parameter values.

Returns: this instance for chaining

See also: set_parameters(); template<typename Param> add_parameter(const Param& value)

Definition at line 378 of file sql.cpp.

 {
     serialized_parameters_.clear();
  
     return *this;
 }

◆ cursor_buffer_size() [1/2]

int32_t hazelcast::client::sql::sql_statement::cursor_buffer_size ( ) const

Gets the cursor buffer size (measured in the number of rows).

Returns: cursor buffer size (measured in the number of rows)

Definition at line 386 of file sql.cpp.

 {
     return cursor_buffer_size_;
 }

◆ cursor_buffer_size() [2/2]

sql_statement & hazelcast::client::sql::sql_statement::cursor_buffer_size ( int32_t size )

Sets the cursor buffer size (measured in the number of rows).

When a statement is submitted for execution, a sql_result is returned as a result. When rows are ready to be consumed, they are put into an internal buffer of the cursor. This parameter defines the maximum number of rows in that buffer. When the threshold is reached, the backpressure mechanism will slow down the execution, possibly to a complete halt, to prevent out-of-memory.

Only positive values are allowed.

The default value is expected to work well for most workloads. A bigger buffer size may give you a slight performance boost for queries with large result sets at the cost of increased memory consumption.

Defaults to sql_statement::DEFAULT_CURSOR_BUFFER_SIZE.

Parameters

size	cursor buffer size (measured in the number of rows)

Returns: this instance for chaining

See also: hazelcast::client::sql::sql_service::execute(const sql_statement& statement); hazelcast::client::sql::sql_result

Definition at line 392 of file sql.cpp.

 {
     util::Preconditions::check_positive(
       size,
       (boost::format("Cursor buffer size must be positive: %s") % size).str());
     cursor_buffer_size_ = size;
  
     return *this;
 }

◆ expected_result_type() [1/2]

sql::sql_expected_result_type hazelcast::client::sql::sql_statement::expected_result_type ( ) const

Gets the expected result type.

Returns: expected result type

Definition at line 439 of file sql.cpp.

 {
     return expected_result_type_;
 }

◆ expected_result_type() [2/2]

sql_statement& hazelcast::client::sql::sql_statement::expected_result_type ( sql_expected_result_type type )

Sets the expected result type.

Parameters

type	expected result type

Returns: this instance for chaining

◆ schema() [1/2]

const boost::optional< std::string > & hazelcast::client::sql::sql_statement::schema ( ) const

Gets the schema name.

Returns: the schema name or
boost::none

if there is none

Definition at line 426 of file sql.cpp.

 {
     return schema_;
 }

◆ schema() [2/2]

sql_statement & hazelcast::client::sql::sql_statement::schema ( boost::optional< std::string > schema )

Sets the schema name.

The engine will try to resolve the non-qualified object identifiers from the statement in the given schema. If not found, the default search path will be used, which looks for objects in the predefined schemas

"partitioned"

and

"public"

.

The schema name is case sensitive. For example,

"foo"

and

"Foo"

are different schemas.

The default value is

boost::none

meaning only the default search path is used.

Parameters

schema the current schema name

Returns: this instance for chaining

Definition at line 432 of file sql.cpp.

 {
     schema_ = std::move(schema);
     return *this;
 }

◆ set_parameters()

template<typename... Param>

sql_statement & hazelcast::client::sql::sql_statement::set_parameters ( Param... params )

Sets the values for statement parameters.

You may define parameter placeholders in the statement with the

"?"

character. For every placeholder, a value must be provided.

When the method is called, the contents of the list are copied. Subsequent changes to the original list don't change the statement parameters.

Parameters

value	the first statement parameter
other_params	the other statement parameters if exist

Returns: this instance for chaining

See also: template<typename Param> add_parameter(const Param& value); clear_parameters()

Definition at line 250 of file sql_statement.h.

 {
     int _[] = { 0, ((void)add_parameter(params), 0)... };
     (void)_;
     return *this;
 }

◆ sql() [1/2]

const std::string & hazelcast::client::sql::sql_statement::sql ( ) const

Returns: The sql string to be executed

Definition at line 362 of file sql.cpp.

 {
     return sql_;
 }

◆ sql() [2/2]

sql_statement & hazelcast::client::sql::sql_statement::sql ( std::string sql_string )

Sets the SQL string to be executed.

The SQL string cannot be empty.

Parameters

sql_string SQL string

Returns: this instance for chaining

Exceptions

hazelcast::client::exception::illegal_argument if passed SQL string is empty

Definition at line 368 of file sql.cpp.

 {
     util::Preconditions::check_not_empty(sql_string, "SQL cannot be empty");
  
     sql_ = std::move(sql_string);
  
     return *this;
 }

◆ timeout() [1/2]

std::chrono::milliseconds hazelcast::client::sql::sql_statement::timeout ( ) const

Gets the execution timeout in milliseconds.

Returns: execution timeout in milliseconds

Definition at line 403 of file sql.cpp.

 {
     return timeout_;
 }

◆ timeout() [2/2]

sql_statement & hazelcast::client::sql::sql_statement::timeout ( std::chrono::milliseconds timeout )

Sets the execution timeout in milliseconds.

If the timeout is reached for a running statement, it will be cancelled forcefully.

Zero value means no timeout. sql_statement::TIMEOUT_NOT_SET means that the value from sql_config::statement_timeout() will be used. Other negative values are prohibited.

Defaults to sql_statement::TIMEOUT_NOT_SET .

Parameters

timeout execution timeout in milliseconds, \c0 for no timeout, -1 to user member's default timeout

Returns: this instance for chaining

See also: sql_config::statement_timeout()

Definition at line 409 of file sql.cpp.

 {
     auto timeout_msecs = timeout.count();
     if (timeout_msecs < 0 && timeout != TIMEOUT_NOT_SET) {
         throw exception::illegal_argument(
           "sql_statement::timeout(std::chrono::milliseconds timeout)",
           (boost::format("Timeout must be non-negative or -1: %1% msecs") %
            timeout_msecs)
             .str());
     }
  
     timeout_ = timeout;
  
     return *this;
 }

Member Data Documentation

◆ DEFAULT_TIMEOUT

constexpr std::chrono::milliseconds hazelcast::client::sql::sql_statement::DEFAULT_TIMEOUT

staticconstexpr

Initial value:

=

TIMEOUT_NOT_SET

Default timeout.

Definition at line 57 of file sql_statement.h.

◆ TIMEOUT_NOT_SET

constexpr std::chrono::milliseconds hazelcast::client::sql::sql_statement::TIMEOUT_NOT_SET { -1 }

staticconstexpr

Value for the timeout that is not set.

The value of sql_config::statement_timeout_millis will be used.

Definition at line 48 of file sql_statement.h.

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

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

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ sql_statement()

Member Function Documentation

◆ add_parameter()

◆ clear_parameters()

◆ cursor_buffer_size() [1/2]

◆ cursor_buffer_size() [2/2]

◆ expected_result_type() [1/2]

◆ expected_result_type() [2/2]

◆ schema() [1/2]

◆ schema() [2/2]

◆ set_parameters()

◆ sql() [1/2]

◆ sql() [2/2]

◆ timeout() [1/2]

◆ timeout() [2/2]

Member Data Documentation

◆ DEFAULT_TIMEOUT

◆ TIMEOUT_NOT_SET