Class: Cassandra::Session

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/cassandra/session.rb

Overview

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.

Instance Method Summary collapse

Instance Method Details

#close ⇒ self

Synchronously closes current session

Returns:

  • (self) —

    this session

See Also:



234
235
236
 
# File 'lib/cassandra/session.rb', line 234

def close
  close_async.get
end

#close_async ⇒ Cassandra::Future<Cassandra::Session>

Asynchronously closes current session

Returns:



215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/cassandra/session.rb', line 215

def close_async
  promise = @futures.promise

  @client.close.on_complete do |f|
    if f.resolved?
      promise.fulfill(self)
    else
      f.on_failure {|e| promise.break(e)}
    end
  end

  promise.future
end

#counter_batch {|batch| ... } ⇒ Statements::Batch

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

Yield Parameters:

Returns:



205
206
207
208
209
 
# File 'lib/cassandra/session.rb', line 205

def counter_batch
  statement = Statements::Batch::Counter.new(@options)
  yield(statement) if block_given?
  statement
end

#execute(statement, options = nil) ⇒ Cassandra::Result

A blocking wrapper around #execute_async

Parameters:

Returns:

Raises:

See Also:



126
127
128
 
# File 'lib/cassandra/session.rb', line 126

def execute(statement, options = nil)
  execute_async(statement, options).get
end

#execute_async(statement, options = nil) ⇒ Cassandra::Future<Cassandra::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.

Executes a given statement and returns a future result

Parameters:

Options Hash (options):

  • :consistency (Symbol) —

    consistency level for the request. Must be one of CONSISTENCIES. Defaults to the setting in the active execution profile. If none is specified, the default profile is used, which is set to :local_one.

  • :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. Defaults to the setting in the active execution profile. If none is specified, the default profile is used, which is set to 12 seconds.

  • :serial_consistency (Symbol) — default: nil —

    this option is only relevant for conditional updates and specifies a serial consistency to be used, one of Cassandra::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, Hash) — default: nil —

    positional or named arguments for the statement.

  • :type_hints (Array, 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, Symbol) — default: nil —

    name of Execution::Profile from which to obtain certain query options. Defaults to the cluster's default execution profile.

Returns:

See Also:



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/cassandra/session.rb', line 89

def execute_async(statement, options = nil)
  options = merge_execution_options(options)

  case statement
  when ::String
    Statements::Simple.new(statement,
                           options.arguments,
                           options.type_hints,
                           options.idempotent?).accept(@client,
                                                       options)
  when Statement
    statement.accept(@client, options)
  else
    @futures.error(::ArgumentError.new("unsupported statement #{statement.inspect}"))
  end
rescue => e
  @futures.error(e)
end

#keyspace ⇒ String

Returns current keyspace

Returns:

  • (String) —

    current keyspace



29
 
# File 'lib/cassandra/session.rb', line 29

def_delegators :@client, :keyspace

#logged_batch {|batch| ... } ⇒ Statements::Batch Also known as: batch

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

Yield Parameters:

Returns:



184
185
186
187
188
 
# File 'lib/cassandra/session.rb', line 184

def logged_batch(&block)
  statement = Statements::Batch::Logged.new(@options)
  yield(statement) if block_given?
  statement
end

#prepare(statement, options = nil) ⇒ Cassandra::Statements::Prepared

A blocking wrapper around #prepare_async

Parameters:

Returns:

Raises:

See Also:



176
177
178
 
# File 'lib/cassandra/session.rb', line 176

def prepare(statement, options = nil)
  prepare_async(statement, options).get
end

#prepare_async(statement, options = nil) ⇒ Cassandra::Future<Cassandra::Statements::Prepared>

Prepares a given statement and returns a future prepared statement

Parameters:

  • statement (String, Cassandra::Statements::Simple) —

    a statement to prepare

  • options (Hash) (defaults to: nil) —

    (nil) a customizable set of options

Options Hash (options):

  • :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, Symbol) — default: nil —

    name of Execution::Profile from which to obtain certain query options. Defaults to the cluster's default execution profile.

Returns:



148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/cassandra/session.rb', line 148

def prepare_async(statement, options = nil)
  options = merge_execution_options(options)

  case statement
  when ::String
    @client.prepare(statement, options)
  when Statements::Simple
    @client.prepare(statement.cql, options)
  else
    @futures.error(::ArgumentError.new("unsupported statement #{statement.inspect}"))
  end
rescue => e
  @futures.error(e)
end

#unlogged_batch {|batch| ... } ⇒ Statements::Batch

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

Yield Parameters:

Returns:



195
196
197
198
199
 
# File 'lib/cassandra/session.rb', line 195

def unlogged_batch
  statement = Statements::Batch::Unlogged.new(@options)
  yield(statement) if block_given?
  statement
end