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.

Public Class Methods

new(client, default_options, futures_factory, profile_manager) click to toggle source

@private

   # File lib/cassandra/session.rb
32 def initialize(client, default_options, futures_factory, profile_manager)
33   @client  = client
34   @options = default_options
35   @futures = futures_factory
36   @profile_manager = profile_manager
37 end

Public Instance Methods

batch(&block)
Alias for: logged_batch
close() click to toggle source

Synchronously closes current session

@return [self] this session

@see Cassandra::Session#close_async

    # File lib/cassandra/session.rb
234 def close
235   close_async.get
236 end
close_async() click to toggle source

Asynchronously closes current session

@return [Cassandra::Future<Cassandra::Session>] a future that resolves to

self once closed
    # File lib/cassandra/session.rb
215 def close_async
216   promise = @futures.promise
217 
218   @client.close.on_complete do |f|
219     if f.resolved?
220       promise.fulfill(self)
221     else
222       f.on_failure {|e| promise.break(e)}
223     end
224   end
225 
226   promise.future
227 end
counter_batch() { |statement| ... } click to toggle source

Returns a counter {Statements::Batch} instance and optionally yields it to a given block @yieldparam batch [Statements::Batch] a counter batch @return [Statements::Batch] a counter batch

    # File lib/cassandra/session.rb
205 def counter_batch
206   statement = Statements::Batch::Counter.new(@options)
207   yield(statement) if block_given?
208   statement
209 end
execute(statement, options = nil) click to toggle source

@!method execute(statement, options = nil) A blocking wrapper around {Cassandra::Session#execute_async}

@param statement [String, Cassandra::Statements::Simple,

Cassandra::Statements::Bound, Cassandra::Statements::Prepared]
statement to execute

@param options [Hash] (nil) a customizable set of options. See {#execute_async} for details.

@see Cassandra::Session#execute_async @see Cassandra::Future#get

@return [Cassandra::Result] query result @raise [Cassandra::Errors::NoHostsAvailable] if all hosts fail @raise [Cassandra::Errors::ExecutionError] if Cassandra fails to execute @raise [Cassandra::Errors::ValidationError] if Cassandra fails to validate @raise [Cassandra::Errors::TimeoutError] if request has not completed

within the `:timeout` given
    # File lib/cassandra/session.rb
126 def execute(statement, options = nil)
127   execute_async(statement, options).get
128 end
execute_async(statement, options = nil) click to toggle source

Executes a given statement and returns a future result

@param statement [String, Cassandra::Statements::Simple,

Cassandra::Statements::Bound, Cassandra::Statements::Prepared]
statement to execute

@param options [Hash] (nil) a customizable set of options

@option options [Symbol] :consistency consistency level for the request.

Must be one of {Cassandra::CONSISTENCIES}. Defaults to the setting in the
active execution profile. If none is specified, the default profile is used,
which is set to `:quorum`.

@option options [Integer] :page_size size of results page. You can page

through results using {Cassandra::Result#next_page} or
{Cassandra::Result#next_page_async}

@option options [Boolean] :trace (false) whether to enable request tracing @option options [Numeric] :timeout (nil) if specified, it is a number of

seconds after which to time out the request if it hasn't completed. Defaults to the setting in the
active execution profile. If none is specified, the default profile is used,
which is set to 12 seconds.

@option options [Symbol] :serial_consistency (nil) this option is only

relevant for conditional updates and specifies a serial consistency to
be used, one of {Cassandra::SERIAL_CONSISTENCIES}

@option options [String] :paging_state (nil) this option is used for

stateless paging, where result paging is resumed some time after the
initial request.

@option options [Array, Hash] :arguments (nil) positional or named

arguments for the statement.

@option options [Array, Hash] :type_hints (nil) override Util.guess_type

to determine the CQL type for an argument; nil elements will fall-back
to Util.guess_type.

@option options [Boolean] :idempotent (false) specify whether this

statement can be retried safely on timeout.

@option options [Hash<[String, Symbol], String>] :payload (nil) custom

outgoing payload to be sent with the request.

@option options [String, Symbol] :execution_profile (nil) name of {Cassandra::Execution::Profile}

from which to obtain certain query options. Defaults to the cluster's default execution profile.

@see Cassandra.cluster Options that can be specified on the cluster-level

and their default values.

@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.

@return [Cassandra::Future<Cassandra::Result>]

@see Cassandra::Session#execute A list of errors this future can be resolved with

    # File lib/cassandra/session.rb
 89 def execute_async(statement, options = nil)
 90   options = merge_execution_options(options)
 91 
 92   case statement
 93   when ::String
 94     Statements::Simple.new(statement,
 95                            options.arguments,
 96                            options.type_hints,
 97                            options.idempotent?).accept(@client,
 98                                                        options)
 99   when Statement
100     statement.accept(@client, options)
101   else
102     @futures.error(::ArgumentError.new("unsupported statement #{statement.inspect}"))
103   end
104 rescue => e
105   @futures.error(e)
106 end
inspect() click to toggle source

@private

    # File lib/cassandra/session.rb
239 def inspect
240   "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
241   "@keyspace=#{keyspace.inspect}, " \
242   "@options=#{@options.inspect}>"
243 end
logged_batch() { |statement| ... } click to toggle source

Returns a logged {Statements::Batch} instance and optionally yields it to a given block @yieldparam batch [Statements::Batch] a logged batch @return [Statements::Batch] a logged batch

    # File lib/cassandra/session.rb
184 def logged_batch(&block)
185   statement = Statements::Batch::Logged.new(@options)
186   yield(statement) if block_given?
187   statement
188 end
Also aliased as: batch
prepare(statement, options = nil) click to toggle source

A blocking wrapper around {Cassandra::Session#prepare_async}

@param statement [String, Cassandra::Statements::Simple] a statement to

prepare

@param options [Hash] (nil) a customizable set of options. See {#prepare_async} for details.

@see Cassandra::Session#prepare_async @see Cassandra::Future#get

@return [Cassandra::Statements::Prepared] prepared statement @raise [Cassandra::Errors::NoHostsAvailable] if none of the hosts can be reached @raise [Cassandra::Errors::ExecutionError] if Cassandra returns an error response

    # File lib/cassandra/session.rb
176 def prepare(statement, options = nil)
177   prepare_async(statement, options).get
178 end
prepare_async(statement, options = nil) click to toggle source

Prepares a given statement and returns a future prepared statement

@param statement [String, Cassandra::Statements::Simple] a statement to

prepare

@param options [Hash] (nil) a customizable set of options

@option options [Boolean] :trace (false) whether to enable request tracing @option options [Numeric] :timeout (nil) if specified, it is a number of

seconds after which to time out the request if it hasn't completed

@option options [Boolean] :idempotent (false) specify whether the

statement being prepared can be retried safely on timeout during
execution.

@option options [String, Symbol] :execution_profile (nil) name of {Cassandra::Execution::Profile}

from which to obtain certain query options. Defaults to the cluster's default execution profile.

@return [Cassandra::Future<Cassandra::Statements::Prepared>] future

prepared statement
    # File lib/cassandra/session.rb
148 def prepare_async(statement, options = nil)
149   options = merge_execution_options(options)
150 
151   case statement
152   when ::String
153     @client.prepare(statement, options)
154   when Statements::Simple
155     @client.prepare(statement.cql, options)
156   else
157     @futures.error(::ArgumentError.new("unsupported statement #{statement.inspect}"))
158   end
159 rescue => e
160   @futures.error(e)
161 end
unlogged_batch() { |statement| ... } click to toggle source

Returns a unlogged {Statements::Batch} instance and optionally yields it to a given block @yieldparam batch [Statements::Batch] an unlogged batch @return [Statements::Batch] an unlogged batch

    # File lib/cassandra/session.rb
195 def unlogged_batch
196   statement = Statements::Batch::Unlogged.new(@options)
197   yield(statement) if block_given?
198   statement
199 end

Private Instance Methods

merge_execution_options(options) click to toggle source

@private

    # File lib/cassandra/session.rb
248 def merge_execution_options(options)
249   if options
250     Util.assert_instance_of(::Hash, options)
251     # Yell if the caller gave us a bad profile name.
252     execution_profile = nil
253     if options.key?(:execution_profile)
254       execution_profile = @profile_manager.profiles[options[:execution_profile]]
255       raise ::ArgumentError.new("Unknown execution profile #{options[:execution_profile]}") unless execution_profile
256     end
257 
258     # This looks a little hokey, so let's explain: Execution::Options.override takes a
259     # varargs-style array of things to merge into the base options object (to produce
260     # a new Options object, not mutate the base). If an execution profile was specified,
261     # we want its attributes to override the base options. In addition, if individual options
262     # were specified, we want *those* to take precedence over the execution profile attributes.
263     # So we override in this order.
264     @options.override(execution_profile, options)
265   else
266     @options
267   end
268 end