email iconemail phone iconcall

Python Driver 2.5 – with Integrated cqlengine Object Mapper

By Adam Holmberg -  March 30, 2015 | 0 Comments

Version 2.5.0 of the DataStax Python driver for Apache Cassandra is released! A full list of changes can be found in the CHANGELOG. I'll add a little color to some of the headline features listed here:

  • Integrated cqlengine object mapping package
  • Support for upcoming Date and Time Cassandra types
  • Utility functions for converting between TimeUUID and native time representations
  • Randomized metadata fetch windows, with configuration

Welcome cqlengine

The biggest change in this release is the inclusion of cqlengine, a CQL object mapping package for Python. While cqlengine has flourished in its own right as a standalone project, we are happy to continue its development as an integrated package, released with the driver. Continuing development in this way will allow us to reduce redundant work, and devote resources to keeping pace with core driver and Cassandra feature parity. We welcome the continued engagement and contributions by the community that has made this project what it is today.

Upgrading to the integrated cqlengine should be painless and simple. We maintained the existing API and functionality. Most applications will only need to remove the legacy package and update import locations. There is one minor functional change, and a number of deprecations. Anyone upgrading is encouraged to consult the upgrade guide for details.

While efforts were taken to leave most of the existing functionality unchanged, there are a few new features to speak of. Most notably: support for modeling User Defined Types (introduced in Cassandra 2.1). There are also a number of new functions for simplified connection and keyspace management. Please consult the API documentation for further detail.

Stay tuned for forthcoming updates expanding the feature set and improving performance.

New Date and Time Cassandra Types

CASSANDRA-7523 introduces new Date and Time types into an upcoming version of Cassandra. This version of the driver includes support for those new types. Results with these types are returned in new types provided in the cassandra.util module. While these types are similar to datetime.time and built-in, custom types were required to work around limitations in precision (nanosecond for times) and range (outside datetime.[MIN|MAX]YEAR for dates). The new types are described in the API documentation here.

Note: for unprepared statements, the driver previously had an overloaded mapping, encoding dates as timestamps in CQL. That overload is removed in support of date types. Conveniently, date CQL literals are also acceptable timestamps, so this updated mapping should not require any application updates. The following table shows the new type mapping:

Python Type CQL Literal Encoding date
datetime.datetime timestamp
datetime.time time

Time Utility Functions

This release includes a number of utility functions for converting between (type 1) TimeUUID types, and native time representations:


These are described in more detail in the util API documentation.

We've also moved the datetime_from_timestamp function from its previous location in cassandra.cqltypes, to the util module. Although not officially part of the API, the old function remains as a pass-through (deprecated until the next release).

Metadata Refresh Controls

The latest driver includes some new controls for specifying how (or if) cluster metadata is refreshed in response to native protocol events on the control connection. Two new Cluster attributes have been added:

  • schema_event_refresh_window
  • topology_event_refresh_window

This feature will be of most interest to users operating the driver in a high fanout from Cassandra nodes to client instances. Previously, the driver would react to these events at a fixed interval, in effect causing a 'thundering herd' problem as many instances refreshed parts of the metadata at the same time. Now, this reaction is smoothed out by randomizing the interval within a configured window. Additionally, if redundant events arrive inside of that window, the driver is able to de-duplicate refreshes.

Finally, these controls can be used to disable refreshes for one, or both types of events. This may be useful for high-fanout deployments where the pertinent schema is static, or the application is not expected to react to schema changes without restart.

More details on these parameters can be found in the API documentation here.

Wrapping Up

As always, thanks to all who provided contributions and bug reports. The continued involvement of the community is appreciated:

DataStax has many ways for you to advance in your career and knowledge.

You can take free classes, get certified, or read one of our many white papers.

register for classes

get certified

DBA's Guide to NoSQL


Your email address will not be published. Required fields are marked *

Subscribe for newsletter: