cassandra.query - Prepared Statements, Batch Statements, Tracing, and Row Factories

Returns each row as a tuple

Example:

>>> from cassandra.query import tuple_factory
>>> session = cluster.connect('mykeyspace')
>>> session.row_factory = tuple_factory
>>> rows = session.execute("SELECT name, age FROM users LIMIT 1")
>>> print(rows[0])
('Bob', 42)

Returns each row as a namedtuple. This is the default row factory.

Example:

>>> from cassandra.query import named_tuple_factory
>>> session = cluster.connect('mykeyspace')
>>> session.row_factory = named_tuple_factory
>>> rows = session.execute("SELECT name, age FROM users LIMIT 1")
>>> user = rows[0]

>>> # you can access field by their name:
>>> print("name: %s, age: %d" % (user.name, user.age))
name: Bob, age: 42

>>> # or you can access fields by their position (like a tuple)
>>> name, age = user
>>> print("name: %s, age: %d" % (name, age))
name: Bob, age: 42
>>> name = user[0]
>>> age = user[1]
>>> print("name: %s, age: %d" % (name, age))
name: Bob, age: 42

Returns each row as a dict.

Example:

>>> from cassandra.query import dict_factory
>>> session = cluster.connect('mykeyspace')
>>> session.row_factory = dict_factory
>>> rows = session.execute("SELECT name, age FROM users LIMIT 1")
>>> print(rows[0])
{u'age': 42, u'name': u'Bob'}

Like dict_factory(), but returns each row as an OrderedDict, so the order of the columns is preserved.

Creates and returns a BoundStatement instance using values.

See BoundStatement.bind() for rules on input values.

The PreparedStatement instance that this was created from.

The sequence of values that were bound to the prepared statement.

Binds a sequence of values for the prepared statement parameters and returns this instance. Note that values must be:

• a sequence, even if you are only binding one value, or

• a dict that relates 1-to-1 between dict keys and columns

• short sequences will be extended to match bind parameters with UNSET_VALUE

• names may be omitted from a dict with UNSET_VALUE implied.

The partition_key portion of the primary key, which can be used to determine which nodes are replicas for the query.

If the partition key is a composite, a list or tuple must be passed in. Each key component should be in its packed (binary) format, so all components should be strings.

An instance of a cassandra.policies.RetryPolicy or one of its subclasses. This controls when a query will be retried and how it will be retried.

The ConsistencyLevel to be used for this operation. Defaults to None, which means that the default consistency level for the Session this is executed in will be used.

How many rows will be fetched at a time. This overrides the default of Session.default_fetch_size

This only takes effect when protocol version 2 or higher is used. See Cluster.protocol_version for details.

The string name of the keyspace this query acts on. This is used when TokenAwarePolicy is configured in the profile load balancing policy.

It is set implicitly on BoundStatement, and BatchStatement, but must be set explicitly on SimpleStatement.

Custom Payloads to be passed to the server.

These are only allowed when using protocol version 4 or higher.

Flag indicating whether this statement is safe to run multiple times in speculative execution.

The partition_key portion of the primary key, which can be used to determine which nodes are replicas for the query.

If the partition key is a composite, a list or tuple must be passed in. Each key component should be in its packed (binary) format, so all components should be strings.

The serial consistency level is only used by conditional updates (INSERT, UPDATE and DELETE with an IF condition). For those, the serial_consistency_level defines the consistency level of the serial phase (or “paxos” phase) while the normal consistency_level defines the consistency for the “learn” phase, i.e. what type of reads will be guaranteed to see the update right away. For example, if a conditional write has a consistency_level of QUORUM (and is successful), then a QUORUM read is guaranteed to see that write. But if the regular consistency_level of that write is ANY, then only a read with a consistency_level of SERIAL is guaranteed to see it (even a read with consistency ALL is not guaranteed to be enough).

The serial consistency can only be one of SERIAL or LOCAL_SERIAL. While SERIAL guarantees full linearizability (with other SERIAL updates), LOCAL_SERIAL only guarantees it in the local data center.

The serial consistency level is ignored for any query that is not a conditional update. Serial reads should use the regular consistency_level.

Serial consistency levels may only be used against Cassandra 2.0+ and the protocol_version must be set to 2 or higher.

See Lightweight Transactions (Compare-and-set) for a discussion on how to work with results returned from conditional statements.

Specifies an unset value when binding a prepared statement.

Unset values are ignored, allowing prepared statements to be used without specify

See https://issues.apache.org/jira/browse/CASSANDRA-7304 for further details on semantics.

Only valid when using native protocol v4+

The same as Statement.serial_consistency_level, but is only supported when using protocol version 3 or higher.

The BatchType for the batch operation. Defaults to BatchType.LOGGED.

This is a convenience method to clear a batch statement for reuse.

Note: it should not be used concurrently with uncompleted execution futures executing the same BatchStatement.

Adds a Statement and optional sequence of parameters to be used with the statement to the batch.

Like with other statements, parameters must be a sequence, even if there is only one item.

Adds a sequence of Statement objects and a matching sequence of parameters to the batch. Statement and parameter sequences must be of equal length or one will be truncated. None can be used in the parameters position where are needed.

Atomic batch operation.

Non-atomic batch operation.

Batches of counter operations.

A string that very generally describes the traced operation.

A datetime.timedelta measure of the duration of the query.

The IP address of the client that issued this request

This is only available when using Cassandra 2.2+

The IP address of the host that acted as coordinator for this request.

A dict of parameters for the traced operation, such as the specific query string.

A UTC datetime.datetime object describing when the operation was started.

A chronologically sorted list of TraceEvent instances representing the steps the traced operation went through. This corresponds to the rows in system_traces.events for this tracing session.

uuid.UUID unique identifier for this tracing session. Matches the session_id column in system_traces.sessions and system_traces.events.

Retrieves the actual tracing details from Cassandra and populates the attributes of this instance. Because tracing details are stored asynchronously by Cassandra, this may need to retry the session detail fetch. If the trace is still not available after max_wait seconds, TraceUnavailable will be raised; if max_wait is None, this will retry forever.

wait_for_complete=False bypasses the wait for duration to be populated. This can be used to query events from partial sessions.

query_cl specifies a consistency level to use for polling the trace tables, if it should be different than the session default.

A brief description of the event.

A UTC datetime.datetime marking when the event occurred.

The IP address of the node this event occurred on.

A datetime.timedelta measuring the amount of time until this event occurred starting from when source first received the query.

The name of the thread that this event occurred on.