Awesome

Synopsis

Create and manage indices for your leveldb database.

• Provides simple querying of indexed data
• Supports inverted sorting of indices (e.g. sort a Date from newer to older)
• Uses bytewise encoding for indices.
• Supports automatic indexing (using hooks).
• Works with changing fields (with some performance impact during reads).

Stability

2 - Unstable

The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable.

Usage

var indico = require('level-indico');

var db = sublevel(level('db', { valueEncoding: 'json' }));

//set indices on a sublevel
var posts = indico(db.sublevel('posts'));

/*
  post = {
    title: String,
    commentCount: Number,
    user: {
      name: String, 
      id: String
    },
    createdDate: Date
  }

*/

//set a single index,  and save the index object for later use
var titleIndex = posts.indico.ensureIndex(['title']);
posts.indico.ensureIndex(['createdDate']);
//works with nested properties
posts.indico.ensureIndex(['user.id']);
//set a compound index
posts.indico.ensureIndex(['title', 'commentCount']);
//set a descending index on 'createdDate' (so it sorts from newer to older)
posts.indico.ensureIndex([['createdDate', 'desc'], 'commentCount']);

//[...] Put some data

//Now query...

//SELECT * FROM posts WHERE title = 'Hello'
titleIndex.find({start: ['Hello'], end: ['Hello']}, function (err, data) {
  //...
});

//SELECT * FROM posts WHERE title = 'Hello' AND commentCount >= 1
posts.indico.findBy(['title', 'commentCount'], {start: ['Hello', 1], end: ['Hello', undefined]}, function (err, data) {
  //...
});

//SELECT * FROM posts ORDER BY createdDate DESC
posts.indico.findBy([['createdDate', 'desc']], {start: [null], end: [undefined]}, function (err, data) {
  //...
});

//SELECT * FROM posts WHERE createdDate <= '1/1/2010' AND commentCount >= 10
posts.indico.findBy([['createdDate', 'desc'], 'commentCount'], {
    start: [new Date(2010,01,00), 10],
    end: [undefined, undefined]
  }, function (err, data) {
  //...
});

//SELECT * FROM posts ORDER BY createdDate ASC
posts.indico.streamBy([['createdDate', 'desc']], {start: [null], end: [undefined]})
.on('data', function(data) {
//...
})
.on(close, function() {
//...
})

API

db.indico

<a name="indico-ensureindex"></a>

indico.ensureIndex(properties)

Sets an index on the specified properties.

Arguments

• properties: an Array listing the properties to index. Each item can be:
  • String: (e.g 'title') the property to include in the index, by default sorted Ascending.
  • Array: An array containing 2 String items:
    • [0]: The property name
    • [1]: The sorting order, one between 'desc' and 'asc'.

Returns

QueryManager for the specified index.

Example

var titleIndex = db.indico.ensureIndex(['title']);
var dateAndCommentIndex = db.indico.ensureIndex([['createdDate', 'desc'], 'commentCount']);

<a name="indico-index"></a>

indico.index(properties)

Alias of indico.ensureIndex

<a name="indico-findby"></a>

indico.findBy(properties, options, callback)

Invokes find on the QueryManager corresponding to the specified properties

<a name="indico-streamby"></a>

indico.streamBy(properties, options)

Invokes stream on the QueryManager corresponding to the specified properties

QueryManager

<a name="querymanager-find"></a>

find(options, callback)

Finds all values corresponding to the specified options

Arguments

• options:
  • start: Array specifying the index you wish to start the read at. It must have the same arity of the index.
  • end: Array specifying index you wish to end the read on. It must have the same arity of the index.
• callback: function(err, data)

Note: Since level-indico uses bytewise under the hood, it means that null will sort before any other value, while undefined will sort aftern any other value.

Example

//SELECT * FROM posts WHERE title = 'Hello' ORDER BY commentCount ASC
posts.indico.findBy(['title', 'commentCount'], {start: ['Hello', null], end: ['Hello', undefined]}, function (err, data) {
  //...
});

<a name="querymanager-stream"></a>

stream(options)

Same as find, but returns a ReadableStream for the specified query.

TODO

• Index nested objects (not just values)
• Full reindex

Breaking changes

0.1 -> 0.2

ensureIndex('title', 'content') becomes ensureIndex(['title', 'content'])

License

MIT