Class: Cql::Client::Client

  • Object
show all
Defined in:


A CQL client manages connections to one or more Cassandra nodes and you use it run queries, insert and update data, prepare statements and switch keyspaces.

To get a reference to a client you call connect. When you don't need the client anymore you can call #close to close all connections.

Internally the client runs an IO reactor in a background thread. The reactor handles all IO and manages the connections to the Cassandra nodes. This makes it possible for the client to handle highly concurrent applications very efficiently.

Client instances are threadsafe and you only need a single instance for in an application. Using multiple instances is more likely to lead to worse performance than better.

Because the client opens sockets, and runs threads it cannot be used by the child created when forking a process. If your application forks (for example applications running in the Unicorn application server or Resque task queue) you must connect after forking.

See Also:

Instance Method Summary collapse

Instance Method Details

#batch(type = :logged, options = {}) {|batch| ... } ⇒ Cql::Client::VoidResult, Cql::Client::Batch

Yields a batch when called with a block. The batch is automatically executed at the end of the block and the result is returned.

Returns a batch when called wihtout a block. The batch will remember the options given and merge these with any additional options given when Batch#execute is called.

Please note that the batch object returned by this method is not thread safe.

The type parameter can be ommitted and the options can then be given as first parameter.


Executing queries in a batch

client.batch do |batch|
  batch.add(%(INSERT INTO metrics (id, time, value) VALUES (1234, NOW(), 23423)))
  batch.add(%(INSERT INTO metrics (id, time, value) VALUES (2346, NOW(), 13)))
  batch.add(%(INSERT INTO metrics (id, time, value) VALUES (2342, NOW(), 2367)))
  batch.add(%(INSERT INTO metrics (id, time, value) VALUES (4562, NOW(), 1231)))

Using the returned batch object

batch = client.batch(:counter, trace: true)
batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 4, 87654)
batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 3, 6572)
result = batch.execute(timeout: 10)
puts result.trace_id

Providing type hints for on-the-fly bound values

batch = client.batch
batch.add('UPDATE counts SET value = value + ? WHERE id = ?', 4, type_hints: [:int])

Yield Parameters:

See Also:

# File 'lib/cql/client/client.rb', line 208


Disconnect from all nodes.

# File 'lib/cql/client/client.rb', line 28

#connected?true, false

Returns whether or not the client is connected.

# File 'lib/cql/client/client.rb', line 34

#execute(cql, *values, options = {}) ⇒ nil, ...

Execute a CQL statement, optionally passing bound values.

When passing bound values the request encoder will have to guess what types to encode the values as. For most types this will be no problem, but for integers and floating point numbers the larger size will be chosen (e.g. BIGINT and DOUBLE and not INT and FLOAT). You can override the guessing with the :type_hint option. Don't use on-the-fly bound values when you will issue the request multiple times, prepared statements are almost always a better choice.

Please note that on-the-fly bound values are only supported by Cassandra 2.0 and above.


A simple CQL query

result = client.execute("SELECT * FROM users WHERE user_name = 'sue'")
result.each do |row|
  p row

Using on-the-fly bound values

client.execute('INSERT INTO users (user_name, full_name) VALUES (?, ?)', 'sue', 'Sue Smith')

Using on-the-fly bound values with type hints

client.execute('INSERT INTO users (user_name, age) VALUES (?, ?)', 'sue', 33, type_hints: [nil, :int])

Specifying the consistency as a symbol

client.execute("UPDATE users SET full_name = 'Sue S. Smith' WHERE user_name = 'sue'", consistency: :one)

Specifying the consistency and other options

client.execute("SELECT * FROM users", consistency: :all, timeout: 1.5)

Loading a big result page by page

result_page = client.execute("SELECT * FROM large_table WHERE id = 'partition_with_lots_of_data'", page_size: 100)
while result_page
  result_page.each do |row|
    p row
  result_page = result_page.next_page

Activating tracing for a query

result = client.execute("SELECT * FROM users", tracing: true)
p result.trace_id

Options Hash (options):

  • :consistency (Symbol) — default: :quorum

    The consistency to use for this query.

  • :serial_consistency (Symbol) — default: nil

    The consistency to use for conditional updates (:serial or :local_serial), see the CQL documentation for the semantics of serial consistencies and conditional updates. The default is assumed to be :serial by the server if none is specified. Ignored for non- conditional queries.

  • :timeout (Integer) — default: nil

    How long to wait for a response. If this timeout expires a TimeoutError will be raised.

  • :trace (Boolean) — default: false

    Request tracing for this request. See QueryResult and VoidResult for how to retrieve the tracing data.

  • :page_size (Integer) — default: nil

    Instead of returning all rows, return the response in pages of this size. The first result will contain the first page, to load subsequent pages use QueryResult#next_page.

  • :type_hints (Array) — default: nil

    When passing on-the-fly bound values the request encoder will have to guess what types to encode the values as. Using this option you can give it hints and avoid it guessing wrong. The hints must be an array that has the same number of arguments as the number of bound values, and each element should be the type of the corresponding value, or nil if you prefer the encoder to guess. The types should be provided as lower case symbols, e.g. :int, :time_uuid, etc.


  • (Cql::NotConnectedError)

    raised when the client is not connected

  • (Cql::TimeoutError)

    raised when a timeout was specified and no response was received within the timeout.

  • (Cql::QueryError)

    raised when the CQL has syntax errors or for other situations when the server complains.

# File 'lib/cql/client/client.rb', line 57


Returns the name of the current keyspace, or nil if no keyspace has been set yet.

# File 'lib/cql/client/client.rb', line 40

#prepare(cql) ⇒ Cql::Client::PreparedStatement

Returns a prepared statement that can be run over and over again with different bound values.


  • (Cql::NotConnectedError)

    raised when the client is not connected

  • (Cql::Io::IoError)

    raised when there is an IO error, for example if the server suddenly closes the connection

  • (Cql::QueryError)

    raised when there is an error on the server side, for example when you specify a malformed CQL query

See Also:

# File 'lib/cql/client/client.rb', line 150

#use(keyspace) ⇒ nil

Changes keyspace by sending a USE statement to all connections.

The the second parameter is meant for internal use only.


# File 'lib/cql/client/client.rb', line 47