Skip to content


Subversion checkout URL

You can clone with
Download ZIP
helps build and organize keys for leveldb
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

Level Key Builder (DEPRECATED)

The problems I was attempting to solve are likely handled better via other modules in the level ecosystem.

Check out sublevel for creating different buckets for things:

For querying, check out the indexes and other plugins in the levelup wiki


The most basic example:

var KB = require('level-key-builder');
var kb = new KB({separator: "!"});

// define your key structure
kb.define("user", ["userid"]);

// get your leveldb key for a single user
kb.get("user", {userid: "123"}); 
// returns {singleKey: "user!123"}

// or get a range for all users
// returns {startKey: "user!", endKey: "user!\xff"}

It seems kind of overkill for that, but it comes in handy if you have keys based on multiple attributes:

kb.define("city", ["state", "cityname"]);

// build a single key by supplying all the requested attributes in the order defined
kb.get("city", {state: "mn", city: "minneapolis"}); 
// {singleKey: "city!mn!minneapolis"}

// or get the keys for a range for Minnesota
kb.get("city", {state: "mn"}); 
// {startKey: "city!mn!", endKey: "city!mn!\xff"}

Feel free to add as many attributes that make sense for your data. Keep in mind however that level-key-builder will only build the key up to the values you've given it. For example:

kb.define("hierarchy", ["a", "b", "c", "d"]);
kb.get("hierarchy", {a: "1", b: "2", d: "3"}); 
// {startKey: "hierarchy!1!2!", endKey: "hierarchy!1!2!\xff"} 

It's especially handy when you want to store something with multiple key parts, and all the key parts are part of that thing. For example:

kb.define("person", ["state", "city", "personId"]);

var myPerson = {
    name: "Rick Bergfalk",
    email: "",
    state: "mn",
    city: "minneapolis",
    more: "data",
    it: "doesn't matter"

var personKey = kb.get("person", myPerson).singleKey;


var options = {
    separator: "!",
    rangeEnder: "\xff",     // optional. defaults to "\xff"
    labelKeyParts: false    // optional. defaults to false
var kb = new LevelKeyBuilder(options);

separator is the string used as a separator. It's the only required option.

rangeEnder is the string used to end a range when a range is created. The default is "\xff" which is the last single-byte character available.

<<<<<<< HEAD labelKeyParts is a boolean that determines whether the attributes/key-parts in your key labelled. For example, if labelKeyParts was true:

kb.define("user", ["userid"]);
kb.get("user", {userid: "123"}); 
// {singleKey: "user!userid!123"} 

I'm not sure if that's beneficial or not, since it would lead to a lot of repeating bytes in your keys, and kind of be a waste of space. On the upside however, it would make your keys readable even if you didn't know what your key conventions were. Especially if you have multiple key parts.

If you're a fan of GUIDs consider:


Why all of this?

Getting into leveldb, I found myself with 2 main concerns:

  • How do I keep track of all my keys?
  • How can I build my keys in an elegant manner?

I'm hoping level-key-builder solve addresses those things... but if anyone has any better ideas let me know

Next Steps

Eventually I'll add some sort of levelup integration. The whole point of generating a key or set of keys is to perform some sort of levelup action with them. Why not combine the two and skip a step:

kb.dbPut("user", {userid: "123"}, value, function (err) {});
kb.dbGet("user", {userid: "123"}, function (err, result) {});

updating readme



Something went wrong with that request. Please try again.