dse-driver

DataStax Enterprise Node.js Driver

This driver is built on top of Node.js CQL driver for Apache Cassandra and provides the following additions for DataStax Enterprise:

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

The DataStax Enterprise Node.js Driver can be used solely with DataStax Enterprise. Please consult the license.

Installation

npm install dse-driver

Documentation

• Documentation index
• API docs
• FAQ

Getting Help

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

Getting Started

Client inherits from the CQL driver counterpart Client. All CQL features available to Client (see the CQL driver manual) can also be used with Client.

const dse = require('dse-driver');
const client = new dse.Client({ contactPoints: ['h1', 'h2'], keyspace: 'ks1'});
const query = 'SELECT email, last_name FROM user_profiles WHERE key=?';
client.execute(query, ['guy'], function(err, result) {
  assert.ifError(err);
  console.log('got user profile with email ' + result.rows[0].email);
});

Additionally, the dse module exports the submodules from the CQL driver, so you just need to import one module to access all DSE and Cassandra types.

For example:

const dse = require('dse-driver');
const Uuid = dse.types.Uuid;

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 a cluster:

const dse = require('dse-driver');
const client = new dse.Client({
  contactPoints: ['h1', 'h2'], 
  keyspace: 'ks1',
  authProvider: new dse.auth.DseGssapiAuthProvider()
});

See the jsdoc of each implementation for more details.

Graph

Client includes the executeGraph() method to execute graph queries:

const client = new dse.Client({
  contactPoints: ['h1', 'h2'],
  graphOptions: { name: 'demo' }
});
client.executeGraph('g.V()', function (err, result) {
  assert.ifError(err);
  const vertex = result.first();
  console.log(vertex.label);
});

Graph Options

You can set default graph options when initializing Client which will be used for all graph statements. For example, to avoid providing a graphName option in each executeGraph() call:

const dse = require('dse-driver');
const client = new dse.Client({
  contactPoints: ['h1', 'h2'],
  graphOptions: { name: 'demo' }
});

These options may be overridden by providing them in the options parameter of executeGraph:

// Use a different graph name than the one provided when creating the client instance
client.executeGraph(query, params, { graphName: 'demo2'}, function (err, result) {
  assert.ifError(err);
  const vertex = result.first();
  console.log(vertex.label);
});

Handling Results

Graph queries return a GraphResultSet, which is an iterable of rows. The format of the data returned is dependent on the data requested. For example, the payload representing edges will be different than those that represent vertices using the 'modern' graph:

// Creating the 'modern' graph
const query =
  'Vertex marko = graph.addVertex(label, "person", "name", "marko", "age", 29);\n' +
  'Vertex vadas = graph.addVertex(label, "person", "name", "vadas", "age", 27);\n' +
  'Vertex lop = graph.addVertex(label, "software", "name", "lop", "lang", "java");\n' +
  'Vertex josh = graph.addVertex(label, "person", "name", "josh", "age", 32);\n' +
  'Vertex ripple = graph.addVertex(label, "software", "name", "ripple", "lang", "java");\n' +
  'Vertex peter = graph.addVertex(label, "person", "name", "peter", "age", 35);\n' +
  'marko.addEdge("knows", vadas, "weight", 0.5f);\n' +
  'marko.addEdge("knows", josh, "weight", 1.0f);\n' +
  'marko.addEdge("created", lop, "weight", 0.4f);\n' +
  'josh.addEdge("created", ripple, "weight", 1.0f);\n' +
  'josh.addEdge("created", lop, "weight", 0.4f);\n' +
  'peter.addEdge("created", lop, "weight", 0.2f);';

client.executeGraph(query, function (err) {
  assert.ifError(err);
});

// Handling Edges
client.executeGraph('g.E()', function (err, result) {
  assert.ifError(err);
  result.forEach(function (edge) {
    console.log(edge.id); // [an internal id representing the edge]
    console.log(edge.type); // edge
    console.log(edge.label); // created
    console.log(edge.properties.weight); // 0.4
    console.log(edge.outVLabel); // person
    console.log(edge.outV); // [an id representing the outgoing vertex]
    console.log(edge.inVLabel); // software
    console.log(edge.inV); // [an id representing the incoming vertex]
  });
});

// Using ES6 for...of
client.executeGraph('g.E()', function (err, result) {
  assert.ifError(err);
  for (let edge of result) {
    console.log(edge.label); // created
    // ...
  });
});

// Handling Vertices
client.executeGraph('g.V().hasLabel("person")', function (err, result) {
  assert.ifError(err);
  result.forEach(function(vertex) {
    console.log(vertex.id); // [an internal id representing the vertex]
    console.log(vertex.type); // vertex
    console.log(vertex.label); // person
    console.log(vertex.properties.name[0].value); // marko
    console.log(vertex.properties.age[0].value); // 29
  });
});

Parameters

Unlike CQL queries which support both positional and named parameters, graph queries only support named parameters. As a result of this, parameters must be passed in as an object:

const query = 'g.addV(label, vertexLabel, "name", username)';
client.executeGraph(query, { vertexLabel: 'person', username: 'marko'}, function (err, result) {
  assert.ifError(err);
  const vertex = result.first();
  // ...
});

Parameters are encoded in json, thus will ultimately use their json representation (toJSON if present, otherwise object representation).

You can use results from previous queries as parameters to subsequent queries. For example, if you want to use the id of a vertex returned in a previous query for making a subsequent query:

client.executeGraph('g.V().hasLabel("person").has("name", "marko")', function (err, result) {
  assert.ifError(err);
  const vertex = result.first();
  client.executeGraph('g.V(vertexId).out("knows").values("name")', {vertexId: vertex.id}, function (err, result) {
    assert.ifError(err);
    const names = result.toArray();
    console.log(names); // [ 'vadas', 'josh' ]
  });
});

Prepared graph statements

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

Geospatial types

DSE 5.0 comes with a set of additional CQL 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 encoders and representations of these types in the geometry module that can be used directly as parameters in queries:

const dse = require('dse-driver');
const Point = dse.geometry.Point;
const insertQuery = 'INSERT INTO points_of_interest (name, coords) VALUES (?, ?)';
const selectQuery = 'SELECT coords FROM points_of_interest WHERE name = ?';

client.execute(insertQuery, ['Eiffel Tower', new Point(48.8582, 2.2945)], function (err, result) {
  assert.ifError(err);
  client.execute(selectQuery, ['Eiffel Tower'], function (err, result) {
    assert.ifError(err);
    const row = result.first();
    const point = row['coords'];
    console.log(point instanceof Point); // true
    console.log('x: %d, y: %d', point.x, point.y); // x: 48.8582, y: 2.2945
  });
});

License

Copyright 2016 DataStax

http://www.datastax.com/terms/datastax-dse-driver-license-terms