npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

dse-driver

v2.3.1

Published

DataStax Enterprise Node.js Driver

Downloads

513

Readme

DataStax Enterprise Node.js Driver

This driver is built on top of Node.js 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

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.

const dse = require('dse-driver');
const client = new dse.Client({ contactPoints: ['host1', 'host2'], localDataCenter: 'datacenter1' });

const query = 'SELECT name, email FROM users WHERE key = ?';
client.execute(query, [ 'someone' ])
  .then(result => console.log('User with email %s', result.rows[0].email));

Along with the rest of asynchronous execution methods in the driver, execute() returns a Promise that can be chained using then() method. On modern JavaScript engines, promises can be awaited upon using the await keyword within async functions.

Alternatively, you can use the callback-based execution for all asynchronous methods of the API by providing a callback as the last parameter.

client.execute(query, [ 'someone' ], function(err, result) {
  assert.ifError(err);
  console.log('User with email %s', result.rows[0].email);
});

In order to have concise code examples in this documentation, we will use the promise-based API of the driver along with the await keyword.

The same submodules structure in the Node.js driver for Apache Cassandra is available in the dse-driver, 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: ['host1', 'host2'],
  profiles: [
    new ExecutionProfile('default', {
      graphOptions: { name: 'demo' }
    })
  ]
});
// executeGraph() method returns a Promise
const result = await client.executeGraph('g.V()');
const vertex = result.first();
console.log(vertex.label);

Graph Options

You can set graph options in execution profiles when initializing Client. Also, to avoid providing the graph name option in each executeGraph() call, you can set the graph options in the default execution profile:

const client = new dse.Client({
  contactPoints: ['host1', 'host2'],
  profiles: [
    new ExecutionProfile('default', {
      graphOptions: { name: 'demo' }
    }),
    new ExecutionProfile('demo2-profile', {
      graphOptions: { name: 'demo2' }
    })
  ]
});
// Execute a traversal on the 'demo' graph
const result = await client.executeGraph(query, params);

If needed, you can specify an execution profile different from the default one:

// Execute a traversal on the 'demo2' graph
client.executeGraph(query, params, { executionProfile: 'demo2-profile'});

Additionally, you can also set the default graph options without using execution profiles (not recommended).

const client = new dse.Client({
  contactPoints: ['host1', 'host2'],
  graphOptions: { name: 'demo' }
});

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

await client.executeGraph(query);
// Handling Edges
const result = await client.executeGraph('g.E()');
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
const result = await client.executeGraph('g.E()');
for (let edge of result) {
  console.log(edge.label); // created
  // ...
}
// Handling Vertices
const result = await client.executeGraph('g.V().hasLabel("person")');
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)';
const result = await client.executeGraph(query, { vertexLabel: 'person', username: 'marko' });
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:

let result = await client.executeGraph('g.V().hasLabel("person").has("name", "marko")');
const vertex = result.first();
result = await client.executeGraph('g.V(vertexId).out("knows").values("name")', { vertexId: vertex.id });
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 = ?';

await client.execute(insertQuery, [ 'Eiffel Tower', new Point(48.8582, 2.2945) ], { prepare: true });
const result = await client.execute(selectQuery, ['Eiffel Tower'], { prepare: true });
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

Logging

Instances of Client are EventEmitter and emit 'log' events:

client.on('log', (level, className, message, furtherInfo) => {
  console.log('%s: %s', level, message);
});

The level values passed to the listener can be verbose, info, warning or error. In production environment, you should filter out verbose log events, that are suitable for debug.

Compatibility

  • DataStax Enterprise versions 4.5 and above.
  • Node.js versions 4 and above.

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

License

© DataStax, Inc.

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