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.
const std::string &	sql () const
sql_statement &	sql (std::string sql_string)
	Sets the SQL string to be executed.
template<typename... Param>
sql_statement &	set_parameters (Param... params)
	Sets the values for statement parameters.
template<typename Param>
sql_statement &	add_parameter (const Param &value)
	Adds a single parameter value to the end of the parameter values list.
sql_statement &	clear_parameters ()
	Clears statement parameter values.
int32_t	cursor_buffer_size () const
	Gets the cursor buffer size (measured in the number of rows).
sql_statement &	cursor_buffer_size (int32_t size)
	Sets the cursor buffer size (measured in the number of rows).
std::chrono::milliseconds	timeout () const
	Gets the execution timeout in milliseconds.
sql_statement &	timeout (std::chrono::milliseconds timeout)
	Sets the execution timeout in milliseconds.
sql_expected_result_type	expected_result_type () const
	Gets the expected result type.
sql_statement &	expected_result_type (sql_expected_result_type type)
	Sets the expected result type.
std::shared_ptr< std::atomic< int32_t > >	partition_argument_index () const
	Get the partition argument index value.
const boost::optional< std::string > &	schema () const
	Gets the schema name.
sql_statement &	schema (boost::optional< std::string > schema)
	Sets the schema name.

Static Public Attributes
static constexpr std::chrono::milliseconds	TIMEOUT_NOT_SET { -1 }
	Value for the timeout that is not set.
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.
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 461 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_{}
  , partition_argument_index_{ std::make_shared<std::atomic<int32_t>>(-1) }
  , 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 262 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 504 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 512 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 518 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 565 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

◆ partition_argument_index()

std::shared_ptr< std::atomic< int32_t > > hazelcast::client::sql::sql_statement::partition_argument_index ( ) const

Get the partition argument index value.

Returns: partition argument index, -1 if not set.

Definition at line 578 of file sql.cpp.

{
    return partition_argument_index_;
}

◆ 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 552 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 558 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 271 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 488 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 494 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 529 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 535 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_CURSOR_BUFFER_SIZE

int32_t hazelcast::client::sql::sql_statement::DEFAULT_CURSOR_BUFFER_SIZE = 4096

staticconstexpr

Default cursor buffer size.

Definition at line 61 of file sql_statement.h.

◆ DEFAULT_TIMEOUT

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_DISABLED

std::chrono::milliseconds hazelcast::client::sql::sql_statement::TIMEOUT_DISABLED { 0 }

staticconstexpr

Value for the timeout that is disabled, meaning there's no time limit to run a query.

Definition at line 54 of file sql_statement.h.

54{ 0 };

◆ TIMEOUT_NOT_SET

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.

48{ -1 };

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]

◆ partition_argument_index()

◆ schema() [1/2]

◆ schema() [2/2]

◆ set_parameters()

◆ sql() [1/2]

◆ sql() [2/2]

◆ timeout() [1/2]

◆ timeout() [2/2]

Member Data Documentation

◆ DEFAULT_CURSOR_BUFFER_SIZE

◆ DEFAULT_TIMEOUT

◆ TIMEOUT_DISABLED

◆ TIMEOUT_NOT_SET