Brand

Ruby Driver for Apache Cassandra

Attention: Viewing documentation for version
(Earlier version)
Download

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.
Returns:
Type Details
Future<Result>
See Also:

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
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
Returns:
Type Details
Future<Statements::Prepared> future prepared statement

prepare

(*args)

A blocking wrapper around #prepare_async

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(*args).and_return(promise)
expect(promise).to receive(:get).once
session.prepare(*args)

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')

inspect

Returns a CLI-friendly session representation

Returns:
Type Details
String a CLI-friendly session representation