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