kunalgolani/cassandra-co

A very basic ORM and Client for Cassandra, inspired by 3logic's apollo-cassandra

cassandra-co

A very basic ORM and Client for Cassandra, inspired by 3logic's apollo-cassandra.

---

Motivation

• apollo-cassandra and other node.js Cassandra ORMs require you to define the schema in code. This means that any time the DB schema is altered, the code also needs to be updated. The code needs to be aware of the schema in the DB even if it's not otherwise using all columns of a table.
• When I looked into the internals of apollo-cassandra before starting this project, I couldn't find evidence of it using prepared statements. With Cassandra, if you're executing the same CQL query with different paramters repeatedly, preparing it makes its execution faster.
• apollo-cassandra and other node.js Cassandra ORMs don't support es2015 Promises. This is important since with es2016 async functions, only Promises can be awaited. Also, #nomorecallbacks!
• As of writing this, the last commit on apollo-cassandra was in March, 2015. It seems to be out of active development.

---

Usage

Installation

npm install --save cassandra-co

Promises and yields

All asynchronous operations return a Promise. Using co or koa, these promises can also be yielded. This documentation uses yield instead of .then() on the Promises.

Example

// Promise
asyncOperation().then(function(result) {
    // use the result here
});

// yield
var result = yield asyncOperation();
// use the result here

Instantiation

Parameters

• {String} keyspace: The keyspace to operate on
• {Array} hosts: Hostnames of cassandra servers
• {Object} options [optional]: Any other client options as defined in http://www.datastax.com/drivers/nodejs/2.0/global.html#ClientOptions.

Example Initialize cassandra-co with game_of_thrones keyspace and local Cassandra

var db = require('cassandra-co')('game_of_thrones', ['127.0.0.1']);

Model

Parameters

• {String} table: The name of the table

Example Initialize the model for characters table

var Characters = yield db.getModel('characters');

Unlike with most other Cassandra node.js ORMs, you don't need to define the model yourself. This statement fetches the model from the schema meta-tables for you.

SELECT

Parameters

• {Object} criteria [optional]: The where clause criteria, with column names as keys, and values as:
  • value for exact match, or
  • {Object} where:
    • operators as keys and operands as values for numerical comparison
    • in as key and {Array} of values for in clause
    • contains or containsKey as key and the respective value or key to check for in the set, list or map as value
• {Object} clauses [optional]: Additional clauses such as:
  • distinct: ['column1', 'column2']
  • count: true
  • orderBy: column_name for default (ascending), or {Object} with order (asc|desc) as key and column_name as value
  • limit: 100
  • allowFiltering: true
  • raw: not wrapped in a cassandra-co object
• {Object} options [optional]: Any other query options as defined in http://www.datastax.com/drivers/nodejs/2.0/global.html#QueryOptions

Example Find at max 5 Starks, born before Robert's Rebellion, sorted younger to older

var starks = yield Characters.find({
    house: 'Stark',
    born: {
        '<': 282
    }
}, {
    limit: 5,
    orderBy: {
        desc: 'born'
    }
});

INSERT

Parameters

• {Object} data: Data to initialize row instance with, column names as keys
• {Object} clauses [optional]: ttl and / or timestamp for the row being saved

Example Add a new row to characters with a ttl of 14 years

var joff = new Characters({
    name: 'Joffrey',
    house: 'Baratheon'
    born: 286
});

yield joff.save({
    ttl: 60 * 60 * 24 * 365 * 14
});

UPDATE

Parameters

• {Object} clauses [optional]: ttl and / or timestamp for the row being saved

Example Change the name of the youngest Stark born before Robert's Rebellion to Ben

starks[0].name = 'Ben';
yield starks[0].save();

Counters

Parameters

• {String} column [optional]: the specific counter column to increment, not required if there's only one such column
• {Number} by [optional]: the amount to increment the counter by, assumed 1 if not given

Example Increment the kills for Daenerys Targaryen whether or not the row exists, and decrement the kills for Jaime Lannister by 2

var Kills = yield db.getModel('kills'),
    danysKills = new Kills({character: 'Daenerys Targaryen'});
yield danysKills.increment();

var kingslayersKillses = yield Kills.find({character: 'Jaime Lannister'});
yield kingslayersKillses[0].decrement(2);

DELETE

Parameters

• {Array} columns [optional]: If provided, the values from the given columns will be deleted; otherwise, the row will be deleted

Example Delete Ben's birth year

yield starks[0].delete('born');

---

Caveats

• Only prepared statements are supported. All operations will be executed as prepared statements.

• cassandra-co needs the following ES2015/2016 features.

  • Generator Functions
  • Arrow Functions
  • Shorthand and Computed Object Properties
  • Spread Operator
  • Array.prototype.includes

  You can check if the above features are available in your javascript environment here. If you don't have them, you can get them in the following ways:

  • The --harmony flag for node.js enables all stable es6 features in the v8 engine used in your version of node.js. Details: man node | grep harmony
  • The --harmony_<feature_name> flags for node.js and io.js enable the respective features behind those flags in the v8 engine used in your version of [node|io].js. Details: node|iojs --v8-options
  • Transpilers and Polyfills such as Babel or Traceur

---