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, *args, options = {})

Executes a given statement and returns a future result

Note
Last argument will be treated as options if it is a Hash. Therefore, make sure to pass empty options when executing a statement with the last parameter required to be a map datatype.
Note
Positional arguments are only supported on Apache Cassandra 2.0 and above.
Parameters:
Name Type Details
statement (String, Statements::Simple, Statements::Bound or Statements::Prepared) statement to execute
args *Object arguments to paramterized query or prepared statement
options Hash (defaults to: {}) 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.
Returns:
Type Details
Future<Result>
See Also:

execute

(statement, *args, options = {})

A blocking wrapper around #execute_async

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

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(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