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 DataStax Enterprise C# Driver can be used solely with DataStax Enterprise. Please consult the license.

Installation

Get it on Nuget

PM> Install-Package Dse

Build status Windows Build status Latest stable on Nuget.org

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);
Vertex vertex = rs.First();
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 essentially an enumerable of GraphNode:

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

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

GraphNode represent a response item returned by the server. You can cast the result to a specific type as it implements implicit conversion operators to Vertex, Edge and Path:

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

// Iterating as Vertex
foreach (Vertex vextex in rs)
{
    Console.WriteLine(vertex.Label);
}

GraphNode also provides conversion methods for scalar values like ToDouble(), ToInt32() and ToString():

GraphNode r = session.ExecuteGraph(new SimpleGraphStatement("g.V().count()")).First();
Console.WriteLine("The graph has {0} vertices.", r.ToInt32());

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);

License

© DataStax, Inc.

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