Class: Cql::Client::PreparedStatement

Inherits:
Object
  • Object
show all
Defined in:
lib/cql/client/prepared_statement.rb

Overview

A prepared statement are CQL queries that have been sent to the server to be precompiled, so that when executed only their ID and not the whole CQL string need to be sent. They support bound values, or placeholders for values.

Using a prepared statement for any query that you execute more than once is highly recommended. Besides the benefit of having less network overhead, and less processing overhead on the server side, they don't require you to build CQL strings and escape special characters, or format non-character data such as UUIDs, different numeric types, or collections, in the correct way.

You should only prepare a statement once and reuse the prepared statement object every time you want to execute that particular query. The statement object will make sure that it is prepared on all connections, and will (lazily, but transparently) make sure it is prepared on any new connections.

It is an anti-pattern to prepare the same query over and over again. It is bad for performance, since every preparation requires a roundtrip to all connected servers, and because of some bookeeping that is done to support automatic preparation on new connections, it will lead to unnecessary extra memory usage. There is no performance benefit in creating multiple prepared statement objects for the same query.

Prepared statement objects are completely thread safe and can be shared across all threads in your application.

See Also:

  • Client#prepare

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#metadata ⇒ ResultMetadata (readonly)

Metadata describing the bound values

Returns:



37
38
39
 
# File 'lib/cql/client/prepared_statement.rb', line 37

def metadata
  @metadata
end

#result_metadata ⇒ ResultMetadata (readonly)

Metadata about the result (i.e. rows) that is returned when executing this prepared statement.

Returns:



43
44
45
 
# File 'lib/cql/client/prepared_statement.rb', line 43

def result_metadata
  @result_metadata
end

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 Cql::Client::PreparedStatementBatch#execute is called.

The batch yielded or returned by this method is not identical to the regular batch objects yielded or returned by Client#batch. These prepared statement batch objects can be used only to add multiple executions of the same prepared statement.

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.

Examples:

Executing a prepared statement in a batch

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

Parameters:

  • type (Symbol) (defaults to: :logged) —

    the type of batch, must be one of :logged, :unlogged and :counter. The precise meaning of these is defined in the CQL specification.

Yield Parameters:

Returns:

See Also:



125
126
 
# File 'lib/cql/client/prepared_statement.rb', line 125

def batch(type=:logged, options={})
end

#execute(*args) ⇒ nil, ...

Execute the prepared statement with a list of values to be bound to the statements parameters.

The number of arguments must equal the number of bound parameters. You can also specify options as the last argument, or a symbol as a shortcut for just specifying the consistency.

Because you can specify options, or not, there is an edge case where if the last parameter of your prepared statement is a map, and you forget to specify a value for your map, the options will end up being sent to Cassandra. Most other cases when you specify the wrong number of arguments should result in an ArgumentError or TypeError being raised.

Examples:

Preparing and executing an INSERT statement

statement = client.prepare(%(INSERT INTO metrics (id, time, value) VALUES (?, NOW(), ?)))
statement.execute(1234, 23432)
statement.execute(2345, 34543, tracing: true)
statement.execute(3456, 45654, consistency: :one)

Preparing and executing a SELECT statement

statement = client.prepare(%(SELECT * FROM metrics WHERE id = ? AND time > ?))
result = statement.execute(1234, Time.now - 3600)
result.each do |row|
  p row
end

Parameters:

  • args (Array) —

    the values for the bound parameters, and an optional hash of options as last argument – see Client#execute for details on which options are available.

Returns:

Raises:

  • (ArgumentError) —

    raised when number of argument does not match the number of parameters needed to be bound to the statement.

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



86
87
 
# File 'lib/cql/client/prepared_statement.rb', line 86

def execute(*args)
end