You're viewing documentation for a previous version of Scylla Python Driver. Switch to the latest stable version.
Since 3.21.0, scylla-driver fully supports DataStax products. dse-driver and dse-graph users should now migrate to scylla-driver to benefit from latest bug fixes and new features. The upgrade to this new unified driver version is straightforward with no major API changes.
Only the scylla-driver package should be installed. dse-driver and dse-graph are not required anymore:
pip install scylla-driver
If you need the Graph Fluent API (features provided by dse-graph):
pip install scylla-driver[graph]
See Installation for more details.
There is no dse module, so you should import from the cassandra module. You need to change only the first module of your import statements, not the submodules.
from dse.cluster import Cluster, EXEC_PROFILE_GRAPH_DEFAULT from dse.auth import PlainTextAuthProvider from dse.policies import WhiteListRoundRobinPolicy # becomes from cassandra.cluster import Cluster, EXEC_PROFILE_GRAPH_DEFAULT from cassandra.auth import PlainTextAuthProvider from cassandra.policies import WhiteListRoundRobinPolicy
Also note that the cassandra.hosts module doesn’t exist in scylla-driver. This module is named cassandra.pool.
dse-graph features are now built into scylla-driver. The only change you need to do is your import statements:
from dse_graph import .. from dse_graph.query import .. # becomes from cassandra.datastax.graph.fluent import .. from cassandra.datastax.graph.fluent.query import ..
Although it is not common to use this API with positional arguments, it is important to be aware that the host and execute_as parameters have had their positional order swapped. This is only because execute_as was added in dse-driver before host.
These changes are optional, but recommended:
Importing from cassandra.graph is deprecated. Consider importing from cassandra.datastax.graph.
DefaultLoadBalancingPolicy instead of DSELoadBalancingPolicy.
Version 3.0 of the DataStax Python driver for Apache Cassandra adds support for Cassandra 3.0 while maintaining support for previously supported versions. In addition to substantial internal rework, there are several updates to the API that integrators will need to consider:
Previous value was
ONE. The new value is introduced to mesh with the default
DC-aware load balancing policy and to match other drivers.
Previously results would be returned as a
list of rows for result rows
PagedResult afterward. This could break
application code that assumed one type and got another.
Now, all results are returned as an iterable
The preferred way to consume results of unknown size is to iterate through them, letting automatic paging occur as they are consumed.
results = session.execute("SELECT * FROM system.local") for row in results: process(row)
If the expected size of the results is known, it is still possible to materialize a list using the iterator:
results = session.execute("SELECT * FROM system.local") row_list = list(results)
For backward compatibility,
ResultSet supports indexing. When
accessed at an index, a ~.ResultSet object will materialize all its pages:
results = session.execute("SELECT * FROM system.local") first_result = results # materializes results, fetching all pages
This can send requests and load (possibly large) results into memory, so ~.ResultSet will log a warning on implicit materialization.
Previously trace data was attached to Statements if tracing was enabled. This could lead to confusion if the same statement was used for multiple executions.
Now, trace data is associated with the
returned for each query:
BoundStatement.bind() would raise if a mapping
was passed with extra names not found in the prepared statement.
Behavior in 3.0+ is to ignore extra names.
Previously the driver had a soft dependency on
blist sortedset, using
that where available and using an internal fallback where possible.
Now, the driver never chooses the
blist variant, instead returning the
util.SortedSet for all
set results. The class implements
all standard set operations, so no integration code should need to change unless
it explicitly checks for
Cassandra 3.0 brought a substantial overhaul to the internal schema metadata representation. This version of the driver supports that metadata in addition to the legacy version. Doing so also brought some changes to the metadata model.
The present API is documented:
cassandra.metadata. Changes highlighted below:
All types are now exposed as CQL types instead of types derived from the internal server implementation
Some metadata attributes have changed names to match current nomenclature (for example,
Index.kind in place of
Some metadata attributes removed
TableMetadata.keyspace reference replaced with
ColumnMetadata.index is removed table- and keyspace-level mappings are still maintained
ResponseFuture.result timeout parameter is removed, use
Session.execute timeout instead (031ebb0)
Cluster.refresh_schema removed, use
Cluster.refresh_*_metadata instead (419fcdf)
Cluster.submit_schema_refresh removed (574266d)
cqltypes time/date functions removed, use
util entry points instead (bb984ee)
decoder module removed (e16a073)
TableMetadata.keyspace attribute replaced with
cqlengine.columns.TimeUUID.from_datetime removed, use
util variant instead (96489cc)
cqlengine.columns.Float(double_precision) parameter removed, use
columns.Double instead (a2d3a98)
cqlengine keyspace management functions are removed in favor of the strategy-specific entry points (4bd5909)
cqlengine.Model.__polymorphic_*__ attributes removed, use
__discriminator* attributes instead (9d98c8e)
cqlengine.statements will no longer warn about list list prepend behavior (79efe97)
Version 2.1 of the DataStax Python driver for Apache Cassandra adds support for Cassandra 2.1 and version 3 of the native protocol.
Cassandra 1.2, 2.0, and 2.1 are all supported. However, 1.2 only supports protocol version 1, and 2.0 only supports versions 1 and 2, so some features may not be available.
By default, the driver will attempt to use version 2 of the
native protocol. To use version 3, you must explicitly
from cassandra.cluster import Cluster cluster = Cluster(protocol_version=3)
Note that protocol version 3 is only supported by Cassandra 2.1+.
In future releases, the driver may default to using protocol version 3.
Cassandra 2.1 introduced the ability to define new types:
USE KEYSPACE mykeyspace; CREATE TYPE address (street text, city text, zip int);
The driver generally expects you to use instances of a specific
class to represent column values of this type. You can let the
driver know what class to use with
cluster = Cluster() class Address(object): def __init__(self, street, city, zipcode): self.street = street self.city = text self.zipcode = zipcode cluster.register_user_type('mykeyspace', 'address', Address)
When inserting data for
address columns, you should pass in
Address. When querying data,
values will be instances of
If no class is registered for a user-defined type, query results
will use a
namedtuple class and data may only be inserted
though prepared statements.
See User Defined Types for more details.
Starting with version 2.1 of the driver, it is possible to customize
how Python types are converted to CQL literals when working with
non-prepared statements. This is done on a per-
cluster = Cluster() session = cluster.connect() session.encoder.mapping[tuple] = session.encoder.cql_encode_tuple
See Type Conversions for the table of default CQL literal conversions.
With version 3 of the native protocol, timestamps may be supplied by the client at the protocol level. (Normally, if they are not specified within the CQL query itself, a timestamp is generated server-side.)
protocol_version is set to 3 or higher, the driver
will automatically use client-side timestamps with microsecond precision
Session.use_client_timestamp is changed to
If a timestamp is specified within the CQL query, it will override the
timestamp generated by the driver.
Version 2.0 of the DataStax Python driver for Apache Cassandra includes some notable improvements over version 1.x. This version of the driver supports Cassandra 1.2, 2.0, and 2.1. However, not all features may be used with Cassandra 1.2, and some new features in 2.1 are not yet supported.
By default, the driver will attempt to use version 2 of Cassandra’s native protocol. You can explicitly set the protocol version to 2, though:
from cassandra.cluster import Cluster cluster = Cluster(protocol_version=2)
When working with Cassandra 1.2, you will need to
explicitly set the
protocol_version to 1:
from cassandra.cluster import Cluster cluster = Cluster(protocol_version=1)
Version 2 of the native protocol adds support for automatic query paging, which can make dealing with large result sets much simpler.
See Paging Large Queries for full details.
With version 1 of the native protocol, batching of statements required using a BATCH cql query. With version 2 of the native protocol, you can now batch statements at the protocol level. This allows you to use many different prepared statements within a single batch.
BatchStatement for details and usage examples.
Also new in version 2 of the native protocol is SASL-based authentication. See the section on Security for details and examples.
In order to fix some issues around garbage collection and unclean interpreter
shutdowns, version 2.0 of the driver requires you to call
Cluster objects when you are through with them.
This helps to guarantee a clean shutdown.
The following functions have moved from
The original functions have been left in place with a
The following dependencies have officially been made optional:
And one new dependency has been added (to enable Python 3 support):
cassandra- Exceptions and Enums
cassandra.cluster- Clusters and Sessions
cassandra.policies- Load balancing and Failure Handling Policies
cassandra.graph- Graph Statements, Options, and Row Factories
cassandra.metadata- Schema and Ring Topology
cassandra.metrics- Performance Metrics
cassandra.query- Prepared Statements, Batch Statements, Tracing, and Row Factories
cassandra.pool- Hosts and Connection Pools
cassandra.protocol- Protocol Features
cassandra.encoder- Encoders for non-prepared Statements
cassandra.decoder- Data Return Formats
cassandra.concurrent- Utilities for Concurrent Statement Execution
cassandra.connection- Low Level Connection Info
cassandra.timestamps- Timestamp Generation
gevent-compatible Event Loop
cassandra.io.twistedreactor- Twisted Event Loop
cassandra.cqlengine.models- Table models for object mapping
cassandra.cqlengine.columns- Column types for object mapping models
cassandra.cqlengine.query- Query and filter model objects
cassandra.cqlengine.connection- Connection management for cqlengine
cassandra.cqlengine.management- Schema management for cqlengine
cassandra.cqlengine.usertype- Model classes for User Defined Types
cassandra.datastax.graph- Graph Statements, Options, and Row Factories
On this page