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

cassandra-client

v0.15.2

Published

Node.js CQL driver for Apache Cassandra

Downloads

139

Readme

node-cassandra-client

node-cassandra-client is a Node.js CQL 2 driver for Apache Cassandra 0.8 and later.

CQL is a query language for Apache Cassandra. You use it in much the same way you would use SQL for a relational database. The Cassandra documentation can help you learn the syntax.

node-cassandra-client and Apache Cassandra 1.2.x

Since 0.14.1, the client supports Apache Cassandra 1.2.x in CQL 2 compatibility mode.

By default Cassandra 1.2.x uses CQL 3 so you need to turn the CQL 2 compatibility mode on by passing 'cql_version': '2.0.0' attribute to Connection / PooledConnection constructor in the options object.

Explicitly setting CQL version on a connection is only supported from Apache Cassandra 1.1 and above so you should only set it if you are using version 1.1 or above.

For example:

var conn = new Connection({'host': host, 'port': port, 'keyspace': 'Keyspace1', 'cql_version': '2.0.0'});
var pool = new PooledConnection({'hosts': hosts, 'keyspace': 'Keyspace1', 'cql_version': '2.0.0'});

Creating column families using cqlsh

If you use cqlsh which ships with Cassandra 1.2.x or a newer version of cqlsh which defaults to CQL 3 you need to pass -2 argument to it, otherwise the client won't be able to read column family definitions (#67).

For example:

cqlsh -2 localhost 9160 < my_file.cql

Installation

$ npm install cassandra-client

Build status

Build Status

Running Tests and Lint

npm run-script test
npm run-script lint

License

node-cassandra-client is distributed under the Apache license.

lib/bigint.js is borrowed from the Node.js source (which comes from the V8 source).

Using It

Access the System keyspace

var System = require('cassandra-client').System;
var sys = new System('127.0.0.1:9160');

sys.describeKeyspace('Keyspace1', function(err, ksDef) {
  if (err) {
    // this code path is executed if the key space does not exist.
  } else {
    // assume ksDef contains a full description of the keyspace (uses the thrift structure).
  }
});

Create a keyspace

sys.addKeyspace(ksDef, function(err) {
  if (err) {
    // there was a problem creating the keyspace.
  } else {
    // keyspace was successfully created.
  }
});

Updating

This example assumes you have strings for keys, column names and values:

var Connection = require('cassandra-client').Connection;
var con = new Connection({host:'cassandra-host', port:9160, keyspace:'Keyspace1', user:'user', pass:'password'});
con.connect(function(err, con) {
  if (err) {
    // Failed to establish connection.
    throw err;
  }

  con.execute('UPDATE Standard1 SET ?=? WHERE key=?', ['cola', 'valuea', 'key0'], function(err) {
      if (err) {
          // handle error
      } else {
          // handle success.
      }
  });
});

The Connection constructor accepts the following properties:

host:        cassandra host
port:        cassandra port
keyspace:    cassandra keyspace
user:        [optional] cassandra user
pass:        [optional] cassandra password
use_bigints: [optional] boolean. toggles whether or not BigInteger or Number instances are in results.
timeout:     [optional] number. Connection timeout. Defaults to 4000ms.
log_time:    [optional] boolean. Log execution time for all the queries.

Getting data

NOTE: You'll only get ordered and meaningful results if you are using an order-preserving partitioner. Assume the updates have happened previously.

  con.execute('SELECT ? FROM Standard1 WHERE key >= ? and key <= ?', ['cola', 'key0', 'key1'], function (err, rows) {
    if (err) {
      // handle error
    } else {
      console.log(rows.rowCount());
      console.log(rows[0]);
                        assert.strictEqual(rows[0].colCount(), 1);
                        assert.ok(rows[0].colHash['cola']);
                        assert.ok(rows[0].cols[0].name === 'cola');
                        assert.ok(rows[0].cols[0].value === 'valuea');
    }
  });

Pooled Connections

// Creating a new connection pool.
var PooledConnection = require('cassandra-client').PooledConnection;
var hosts = ['host1:9160', 'host2:9170', 'host3', 'host4'];
var connection_pool = new PooledConnection({'hosts': hosts, 'keyspace': 'Keyspace1'});

PooledConnection() accepts an objects with these slots:

     hosts : String list in host:port format. Port is optional (defaults to 9160).
  keyspace : Name of keyspace to use.
      user : User for authentication (optional).
      pass : Password for authentication (optional).
   maxSize : Maximum number of connection to pool (optional).
idleMillis : Idle connection timeout in milliseconds (optional).
use_bigints: boolean indicating whether or not to use BigInteger or Number in numerical results.
timeout:   : [optional] number. Connection timeout. Defaults to 4000ms.
log_time   : [optional] boolean. Log execution time for all the queries.
             Timing is logged to 'node-cassandra-client.driver.timing' route. Defaults to false.

Queries are performed using the execute() method in the same manner as Connection, (see above). For example:

// Writing
connection_pool.execute('UPDATE Standard1 SET ?=? WHERE KEY=?', ['A', '1', 'K'],
  function(err) {
    if (err) console.log("failure");
    else console.log("success");
  }
);

// Reading
connection_pool.execute('SELECT ? FROM Standard1 WHERE KEY=?', ['A', 'K'],
  function(err, row) {
    if (err) console.log("lookup failed");
    else console.log("got result " + row.cols[0].value);
  }
);

When you are finished with a PooledConnection instance, call shutdown(callback). Shutting down the pool prevents further work from being enqueued, and closes all open connections after pending requests are complete.

// Shutting down a pool
connection_pool.shutdown(function() { console.log("connection pool shutdown"); });

Logging

Instances of Connection() and PooledConnection() are EventEmitter's and emit log events:

var Connection = require('cassandra-client').Connection;
var con = new Connection({host:'cassandra-host', port:9160, keyspace:'Keyspace1', user:'user', pass:'password'});
con.on('log', function(level, message, obj) {
  console.log('log event: %s -- %j', level, message);
});

The level being passed to the listener can be one of debug, info, warn, error, timing and cql. The message is a string and obj is an object that provides more detailed information.

Regenerating Thrift Definition Files

To regenerate Thrift definition files you need to have thrift compiler installed. You can find information on how to do that on the Thrift website.

git clone git://github.com/apache/cassandra.git
cd cassandra/interface
thrift --gen js:node cassandra.thrift

Things you should know about

Numbers

The Javascript Number type doesn't match up well with the java longs and integers stored in Cassandra. Therefore all numbers returned in queries are BigIntegers. This means that you need to be careful when you do updates. If you're worried about losing precision, specify your numbers as strings and use the BigInteger library.

Decoding

node-cassandra-client supports Cassandra BytesType, IntegerType, LongTime and TimeUUIDType out of the box. When dealing with numbers, the values you retreive out of rows will all be BigIntegers (be wary of losing precision if your numbers are bigger than 2^53--you know, like a timestamp).

BigInteger supports many operations like add, subtract, multiply, etc., and a few others that may come in handy: shift, square, abs, etc. Check the source if you'd like to know more.

We technically have a UUID type, but have not had the need to flesh it out yet. If you find the need to expose more parts of the UUID (timestamp, node, clock sequence, etc.), or would like to implement some operations, patches are welcome.

Todo

  • Full BigInteger documentation.