class Cassandra::Session

Sessions are used for query execution. Each session tracks its current keyspace. A session should be reused as much as possible, however it is ok to create several independent session for interacting with different keyspaces in the same application.

Inherits

Object

Extends

  • Forwardable

Methods

keyspace

Returns current keyspace

Returns:
Type Details
String current keyspace

execute_async

(statement, options = nil)

Executes a given statement and returns a future result

Note
Positional arguments for simple statements are only supported starting with Apache Cassandra 2.0 and above.
Note
Named arguments for simple statements are only supported starting with Apache Cassandra 2.1 and above.
Parameters:
Name Type Details
statement (String, Statements::Simple, Statements::Bound or Statements::Prepared) statement to execute
options Hash (defaults to: nil) (nil) a customizable set of options
Keys for options:
Key Type Details
:consistency Symbol consistency level for the request. Must be one of CONSISTENCIES
:page_size Integer size of results page. You can page through results using Result#next_page or Result#next_page_async
:trace Boolean default: false whether to enable request tracing
:timeout Numeric default: nil if specified, it is a number of seconds after which to time out the request if it hasn’t completed
:serial_consistency Symbol default: nil this option is only relevant for conditional updates and specifies a serial consistency to be used, one of SERIAL_CONSISTENCIES
:paging_state String default: nil this option is used for stateless paging, where result paging is resumed some time after the initial request.
:arguments (Array or Hash) default: nil positional or named arguments for the statement.
:type_hints (Array or Hash) default: nil override Util.guess_type to determine the CQL type for an argument; nil elements will fall-back to Util.guess_type.
:idempotent Boolean default: false specify whether this statement can be retried safely on timeout.
:payload Hash<[String, Symbol], String> default: nil custom outgoing payload to be sent with the request.
:execution_profile (String or Symbol) default: nil name of Execution::Profile from which to obtain certain query options. Defaults to the cluster’s default execution profile.
Returns:
Type Details
Future<Result>
See Also:
Specifications:
Session#execute_async should error out if a bad profile name is provided 
expect {
          session.execute_async('SELECT * FROM songs', execution_profile: :bad_profile).get
        }.to raise_error(ArgumentError)

execute

(statement, options = nil)

A blocking wrapper around #execute_async

Parameters:
Name Type Details
statement (String, Statements::Simple, Statements::Bound or Statements::Prepared) statement to execute
options Hash (defaults to: nil) (nil) a customizable set of options. See #execute_async for details.
Returns:
Type Details
Result query result
Raises:
Type Details
Errors::NoHostsAvailable if all hosts fail
Errors::ExecutionError if Cassandra fails to execute
Errors::ValidationError if Cassandra fails to validate
Errors::TimeoutError if request has not completed within the :timeout given
See Also:

prepare_async

(statement, options = nil)

Prepares a given statement and returns a future prepared statement

Parameters:
Name Type Details
statement (String or Statements::Simple) a statement to prepare
options Hash (defaults to: nil) (nil) a customizable set of options
Keys for options:
Key Type Details
:trace Boolean default: false whether to enable request tracing
:timeout Numeric default: nil if specified, it is a number of seconds after which to time out the request if it hasn’t completed
:idempotent Boolean default: false specify whether the statement being prepared can be retried safely on timeout during execution.
:execution_profile (String or Symbol) default: nil name of Execution::Profile from which to obtain certain query options. Defaults to the cluster’s default execution profile.
Returns:
Type Details
Future<Statements::Prepared> future prepared statement
Specifications:
Session#prepare_async should error out if a bad profile name is provided 
expect {
          session.prepare_async('SELECT * FROM songs', execution_profile: :bad_profile).get
        }.to raise_error(ArgumentError)

prepare

(statement, options = nil)

A blocking wrapper around #prepare_async

Parameters:
Name Type Details
statement (String or Statements::Simple) a statement to prepare
options Hash (defaults to: nil) (nil) a customizable set of options. See #prepare_async for details.
Returns:
Type Details
Statements::Prepared prepared statement
Raises:
Type Details
Errors::NoHostsAvailable if none of the hosts can be reached
Errors::ExecutionError if Cassandra returns an error response
See Also:
Specifications:
Session#prepare resolves a promise returned by #prepare_async 
expect(session).to receive(:prepare_async).with(statement, nil).and_return(promise)
expect(promise).to receive(:get).once
session.prepare(statement)

logged_batch

{|batch| … } aliased as: batch

Returns a logged Statements::Batch instance and optionally yields it to a given block

Yield Parameters:
Name Type Details
batch Statements::Batch a logged batch
Returns:
Type Details
Statements::Batch a logged batch

unlogged_batch

{|batch| … }

Returns a unlogged Statements::Batch instance and optionally yields it to a given block

Yield Parameters:
Name Type Details
batch Statements::Batch an unlogged batch
Returns:
Type Details
Statements::Batch an unlogged batch
Specifications:
Session#unlogged_batch creates an unlogged batch 
batch = double('batch')
expect(Statements::Batch::Unlogged).to receive(:new).once.and_return(batch)
expect(session.unlogged_batch).to eq(batch)

counter_batch

{|batch| … }

Returns a counter Statements::Batch instance and optionally yields it to a given block

Yield Parameters:
Name Type Details
batch Statements::Batch a counter batch
Returns:
Type Details
Statements::Batch a counter batch
Specifications:
Session#counter_batch creates a counter batch 
batch = double('batch')
expect(Statements::Batch::Counter).to receive(:new).once.and_return(batch)
expect(session.counter_batch).to eq(batch)

close_async

Asynchronously closes current session

Returns:
Type Details
Future<Session> a future that resolves to self once closed
Specifications:
Session#close_async uses Client#close 
expect(client).to receive(:close).and_return(Ione::Future.resolved)
expect(session.close_async).to eq(promise)
expect(promise).to have_received(:fulfill).once.with(session)

close

Synchronously closes current session

Returns:
Type Details
self this session
See Also:
Specifications:
Session#close resolves a promise returned by #close_async 
expect(session).to receive(:close_async).with(no_args).and_return(promise)
expect(promise).to receive(:get).once.and_return('success')
expect(session.close).to eq('success')