Ruby DataStax Enterprise Driver

NOTE: The Ruby DataStax Enterprise Driver can be used solely with DataStax Enterprise. Please consult the license.

This driver is built on top of the DataStax Ruby driver for Apache Cassandra and enhanced for the adaptive data management and mixed workload capabilities provided by DSE. Therefore a lot of the underlying concepts are the same.

Documentation

Driver documentation can be found here.

In particular, you’ll find our Features and API sections very enlightening.

Compatibility

This driver works exclusively with the Cassandra Query Language v3 (CQL3), Cassandra’s native protocol, and DataStax Enterprise extensions to that protocol. The current version works with:

  • DataStax Enterprise 4.8 and above.
  • Ruby (MRI) 2.2, 2.3, 2.4
  • JRuby 9k

Note: DataStax products do not support big-endian systems.

Feedback Requested

Help us focus our efforts! Provide your input on the Ruby Driver Platform and Runtime Survey (we kept it short).

If you find an issue, please file an issue in our public JIRA. Please be sure to specify the affects-version (DSE-X.Y.Z).

You can also post questions in our forum.

Features

This driver exposes the following features of DSE 5.0:

Note that this driver is fully compatible with previous versions of DataStax Enterprise.

Installation

The driver is named dse-driver on rubygems.org and can easily be installed with Bundler or the gem program. It will download the appropriate Cassandra driver as well.

Upgrade

The driver is intended to have the same look and feel as the core driver to make upgrading from the core driver trivial. The only change is to replace references to the Cassandra module with Dse when creating the cluster object:

require 'dse'

# This returns a Dse::Cluster instance
cluster = Dse.cluster

# This returns a Dse::Session instance
session = cluster.connect
rs = session.execute('select * from system.local')

Breaking changes in 2.0

This release adds support for graph execution profiles. As a result, the cluster-level graph_options object has been removed. That object is effectively stored in the :default_graph execution profile. However, since execution profiles are read-only, graph options in profiles cannot be manipulated. Instead, either specify new graph options at query execution time, or use separate execution profiles for your different scenarios.

Furthermore, the Dse::Graph::Options class is no longer in the public api. Instead of constructing a Dse::Graph::Options object and passing it to Session.execute_graph*, you must now pass the primitive graph options or specify the name of an execution profile that encapsulates the desired graph options. Similarly, when creating a Dse::Graph::Statement, you must specify primitive graph options instead of a Dse::Graph::Options object.

Since execution profiles are immutable, you must set expert options at construction time with the expert_options hash. See the documentation for more details.

Another behavior change is that in v1.x, graph query timeout defaulted to unlimited. This caused queries to fall back to server timeouts. The default was set this way to accommodate multi-day analytics queries and multi-second OLTP queries without requiring intervention / special handling from the user. The introduction of execution profiles into the driver enables the user to more easily run different types of queries:

# Use the default graph profile with its OLTP-motivated timeout (30 seconds)
rs = session.execute_graph('g.V()')
# Use the default graph analytics profile for an OLAP query (timeout 7 days)
rs = session.execute_graph('g.V()', execution_profile: :default_graph_analytics
# Use the default system query profile for graph system queries (timeout 3 minutes)
rs = session.execute_graph("system.graph('mygraph').exists()",
                           execution_profile: :default_graph_system)

Thus, no query runs with unlimited timeout by default as of this version of the driver.

Finally, in v1.x, graph query timeout was specified via the :timeout option in calls to Session.execute_graph* or packaged up in a graph options object. Since the graph execution profile now assumes the role of graph options, use the :timeout attribute in the graph execution profile to specify graph timeout. In particular, to set the default graph timeout for graph queries, you must define your own :default_graph execution profile that will take precedence over one that would normally be generated by the driver:

cluster = Dse.cluster(execution_profiles: {
    default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph')
})

In the example above, the default graph timeout is set to 17 seconds. Note that you are not permitted to mix primitive options (that are now available in execution profiles) with an execution_profiles hash when creating the cluster object:

# Illegal!
cluster = Dse.cluster(execution_profiles: {
    default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph')
}, timeout: 7)

Thus, in order to specify that non-graph queries should execute with a timeout of 7 seconds by default, you must override the Cassandra default execution profile, named :default:

# Legal.
cluster = Dse.cluster(execution_profiles: {
    default_graph: Dse::Graph::ExecutionProfile.new(timeout: 17, graph_name: 'mygraph'),
    default: Cassandra::Execution::Profile.new(timeout: 7)
})

Determining driver versions

Within a script or irb, you can determine the exact versions of the dse and core drivers by accessing the VERSION constant of the appropriate module:

require 'dse'

puts "Dse Driver Version: #{Dse::VERSION}"
puts "Cassandra Driver Version: #{Cassandra::VERSION}"

Compatibility

Although this driver exposes new features introduced in DSE 5.0, it is fully compatible and supported for use with previous versions of DSE.

License

© DataStax, Inc.

The full license terms are available at http://www.datastax.com/terms/datastax-dse-driver-license-terms