DataStax Enterprise C# Driver

This driver is built on top of DataStax C# driver for Apache Cassandra and provides the following additions for DataStax Enterprise:

IAuthenticator implementations that use the authentication scheme negotiation in the server-side DseAuthenticator.
DSE graph integration.
Serializers for geospatial types which integrate seamlessly with the driver.

The driver supports .NET Framework 4.5+ and .NET Core 1+.

The DataStax Enterprise C# Driver can be used solely with DataStax Enterprise. Please consult the license.

Installation

Get it on Nuget

PM> Install-Package Dse

Documentation

Getting Help

You can use the project mailing list or create a ticket on the Jira issue tracker.

Getting Started

IDseCluster and IDseSession extend their CQL driver counterparts, so you can use Dse instances to execute CQL queries.

using Dse;

IDseCluster cluster = DseCluster.Builder()
                                .AddContactPoint("127.0.0.1")
                                .Build();
IDseSession session = cluster.Connect();
Row row = session.Execute("select * from system.local").First();
Console.WriteLine(row.GetValue<string>("cluster_name"));

Authentication

For clients connecting to a DSE cluster secured with DseAuthenticator, two authentication providers are included:

DsePlainTextAuthProvider: plain-text authentication;
DseGssapiAuthProvider: GSSAPI authentication.

To configure a provider, pass it when initializing the cluster:

using Dse;
using Dse.Auth;

IDseCluster dseCluster = DseCluster.Builder()
    .AddContactPoint("127.0.0.1")
    .WithAuthProvider(new DseGssapiAuthProvider())
    .Build();

Graph

IDseSession has dedicated methods to execute graph queries:

using Dse.Graph;

session.ExecuteGraph("system.createGraph('demo').ifNotExist().build()");

GraphStatement s1 = new SimpleGraphStatement("g.addV(label, 'test_vertex')").SetGraphName("demo");
session.ExecuteGraph(s1);

GraphStatement s2 = new SimpleGraphStatement("g.V()").SetGraphName("demo");
GraphResultSet rs = session.ExecuteGraph(s2);

IVertex vertex = rs.First().To<IVertex>();
Console.WriteLine(vertex.Label);

Graph options

You can set default graph options when initializing the cluster. They will be used for all graph statements. For example, to avoid repeating SetGraphName("demo") on each statement:

IDseCluster dseCluster = DseCluster.Builder()
    .AddContactPoint("127.0.0.1")
    .WithGraphOptions(new GraphOptions().SetName("demo"))
    .Build();

If an option is set manually on a GraphStatement, it always takes precedence; otherwise the default option is used. This might be a problem if a default graph name is set, but you explicitly want to execute a statement targeting system, for which no graph name must be set. In that situation, use GraphStatement.SetSystemQuery():

GraphStatement s = new SimpleGraphStatement("system.createGraph('demo').ifNotExist().build()")
    .SetSystemQuery();
session.ExecuteGraph(s);

Query execution

As explained, graph statements can be executed with the session’s ExecuteGraph method. There is also an asynchronous equivalent called ExecuteGraphAsync that returns a Task that can be awaited upon.

Handling results

Graph queries return a GraphResultSet, which is a sequence of GraphNode elements:

GraphResultSet rs = session.ExecuteGraph(new SimpleGraphStatement("g.V()"));

// Iterating as IGraphNode
foreach (IGraphNode r in rs)
{
    Console.WriteLine(r);
}

IGraphNode represents a response item returned by the server. Each item can be converted to the expected type:

GraphResultSet rs = session.ExecuteGraph(new SimpleGraphStatement("g.V()"));
IVertex vertex = rs.First().To<IVertex>();
Console.WriteLine(vertex.Label);

Additionally, you can apply the conversion to all the sequence by using GraphResultSet.To<T>() method:

foreach (IVertex vertex in rs.To<IVertex>())
{
    Console.WriteLine(vertex.Label);
}

GraphNode provides implicit conversion operators to string, int, long and others in order to improve code readability, allowing the following C# syntax:

var rs = session.ExecuteGraph(new SimpleGraphStatement("g.V().has('name', 'marko').values('location')"));
foreach (string location in rs)
{
    Console.WriteLine(location);
}

GraphNode inherits from DynamicObject, allowing you to consume it using the dynamic keyword and/or as a dictionary.

dynamic r = session.ExecuteGraph(new SimpleGraphStatement("g.V()")).First();

Parameters

Graph query parameters are always named. Parameter bindings are passed as an anonymous type or as a IDictionary<string, object> alongside the query:

session.ExecuteGraph("g.addV(label, vertexLabel)", new { vertexLabel = "test_vertex_2" });

Note that, unlike in CQL, Gremlin placeholders are not prefixed with “:”.

Prepared statements

Prepared graph statements are not supported by DSE Graph yet (they will be added in the near future).

Geospatial types

DSE 5 comes with a set of additional types to represent geospatial data: PointType, LineStringType and PolygonType:

cqlsh> CREATE TABLE points_of_interest(name text PRIMARY KEY, coords 'PointType');
cqlsh> INSERT INTO points_of_interest (name, coords) VALUES ('Eiffel Tower', 'POINT(48.8582 2.2945)');

The DSE driver includes C# representations of these types, that can be used directly in queries:

using Dse.Geometry;

Row row = session.Execute("SELECT coords FROM points_of_interest WHERE name = 'Eiffel Tower'").First();
Point coords = row.GetValue<Point>("coords");

var statement = new SimpleStatement("INSERT INTO points_of_interest (name, coords) VALUES (?, ?)",
    "Washington Monument", 
    new Point(38.8895, 77.0352));
session.Execute(statement);

Compatibility

DataStax Enterprise versions 4.5 and above.
.NET Framework versions 4.5 and above and .NET Core versions 1.0 and above.

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

License

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