datastar

"Now witness the power of this FULLY ARMED AND OPERATIONAL DATASTAR!"

npm install datastar --save

Contributing

This module is open source! That means we want your contributions!

1. Install it and use it in your project.
2. Log bugs, issues, and questions on Github
3. Make pull-requests and help make us it better!

---

• Usage
• Warnings
• API Documentation
  • Defining Models
    • consistency
  • Schema Validation
  • Lookup Tables
  • Model.create
  • Model.find
    • Stream API
  • Model.remove
  • Model.update
  • Model hooks
  • Create Tables
  • Drop Tables
  • Statement Building
  • Conventions: casing, pluarlization, etc.
  • Using Async/Await
• Tests
• Contributors

Usage

1const Datastar = require('datastar');
2const datastar = new Datastar({
3  config: {
4    credentials: {
5      username: 'cassandra',
6      password: 'cassandra'
7    },
8    keyspace: 'a_fancy_keyspace',
9    contactPoints: ['127.0.0.1', 'host2', 'host3']
10  }
11}).connect();
12
13const cql = datastar.schema.cql;
14
15const Artist = datastar.define('artist', {
16  schema: datastar.schema.object({
17    artist_id: cql.uuid(),
18    name: cql.text(),
19    create_date: cql.timestamp({ default: 'create' }),
20    update_date: cql.timestamp({ default: 'update' }),
21    members: cql.set(cql.text()),
22    related_artists: cql.set(cql.uuid()).allow(null),
23    traits: cql.set(cql.text()),
24    metadata: cql.map(cql.text(), cql.text()).allow(null)
25  }).partitionKey('artist_id'),
26  with: {
27    compaction: {
28      class: 'LeveledCompactionStrategy'
29    }
30  }
31});
32
33Artist.create({
34  artistId: '12345678-1234-1234-1234-123456789012',
35}, function (err, res) {
36  if (err) /* handle me */ return;
37  /* The create statement(s) have executed. */
38});

Warnings

• Define schemas in snakecase, however always use camelcase instead of snakecase everywhere else but schema definitions.

API Documentation

Constructor

All constructor options are passed directly to Priam so any options Priam supports, Datastar supports.

1const Datastar = require('datastar');
2const datastar = new Datastar({
3  config: {
4    credentials: {
5      // who am I connecting as
6      username: 'cassandra',
7      // what's my password
8      password: 'cassandra'
9    },
10    // what keyspace am I using
11    keyspace: 'a_fancy_keyspace',
12    // what cluster hosts do I know about
13    contactPoints: ['127.0.0.1', 'host2', 'host3']
14  }
15});

Connect

Given a set of cassandra information, connect to the cassandra constructor. This must be called before you do any model creation, finding, schema defintion, etc.

1let datastar = new Datastar(...);
2// I setup the connection, but I'm not connected yet, let's connect!
3datastar = datastar.connect();

Define

Define is the primary way to create Models while using Datastar. See the following long example for an explanation of all options to define. Define your schemas in snake case, but use camel case everywhere else!

1
2//
3// main definition function, pass a name of the model (table), and it's corresponding schema
4//
5const Album = datastar.define('album', {
6  //
7  // ensure that the table exists. This executes an implicit CREATE IF NOT EXISTS
8  // statement. You can listen for completio using the `ensure-tables:finished`
9  // event
10  ensureTables: true,
11  //
12  // the actual schema definition
13  //
14  schema: datastar.schema.object({
15    album_id: cql.uuid(),
16    artist_id: cql.uuid(),
17    name: cql.text(),
18    track_list: cql.list(cql.text()),
19    song_list: cql.list(cql.uuid()),
20    release_date: cql.timestamp(),
21    create_date: cql.timestamp(),
22    producer: cql.text()
23  }).partitionKey('artist_id')
24    .clusteringKey('album_id'),
25  //
26  // Support `with` extensions onto the table statement when calling .ensureTables
27  //
28  with: {
29    //
30    // key value of how you want to alter the table
31    //
32    compaction: {
33      class: 'LeveledCompactionStrategy'
34    },
35    gcGraceSeconds: 9860,
36    //
37    // How we want to order our rows on disk for clustering keys
38    //
39    orderBy: {
40      key: 'album_id',
41      order: 'desc'
42    }
43  }
44});

Consistency

Since Cassandra is a distributed database, we need a way to specify what our consistency threshold is for both reading and writing from the database. We can set consistency, readConsistency and writeConsistency when we define our model. consistency is used if you want to set both to be the same threshold otherwise you can go more granular with readConsistency and writeConsistency. Consistency is defined using a camelCase string that corresponds with a consistency that cassandra allows.

1const Album = datastar.define('album', {
2  schema: albumSchema,
3  readConsistency: 'localQuorum',
4  writeConsitency: 'one'
5});

We also support setting consistency on an operation basis as well if you want to override the default set on the model for specific cases.

1Album.create({
2  entity: {
3    albumId: uuid.v4(),
4    name: 'nevermind'
5  },
6  consistency: 'localOne'
7}, function (err) {
8  if (err) /* handle me */ return;
9  /* create is completed */
10});

We also support setting an optional expiration period called TTL(Time To Live) for data expiration and removal. You can set up the TTL option either when creating the data entry or updating it, e.g. { ttl: 3 } means the expiration time for the data is 3 seconds. Once when you update the data entry, it will reset its TTL.

1Album.create({
2  entity: {
3    albumId: uuid.v4(),
4    name: 'nevermind'
5  },
6  ttl: 3
7}, function (err) {
8  if (err) /* handle me */ return;
9  /* create is completed */
10});

OR

1Album.update({
2  entity: {
3    albumId: uuid.v4(),
4    name: 'whatever'
5  },
6  ttl: 5
7}, function (err) {
8  if (err) /* handle me */ return;
9  /* update is completed */
10});

Note: The ttl option must be set on every update call. It is not maintained from the initial entity creation. If you don't set it in an update call, the entity will not have a TTL set.

Schema Validation

Schemas are validated on .define. As you call each function on a Model, such as create or find, the calls to the functions are validated against the schema. See here for detailed information of supported CQL data types.

Validation is performed using joi.

Notes on null:

• Use the .allow(null) function of joi on any property you want to allow to be null when creating your schema

The following table show how certain data types are validated:

CQL Data Type	Validation Type
ascii	cql.ascii()
bigint	cql.bigint()
blob	cql.blob()
boolean	cql.boolean()
counter	cql.counter()
decimal	cql.decimal()
double	cql.double()
float	cql.float()
inet	cql.inet()
text	cql.text()
timestamp	cql.timestamp()
timeuuid	cql.timeuuid()
uuid	cql.uuid()
int	cql.int()
varchar	cql.varchar()
varint	cql.varint()
map	cql.map(cql.text(), cql.text()),
set	cql.set(cql.text())

Lookup tables

This functionality that we built into datastar exists in order to optimize queries for other unique keys on your main table. By default Cassandra has the ability to do this for you by building an index for that key. The only problem is that the current backend storage of Cassandra can make these very slow and under performant. If this is a high traffic query pattern, this could lead you to having issues with your database. We work around this limitation by simply creating more tables and doing an extra write to the database. Since Cassandra is optimized for handling a heavy write workload, this becomes trivial. We take care of the complexity of keeping these tables in sync for you. Lets look at an example by modifying our Artist model.

1const Artist = datastar.define('artist', {
2  schema: datastar.schema.object({
3    artist_id: cql.uuid(),
4    name: cql.text(),
5    create_date: cql.timestamp({ default: 'create' }),
6    update_date: cql.timestamp({ default: 'update' }),
7    members: cql.set(cql.text()),
8    related_artists: cql.set(cql.uuid()).allow(null),
9    traits: cql.set(cql.text()),
10    metadata: cql.map(cql.text(), cql.text()).allow(null)
11  }).partitionKey('artist_id')
12    .lookupKeys('name'),
13  with: {
14    compaction: {
15      class: 'LeveledCompactionStrategy'
16    }
17  }
18});

In our example above we added name as a lookupKey to our Artist model. This means a few things:

1. We must provide a name when we create an Artist.
2. name as with any lookupKey MUST be unique
3. We must provide the name when removing an Artist as it is now the primary key of a different table.
4. When updating an Artist, a fully formed previous value must be given or else an implicit find operation will happen in order to properly assess if a lookupKey has changed.

Keeping these restrictions in mind, we can now have fast lookups by name without having to worry about too much.

1Artist.findOne({
2  name: 'kurt cobain'
3}, function (err, artist) {
4  if (err) /* handle me */ return;
5  console.log('Fetched artist by name!');
6});

Model.create

Once you have created a Model using datastar.define you can start creating records against the Cassandra database you have configured in your options or passed to datastar.connect:

1const cql = datastar.schema.cql;
2
3const Beverage = datastar.define('beverage', {
4  schema: datastar.schema.object({
5    'beverage_id': cql.uuid({ default: 'v4' }),
6    'name': cql.text(),
7    'type': cql.text().allow(null),
8    'sugar': cql.int(),
9    'notes': cql.text(),
10    'otherIngredients': cql.map(cql.text(), cql.text()),
11    'tags': cql.set(cql.text()),
12    'siblings': cql.set(cql.uuid())
13  }).partitionKey('beverage_id'),
14});
15
16Beverage.create({
17  name: 'brawndo',
18  sugar: 1000000,
19  notes: "It's got what plants crave"
20}, function (err) {
21  if (err) /* handle me */ return;
22  /* create is completed */
23});

The create method (like all CRUD methods) will accept four different arguments for convenience:

1// Create a single model with properties
2Model.create(properties);
3Model.create({ entity: properties });
4Model.create({ entities: properties });
5
6// Create a two models: one with properties
7// and the second with properties2
8Model.create({ entities: [properties, properties2] })

Model.update

Updating records in the database is something that is fairly common. We expose a simple method to do this where you just provide a partial object representing your Beverage and it will figure out how to update all the fields! Lets see what it looks like.

1//
2// For the simple case update some basic field
3//
4Beverage.update({
5  name: 'brawndo',
6  sugar: 900000000,
7  notes: "It's got what plants crave, now with more sugar!",
8  //
9  // This value will get merged in with whatever keys currently exist for this
10  // `map`
11  //
12  otherIngredients: {
13    energy: '9001'
14  },
15  //
16  // This replaces the set that currently exists in the database with these
17  // values
18  //
19  tags: ['healthy', 'energy', 'gives you wings']
20}, function (err) {
21  if (err) /* handle me */ return;
22  /* update is completed */
23});

It even supports higher level functions on set and list types. Lets look at what set looks like. (list covered father down)

1Beverage.update({
2  name: 'brawndo',
3  //
4  // The keys of this object are the `actions` that can be made on the set in
5  // cassandra. This allows us to understand which CQL to be sent when updating.
6  //
7  tags: {
8    add: ['amazing', 'invincible'],
9    remove: ['gives you wings']
10  }
11}, function (err) {
12  if (err) /* handle me */ return;
13  /* update success */
14});

If we decide to create a model that needs to use Lookup Tables, we require a previous value to be passed in as well as the entity being updated. If no previous value is passed in, we will implicitly run a find on the primary table to get the latest record before executing the update. This previous value is required because we have to detect whether a primaryKey of a lookup table has changed.

IMPORTANT:

If you have a case where you are modifying the primaryKey of a lookup table and you are PASSING IN the previous value into the update function, that previous value MUST be a fully formed object of the previous record, otherwise you are guaranteed to have the changed lookup table go out of sync. Passing in your own previous value is done at your own risk if you do not understand this warning or the implications, please post an issue.

1const Person = datastar.define('person', {
2  ensureTables: true,
3  schema: datastar.schema.object({
4    person_id: datastar.schema.cql.uuid({ default: 'v4' }),
5    // We are assuming names are unique
6    name: datastar.schema.cql.text(),
7    characteristics: datastar.schema.cql.list(datastar.schema.cql.text()),
8    attributes: datastar.schema.cql.map(
9      datastar.schema.cql.text(),
10      datastar.schema.cql.text()
11    )
12  }).rename('id', 'person_id')
13    //
14    // Create lookup table so I can look up by `name` as well since it is unique
15    //
16    .lookupKeys('name')
17});
18
19//
20// person Object
21//
22const person = {
23  name: 'Fred Flinstone',
24  attributes: {
25    height: '6 foot 1 inch'
26  }
27};
28
29//
30// So we start but creating a person
31//
32Person.create(person, function (err) {
33  if (err) /* handle me */ return;
34  /* person created */
35});
36
37//
38// Now if I later want to update this same and change the name... I need to pass
39// in that FULL person object that was used previously. I will warn again that
40// DATA WILL BE LOST if `previous` is an incomplete piece of data. This means that the `person_by_name`
41// lookup table that gets generated under the covers will have incomplete data.
42//
43Person.update({
44  previous: person,
45  entity: {
46    name: 'Barney Rubble',
47  }
48}, function (err) {
49  if (err) /* handle me */ return;
50  /* update completed */
51});
52
53//
54// If I want to update the primary key of the entity I would need to do something as follows
55// (this also shows changing the lookup table primary key at the same time)
56//
57
58Person.remove(previous, function(err) {
59  if (err) /* handle me */ return;
60  previous.name = 'Barney Rubble';
61  previous.personId = '12345678-1234-1234-1234-123456789012'
62
63  Person.create(previous, function (err) {
64    if (err) /* handle me */ return;
65    /* successful create */
66  });
67});
68
69//
70// If I ommit previous altogether, I just need to ensure I pass in the proper
71// primary key for the `person` table and a find operation will be done in order to
72// fetch the previous entity. This is the simplest method but costs an implicit
73// find operation before the update is completed.
74//
75Person.update({
76  id: person.id,
77  name: 'Barney Rubble',
78  attributes: {
79    hair: 'blonde'
80  }
81}, function (err) {
82  if (err) /* handle me */ return;
83  /* update completed */
84});
85
86//
87// Just like `set` types, we can do higher level operations with `list` types.
88// Lets start by updateing a list
89//
90Person.update({
91  id: person.id,
92  characteristics:['fast', 'hard working']
93}, function (err) {
94  if (err) /* handle me */ return;
95  /* update completed */
96});
97
98//
99// We can place items on the front of the list using `prepend`
100//
101Person.update({
102  id: person.id,
103  characteristics: {
104    prepend: ['lazy']
105  }
106}, function (err) {
107  if (err) /* handle me */ return;
108  /* update completed, characteristics = ['lazy', 'fast', 'hard working'] */
109});
110
111//
112// We can also add them to the end of the list as well with `append`
113//
114Person.update({
115  id: person.id,
116  characteristics: {
117    append: ['helpful']
118  }
119}, function (err) {
120  if (err) /* handle me */ return;
121  /* update completed, characteristics = ['lazy', 'fast', 'hard working', 'helpful'] */
122});
123
124//
125// We also have a standard `remove` operation that can be done
126//
127Person.update({
128  id: person.id,
129  characteristics: {
130    remove: ['fast']
131  }
132}, function (err) {
133  if (err) /* handle me */ return;
134  /* update completed, characteristics = ['lazy', 'hard working', 'helpful'] */
135});
136
137//
138// The last function we support on `list` is the `index` operation. It replaces
139// the item in the `list` at the given index with the value associated.
140//
141Person.update({
142  id: person.id,
143  characteristics: {
144    //
145    // Replaces the item at index 1.
146    //
147    index: { '1': 'disabled' }
148  }
149}, function (err) {
150  if (err) /* handle me */ return;
151  /* update completed, characteristics = ['lazy', 'disabled', 'helpful'] */
152});

Model.find

Querying Cassandra can be the source of much pain, which is why datastar will only allow queries on models based on primary keys. Any post-query filtering is the responsibility of the consumer.

There are four variants to find:

• Model.find(options, callback)
• Model.findOne(options || key, callback) <-- Also has an alias Model.get
• Model.findFirst(options, callback)
• Model.count(options, callback)

The latter three (findOne/get, findFirst, and count) are all facades to find and simply do not need the type parameter in the example below. Another note here is that type is implied to be all if none is given.

1Album.find({
2  type: 'all',
3  conditions: {
4    artistId: '00000000-0000-0000-0000-000000000001'
5  }
6}, function (err, result) {
7  if (err) /* handle me */ return;
8  /* `result` will be an array of instances of `Album` */
9});

In the latter three facades, you can also pass in conditions as the options object!

1Album.findOne({
2  artistId: '00000000-0000-0000-0000-000000000001',
3  albumId: '00000000-0000-0000-0000-000000000005'
4}, function (err, result) {
5  if (err) /* handle me */ return;
6  /* `result` will be an instance of `Album` */
7});

You only need to pass a separate conditions object when you want to add additional parameters to the query like LIMIT. Limit allows us to limit how many records we are retrieving for any range query

1Album.findAll({
2  conditions: {
3    artistId: '00000000-0000-0000-0000-000000000001'
4  },
5  limit: 1
6}, function (err, results) {
7  if (err) /* handle me */ return;
8  /* results.length === 1 */
9});

We can also just pass in a single key in order to fetch our record. NOTE This only works if your schema only has a single partition/primary key and assumes you are passing in that key. This will not work for lookup tables.

1Artist.get('00000000-0000-0000-0000-000000000001', function(err, result) {
2  if (err) /* handle me */ return;
3  /* `result` will be an instance of `Artist` */
4});

Stream API

While also providing a standard callback API, the find function supports first class streams! This is very convenient when doing a findAll and processing those records as they come instead of waiting to buffer them all into memory. For example, if we were doing this inside a request handler:

1const { Transform } = require('stream');
2
3//
4// Fetch sodas handler
5//
6function handler(req, res) {
7  Album.findAll({
8    artistId: '00000000-0000-0000-0000-000000000001'
9  })
10  .on('error', function (err) {
11    // Handle me for when something bad happens
12    res.writeHead(500);
13    res.end(JSON.stringify({ error: err.message }));
14  })
15  .pipe(new Transform({
16    writableObjectMode: true,
17    readableObjectMode: true,
18    transform(bev, enc, callback) {
19      //
20      // Massage the beverage object in some way before returning it to the user
21      //
22      callback(null, massageBeverage(bev));
23    }
24  }))
25  .pipe(res);
26}

Async Iterable API

The async iterable API, like the stream API, provides another convenient way to process records as they come in. If you do not need the full feature set of node streams, this is a more efficient technique.

To access the async iterable API, set the iterable option to true in your call to .find() or .findAll(). Alternately, call the .iterate() method of your model, which is equivalent to .findAll({ ..., iterable: true }).

1async function getAllArtistTracks(artistId) {
2  let allTracks = [];
3  for await (const album of Album.iterate({ conditions: { artistId } })) {
4    allTracks = allTracks.concat(album.trackList);
5  }
6  return new Set(allTracks);
7}

Model.remove

If you would like to remove a record or a set of records from the database, you just need to pass in the right set of conditions.

• Model.remove(options, callback);

One thing to note here is that when deleting a single record, you can pass in the fully formed object and we will handle stripping the unsafe parameters that you cannot query upon based on your defined schema.

1Album.remove({
2  artistId: '00000000-0000-0000-0000-000000000001',
3  albumId: '00000000-0000-0000-0000-000000000005'
4  // any other properties.
5}, function (err) {
6  if (err) /* handle me */ return;
7  console.log('Successfully removed beverage');
8});

This also works on a range of values, given a schema with artistId as the partition key and albumId as the clustering key, like our album model at the top of this readme...

1//
2// This will delete ALL elements for a given `artistId`
3//
4Album.remove({
5  artistId: '00000000-0000-0000-0000-000000000001'
6}, function (err) {
7  if (err) /* handle me */ return;
8  console.log('Successfully removed all albums');
9});

When you remove an entity that has an associated lookup table, you need to pass in both the partition keys of the main table AND the lookup table.

1//
2// Going back to our `person` model..
3//
4Person.remove({
5  personId: '12345678-1234-1234-1234-123456789012',
6  name: 'steve belaruse'
7}, function(err) {
8  if (err) /* handle me */ return;
9  console.log('Successfully removed artist');
10});

This is necessary because a lookupKey defines the partition key of a different table that is created for lookups.

Model hooks

Arguably one of the most powerful features hidden in datastar are the model hooks or life-cycle events that allow you to hook into and modify the execution of a given statement. First let's define the operations and the hooks that they have associated.

Operation	Life-cycle event / model hook
create, update, remove, ensure-tables	build, execute
find	all, count, one, first

datastar utilizes a module called Understudy under the hood. This provides a way to add extensibility to any operation you perform on a specific model. Lets take a look at what this could look like.

Before build is before we create the statement(s) that we then collect to execute and insert into Cassandra. This allows us to modify any of the entities before CQL is generated for them.

1Beverage.before('create:build', function (options, callback) {
2  //
3  // We create our own option that gets passed in by the beverage option that
4  // multiplies all number values by the given multiple. Might not be
5  // practically useful but serves the point of how we can manipulate objects
6  // conditionally in our application by leveraging `datastar`'s machinery.'
7  //
8  if (options.multiply) {
9    //
10    // Here we can modify the entities that were passed in. If a single entity
11    // was passed in, this will still be an array, just of length 1
12    //
13    options.entities = options.entities.map(function (ent) {
14      return Object.keys(ent).reduce(function (acc, key) {
15        acc[key] = typeof ent[key] === 'number'
16          ? ent[key] * options.multiply
17          : ent[key];
18
19        return acc;
20      }, {})
21    });
22  }
23  //
24  // We even have a callback interface here in case we have to make an
25  // asynchronous call to another service or database.
26  //
27  callback();
28});

Before execute is right before we actually send the statements to cassandra. This is where we have a chance to modify the statements or StatementCollection with any other statements we may have or even to just the consistency we are asking of cassandra if there is only a narrow case where you require a consistency of one. (You could also just pass option.consistency into the function call as well)

1Beverage.before('create:execute', function (options, callback) {
2  if (options.commitFast) {
3    options.statements.consistency('one');
4    //
5    // Execute all statements in parallel with a limit of 7
6    //
7    options.statements.strategy = 7;
8  }
9
10
11  callback();
12});

An after hook for execute might look like this if we wanted to insert the same data into a separate keyspace using a different Priam instance. Which would be a separate connection to cassandra. This call is ensured to be executed before the Beverage.create(opts, callback) function calls its callback. NOTE: This assumes the same columns exist in this other keyspace

1const otherDataCenterConnection = new Priam(connectOpts);
2Beverage.after('create:execute', function (options, callback) {
3  //
4  // Reuse the statement collection from the create operation to execute the
5  // same set of statements on another connection
6  //
7  options.statements.connection = otherDataCenterConnection;
8
9  options.statements.execute(callback);
10});

The last types of hook we have is for the specific find operations including. find:all, find:one, find:count, find:first. These specifc are the same as the above :build hooks in when they execute but have different and more useful semantics for after hooks for modifying data fetched. This makes use of Understudy's .waterfall function. An important caveat is that find hooks are not executed when you use the streaming option. If you want to convert all records from your queries, see Record Transformation for a technique that works for all types of queries.

This after hooks on find:one allow us to mutate the result returned from any findOne query taken on beverage. This could allow us to call an external service to fetch extra properties or anything else you can think of. The main goal is to provide the extensibility to do what you want without datastar getting in your way.

1Beverage.after('find:one', function (result, callback) {
2  //
3  // Populate associated sibling models on every `findOne` or `get` query
4  //
5  async.map(result.siblings,
6    function (id, next) {
7    Beverage.get(id, next);
8  }, function (err, siblingModels) {
9    if (err) { return callback(err); }
10    result.siblings = siblingModels;
11    callback()
12  });
13});

We can even add another after hook after this one which will get executed in series and be able to modify any new attributes!

1Beverage.after('find:one', function (result, callback) {
2  //
3  // Now that siblings are populated, modify their siblings if they arent
4  // properly associated with their sibling
5  //
6  async.each(result.siblings, function (bev, next) {
7    if (bev.siblings.indexOf(result.beverageId) !== -1) {
8      return next();
9    }
10    //
11    // TODO: Have instance functions for this type of thing
12    //
13    const update = bev.toJSON();
14    //
15    // Do the more efficient update to cassandra on the `set` type.
16    //
17    update.siblings = {
18      add: [result.beverageId]
19    };
20    bev.siblings.push(result.beverageId);
21    Beverage.update(update, function (err) {
22      if (err) { return next(err); }
23      next(null, bev);
24    });
25  }, function (err, res) {
26    if (err) { return callback(err); }
27    result.siblings = res;
28    callback();
29  });
30});

Record Transformation

Assign a transform method to your model to synchronously modify all records coming back from a query; this technique works for the callback, streaming, or async iterable methods of querying:

1Beverage.transform = before => ({
2  ...before,
3  isDiet: before.sugar <= 0
4})

Create tables

Each Model is capable of creating the Cassandra tables associated with its schema. To ensure that a table is created you can pass the ensureTables option:

1const Spice = datastar.define('spice', {
2  ensureTables: true,
3  schema: /* a valid schema */
4})

Or call Model.ensureTables whenever is appropriate for your application:

1Spice.ensureTables(function (err) {
2  if (err) /* handle me */ return;
3  console.log('Spice tables created successfully.');
4});

You can also specify an with.orderBy option to enable CLUSTER ORDER BY on a partition key. This is useful if you want your Spice table to store the newest items on disk first, making it faster to reading in that order.

1//
2// WITH CLUSTER ORDER BY (created_at, DESC)
3//
4
5Spice.ensureTables({
6  with: {
7    orderBy: { key: 'createdAt', order: 'DESC' }
8  }
9}, function (err) {
10  if (err) /* handle me */ return;
11  console.log('Spice tables created ordered descending');
12})

// // We can also pass an option to enable setting other properties of a table as well! //

1Spice.ensureTables({
2  with: {
3    compaction: {
4      class: 'LeveledCompactionStrategy',
5      enabled: true,
6      sstableSizeInMb: 160,
7      tombstoneCompactionInterval '86400'
8    },
9    gcGraceSeconds: 86400
10  }
11}, function (err) {
12  if (err) /* handle me */ return;
13  console.log('Successfully created and altered the table');
14});
15

Drop Tables

In datastar, each model also has the ability to drop tables. This assumes the user used to establish the connection has these permissions. Lets see what this looks like with our spice model.

1Spice.dropTables(function (err) {
2  if (err) /* handle me */ return;
3
4  console.log('Spice tables dropped!');
5});
6

Its as simple as that. We will drop the spice table and any associated Lookup Tables if they were configured. With .dropTables and .ensureTables it's super easy to use datastar as a building block for managing all of your Cassandra tables without executing any manual CQL.

Statement Building

Currently this happens within the model.js code and how it interacts with the statement-builder and appends statements to the StatementCollection. Currently the best place to learn about this is read through the create/update/remove pathway and follow how a statement is created and then executed. In the future we will have comprehensive documentation on this.

Conventions

We make a few assumptions which have manifested as conventions in this library.

1. We do not store null values in cassandra itself for an update or create operation on a model. We store a null representation for the given cassandra type. This also means that when we fetch the data back from cassandra, we return the data back to you with the proper nulls you would expect. It just may be unintuitive if you look at the cassandra tables directly and do not see null values.

   This prevents tombstones from being created which has been crucial for our production uses of cassandrai at GoDaddy. This is something that could be configurable in the future.

   Fields that are defined as either partitionKey() or clusteringKey() will not be converted to/from null. In addition, to exclude a field from this null handling, define the field with meta({ nullConversion: false }).

2. Casing, as mentioned briefly in the warning at the top of the readme, we assume camelCase as the casing convention when interacting with datastar and the models created with it. The schema is the only place where the keys used MUST be written as snake_case.

Using Async/Await

In Datastar we currently have experimental async/await support. The way to enable Async/Await is to explicitly wrap your models with the AwaitWrap class. This will expose all the expected methods for your model via a thenable that can be awaited. Example shown below.

1const Datastar = require('datastar');
2const { AwaitWrap } = require('datastar');
3const config = require('./config.json');
4
5const datastar = new Datastar(config);
6const cql = datastar.schema.cql;
7
8// Wrap the model to expose async/await functions via `thenables`
9const Model = new AwaitWrap(datastar.define('model', {
10  schema: datastar.schema.object({
11    name: cql.text()
12  }).partitionKey('name')
13}));
14
15async function main()
16  // Ensure the table exists
17  await Model.ensure()
18  // Create the model
19  await Model.create({ name: 'hello' });
20  // find models
21  const models = await Model.findAll({ name: 'hello' })
22  // if you need a stream you can still do that as well
23  const stream = Model.findAllStream({ name: 'hello' });
24}
25
26main();

Until we finalize integrating async/await support into datastar as a first class citizen, this is what we have available to start converting your callback code to use async/await.

Tests

Tests are written with mocha and code coverage is provided with istanbul. They can be run with:

# Run all tests with "pretest"
npm test

# Just run tests
npm run coverage

Contributors

• Christopher Jeffrey
• Sam Shull
• Jarrett Cruger
• Fady Matar
• Charlie Robbins
• Adrian Chang
• Troy Rhinehart
• Steve Commisso
• Joe Junker
• Bill Enterline
• Jacob Page