node-cassandra

An ORM for Cassandra

• Provides support for current Cassandra 3.x builds.
• Tested at scale with distribution in real production environments.
• Mostly feature-complete, active development is underway to add remaining features.
• Open to suggestions! Just create an issue and tag it.

Read the full API Documentation.

Examples:

• Getting Started
  • Connecting
  • Your first Schema, Model, and Materialized View
• Table Compaction
• Static Methods
• Working with List Types
  • Inserting Lists
  • Updating Lists
  • Updating Lists By Index
  • Deleting Lists
• Working with Set Types
  • Inserting Sets
  • Updating Sets
  • Deleting Sets
• Working with Map Types
  • Inserting Maps
  • Updating Maps
  • Deleting Maps by Keys
  • Deleting Maps

Cassandra Known Versions Supported:

• 3.x

Known Supported NodeJS Versions:

• <= 7.6
• 6.x
• 5.x

Getting Started

Connecting to the database

var Cassandra = require('node-cassandra');
var config = {
    contactPoints: ['127.0.0.1:9042'],
    protocolOptions: {port: 9042},
    keyspace: {
        testkeyspace: {
            durableWrites: true,
            withReplication: {
                class: 'SimpleStrategy',
                replication_factor: 1
            }
        }
    }
};

var cassandra = Cassandra.connect(config);
cassandra.on('error', (err) => console.log(err));
cassandra.on('connect', (err) => console.log('connected'));

Creating your first Schema, Model and Materialized View

//create a new schema
var schema = new Cassandra.Schema({
    id: {
        type: 'uuid',
        default: Cassandra.uuid
    },
    username: {
        type: 'text',
        required: true
    },
    ageName: {
        type: 'text',
        default: (instance) => {
            //default value functions are passed the object instance
            return instance.age + instance.name;
        }
    },
    name: 'text',
    age: 'int'
}, {
    primaryKeys: ['username'],
    views: {
        byName: {
            primaryKeys: ['name'],
            orderBy: {
                name: 'asc'
            }
        },
    }
});

//create model
var TestModel = cassandra.model('testModel', schema, (err) => {
    test.save((err) => {
        if (err) {
            throw err;
        }
        console.log('test saved!');
        test.age = 29;
        test.save((err) => {...});
        //test.age updated
    });
});

var test = new TestModel({
    name: 'bar',
    username: 'foo',
    age: 30
});

Working with Collections and Indexes

List Types

//create a new schema
var schema = new Cassandra.Schema({
    name: 'text',
    usernames: {
        type: {
            list: 'text'
        }
    }
}, {
    indexes: ['usernames'], //create an index on the usernames column
    primaryKeys: ['name']
});

Inserting lists

//create model
var TestModel = cassandra.model('testModel', schema, (err) => {
    var test = new TestModel({
        name: 'bar',
        usernames: ['foo', 'bar']
    });
    test.save(() => {
        TestModel.findOne({
            usernames: {
                $contains: 'foo'
            }
        }, (err, row) => {
            console.log(row.usernames); //['foo', 'bar']
        });
    });
});

Updating lists

//following above
var query = {
    name: 'bar',
    usernames: {
        $contains: 'foo'
    }
};
var updateObject = {
    usernames: {
        $filter: ['foo'], //remove items matching "foo"
        $append: ['baz'], //append item "baz"
        $prepend: ['fii'] //prepend item "fii"
    }
};
TestModel.update(query, updateObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne({usernames: {$contains: 'baz'}}, (err, row) => {
        console.log(row.usernames); //['fii', 'bar', 'baz']
    });
});

Updating lists by index

//following above
var query = {
    name: 'bar',
    usernames: {
        $contains: 'bar'
    }
};
var updateObject = {
    usernames: {
        $set: {
            0: 'foo'
        }
    }
};
TestModel.update(query, updateObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne(query, (err, row) => {
        console.log(row.usernames); //['foo', 'bar', 'baz']
    });
});

Deleting lists by column or index

//following above
var query = {
    name: 'bar',
    usernames: {
        $contains: 'fii'
    }
};
var deleteObject = {
    usernames: [0,2] //delete first and last index
};
TestModel.delete(query, deleteObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne({usernames: {$contains: 'bar'}}, (err, row) => {

        console.log(row.usernames); //['bar']

        TestModel.delete({
            usernames: {
                $contains: 'bar'
            }
        }, {
            usernames: 1 //delete usernames column
        }, (err) => {...});

    });
});

Set Types

//create a new schema
var schema = new Cassandra.Schema({
    name: 'text',
    usernames: {
        type: {
            set: 'text'
        }
    }
}, {
    indexes: ['usernames'], //create an index on the usernames column
    primaryKeys: ['name']
});

Inserting sets

//create model
var TestModel = cassandra.model('testModel', schema, (err) => {
    var test = new TestModel({
        name: 'bar',
        usernames: ['foo', 'bar']
    });
    test.save(() => {
        TestModel.findOne({
            usernames: {
                $contains: 'foo'
            }
        }, (err, row) => {
            console.log(row.usernames); //['bar', 'foo']
        });
    });
});

Updating sets

//following above
var query = {
    name: 'bar',
    usernames: {
        $contains: 'bar'
    }
};
var updateObject = {
    usernames: {
        $add: ['aba', 'boa'],
        $filter: ['foo']
    }
};
TestModel.update(query, updateObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne(query, (err, row) => {
        console.log(row.usernames); //['aba', 'bar', 'boa']
    });
});

Update sets to null

//following above
var query = {
    name: 'bar',
    usernames: {
        $contains: 'bar'
    }
};
var updateObject = {
    usernames: [] //or null
};
TestModel.update(query, updateObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne(query, (err, row) => {
        console.log(row.usernames); //null
    });
});

Deleting sets

//not much you can do with deleting sets
var query = {
    name: 'bar',
    usernames: {
        $contains: 'fii'
    }
};
var deleteObject = {
    usernames: 1 //delete usernames column
};
TestModel.delete(query, deleteObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne({name: 'bar'}, (err, row) => {
        console.log(row.usernames); //null
    });
});

Map Types

//create a new schema
var schema = new Cassandra.Schema({
    name: 'text',
    usernames: {
        type: {
            map: ['text', 'int']
        }
    }
}, {
    indexes: ['usernames'], //create an index on the usernames column keys
    primaryKeys: ['name']
});

Inserting maps

//create model
var TestModel = cassandra.model('testModel', schema, (err) => {
    var test = new TestModel({
        name: 'bar',
        usernames: {
            $set: {
                foo: 2,
                bar: 4
            }
        }
    });
    test.save(() => {
        TestModel.findOne({
            usernames: {
                $containsKey: 'foo' //use containsKey for maps
            }
        }, (err, row) => {
            console.log(row.usernames.foo); // 2
        });
    });
});

Updating maps

//following above
var query = {
    name: 'bar',
    usernames: {
        $containsKey: 'bar'
    }
};
var updateObject = {
    usernames: {
        foo: 5, //update "foo" to 5
        fii: 7 /set "fii" to 7
    }
};
TestModel.update(query, updateObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne(query, (err, row) => {
        console.log(row.usernames.foo); // 5
    });
});

Deleting maps by Keys

//not much you can do with deleting maps
var query = {
    name: 'bar',
    usernames: {
        $containsKey: 'bar'
    }
};
var deleteObject = {
    usernames: ['foo']
};
TestModel.delete(query, deleteObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne(query, (err, row) => {
        console.log(row.usernames.foo); // undefined
    });
});

Deleting maps

//not much you can do with deleting maps
var query = {
    name: 'bar',
    usernames: {
        $containsKey: 'bar'
    }
};
var deleteObject = {
    usernames: 1
};
TestModel.delete(query, deleteObject, (err) => {
    if (err) {
        return console.log(err):
    }
    TestModel.findOne(query, (err, row) => {
        console.log(row.usernames); // null
    });
});

Table Compaction

//create a new schema
var schema = new Cassandra.Schema({
    id: 'uuid',
    name: 'text'
}, {
    primaryKeys: ['username'],
    compaction: {
        class: 'DateTieredCompactionStrategy',
        timestamp_resolution: 'MICROSECONDS',
        base_time_seconds: 3600,
        max_sstable_age_days: 365
    }
});

Static Methods

//create a new schema
var schema = new Cassandra.Schema({
    id: {
        type: 'uuid',
        default: Cassandra.uuid
    },
    username: {
        type: 'text',
        required: true
    },
    name: 'text'
}, {
    primaryKeys: ['username'],
    views: {
        byName: {
            primaryKeys: ['name']
        },
    }
});

//attach static method - fat arrow functions won't work here as we need the context to change
schema.statics.findByName = function (name, callback) {
    this.views.byName.findOne({name: name}, callback);
};

//create model
var TestModel = cassandra.model('testModel', schema, (err) => {
    TestModel.findByName('foo', (err, row) => {
        console.log(row.name); // "foo"
    });
});