The consistency level used for a query determines how many of the replicas of the data you are interacting with need to respond for the query to be considered a success.
By default, ConsistencyLevel.LOCAL_ONE
will be used for all queries. You can specify a different default for the session on Session.default_consistency_level
if the cluster is configured in legacy mode (not using execution profiles). Otherwise this can be done by setting the ExecutionProfile.consistency_level
for the execution profile with key EXEC_PROFILE_DEFAULT
. To specify a different consistency level per request, wrap queries in a SimpleStatement
:Copy
from cassandra import ConsistencyLevel
from cassandra.query import SimpleStatement
query = SimpleStatement(
"INSERT INTO users (name, age) VALUES (%s, %s)",
consistency_level=ConsistencyLevel.QUORUM)
session.execute(query, ('John', 42))
Prepared Statements
Prepared statements are queries that are parsed by Cassandra and then saved for later use. When the driver uses a prepared statement, it only needs to send the values of parameters to bind. This lowers network traffic and CPU utilization within Cassandra because Cassandra does not have to re-parse the query each time.
To prepare a query, use Session.prepare()
:Copy
user_lookup_stmt = session.prepare("SELECT * FROM users WHERE user_id=?")
users = []
for user_id in user_ids_to_query:
user = session.execute(user_lookup_stmt, [user_id])
users.append(user)
prepare()
returns a PreparedStatement
instance which can be used in place of SimpleStatement
instances or literal string queries. It is automatically prepared against all nodes, and the driver handles re-preparing against new nodes and restarted nodes when necessary.
Note that the placeholders for prepared statements are ?
characters. This is different than for simple, non-prepared statements (although future versions of the driver may use the same placeholders for both).
Setting a Consistency Level with Prepared Statements
To specify a consistency level for prepared statements, you have two options.
The first is to set a default consistency level for every execution of the prepared statement:Copy
from cassandra import ConsistencyLevel
cluster = Cluster()
session = cluster.connect("mykeyspace")
user_lookup_stmt = session.prepare("SELECT * FROM users WHERE user_id=?")
user_lookup_stmt.consistency_level = ConsistencyLevel.QUORUM
# these will both use QUORUM
user1 = session.execute(user_lookup_stmt, [user_id1])[0]
user2 = session.execute(user_lookup_stmt, [user_id2])[0]
The second option is to create a BoundStatement
from the PreparedStatement
and binding parameters and set a consistency level on that:Copy
# override the QUORUM default
user3_lookup = user_lookup_stmt.bind([user_id3])
user3_lookup.consistency_level = ConsistencyLevel.ALL
user3 = session.execute(user3_lookup)
ConsistencyLevel
Spcifies how many replicas must respond for an operation to be considered a success. By default, ONE
is used for all operations.
Attributes
ANY
= 0
Only requires that one replica receives the write or the coordinator stores a hint to replay later. Valid only for writes.
ONE
= 1
Only one replica needs to respond to consider the operation a success
TWO
= 2
Two replicas must respond to consider the operation a success
THREE
= 3
Three replicas must respond to consider the operation a success
QUORUM
= 4
ceil(RF/2)
replicas must respond to consider the operation a success
ALL
= 5
All replicas must respond to consider the operation a success
LOCAL_QUORUM
= 6
Requires a quorum of replicas in the local datacenter
EACH_QUORUM
= 7
Requires a quorum of replicas in each datacenter
SERIAL
= 8
For conditional inserts/updates that utilize Cassandra’s lightweight transactions, this requires consensus among all replicas for the modified data.
LOCAL_SERIAL
= 9
Like SERIAL
, but only requires consensus among replicas in the local datacenter.
LOCAL_ONE
= 10
Sends a request only to replicas in the local datacenter and waits for one response.