Dexter Goodwin

Dexter Goodwin

1657258020

Level-tree-index: Tree indexer for Leveldb / Levelup

A streaming tree structure index for leveldb.

Reference every value in your leveldb to its parent, e.g. by setting value.parentKey to the key of the parent, then level-tree-index will keep track of the full path for each value, allow you to look up parents and children, stream the entire tree or a part thereof and even perform streaming search queries on the tree.

This is useful for implementing e.g. nested comments.

level-tree-index works for all keyEncodings. It works for the json valueEncoding automatically and works for other valueEncodings if you provide custom functions for the opts.pathProp and opts.parentProp options. level-tree-index works equally well with string and buffer paths.

level-tree-index automatically keeps the tree updated as you add, change or delete from the database.

Usage

// db contains your data and idb is used to store the index
var tree = treeIndexer(db, idb);

db.put('1', {name: "foo"}, function(err) {
  if(err) fail(err);

  db.put('2', {parentKey: '1', name: "bar"}, function(err) {
    if(err) fail(err);

    db.put('3', {parentKey: '2', name: "baz"}, function(err) {
      if(err) fail(err);

      // wait for index to finish building
      setTimeout(function() {

        // stream child-paths of 'foo' recursively
        var s = tree.stream('foo');

        s.on('data', function(data) {
          console.log(data.path, data.key, data.value);
        });

      }, 500);
    });
  });
});

Read the unit tests in tests/ for more.

API

treeIndex(db, idb, [opts]) [constructor]

  • db: Your database to be indexed
  • idb: Database to use for storing the tree index

opts:

pathProp: 'name' // property used to construct the path
parentProp: 'parentKey' // property that references key of parent
sep: 0x1f, // path separator. can be string or unicode/ascii character code
pathArray: false, // for functions that output paths, output paths as arrays
ignore: false, // set to a function to selectively ignore 
listen: true, // listen for changes on db and update index automatically
uniquefy: false, // add uniqueProp to end of pathProp to ensure uniqueness
uniqProp: 'unique', // property used for uniqueness
uniqSep: 0x1e, // like `sep` but separates pathProp from uniqProp
levelup: false // if true, returns a levelup instance instead
orphanPath: 'orphans' // parent path of orphans

Both pathProp and parentProp can be either a string, a buffer or a function.

If a function is used then the function will be passed a value from your database as the only argument. The pathProp function is expected to return a string or buffer that will be used to construct the path by joining multiple returned pathProp values with the opts.sep value as separator. The parentProp function is expected to return the key in db of the parent.

opts.sep can be a buffer of a string and is used as a separator to construct the path to each node in the tree.

opts.ignore can be set to a function which will receive the key and value for each change and if it returns something truthy then that value will be ignored by the tree indexer, e.g:

Setting orphanPath to a string, buffer or array will cause all orphaned rows to have orphanPath as their parent path. Setting orphanPath to null will cause orphaned rows to be ignored (not indexed). An orphan is defined as a row with its parentProp set to a non-falsy value but where the referenced parent does not exist in the database. This can happen e.g. if a parent is deleted but its children are left in the database.

// ignore items where the .name property starts with an underscore
ignore: function(key, value) {
  if(typeof value === 'object') {
    if(typeof value.name === 'string') {
      if(value.name[0] === '_') {
        return true;
      }     
    }
  }
  return false;
}

If opts.listen is true then level-tree-index will listen to operations on db and automatically update the index. Otherwise the index will only be updated when .put/.del/batch is called directly on the level-tree-index instance. This option is ignored when opts.levelup is true.

If opts.levelup is true then instead of a level-tree-index instance a levelup instance will be returned with all of the standard levelup API + the level-tree-index API. All calls to .put, .del or .batch will operate on the database given as the db argument and only call their callbacks once the tree index has been updated.

Limitations when using levelup:true:

  • Chained batch mode is not implemented.
  • It is currently not possible not to wait for the tree index to update so it will take longer before the .put, .del and .batch callbacks are called.
  • Key and value encoding happens before the data gets to level-tree-index so opts.pathProp and opts.parentProp must be set to functions and if you're using valueEncoding:'json' then those functions will receive the stringified json data.

See tests/levelup.js for how to use the levelup:true mode.

.getRoot(cb)

Get the path and key of the root element. E.g:

tree.getRoot(function(err, path, key) {
  console.log("Path of root element:", path);
  console.log("Key of root element:", key);
});

.stream([parentPath], [opts])

Recursively stream descendants starting from parentPath. If parentPath is falsy then the entire tree will be streamed to the specified depth.

Opts:

depth: 0, // how many (grand)children deep to go. 0 means infinite
paths: true, // output the path for each child
keys: true, // output the key for each child
values: true, // output the value for each child
pathArray: undefined, // output paths as arrays
ignore: false, // optional function that returns true for values to ignore
match: null, // Stream only matching elements. A string, buffer or function.
matchAncestors: false, // include ancestors of matches if true
gt: undefined, // specify gt directly, must then also specify lt or lte
gte: undefined, // specify gte directly, must then also specify lt or lte
lt: undefined, // specify lt directly, must then also specify gt or gte
lte: undefined // specify lte directly, must then also specify lt or gte

If parentPath is not specified then .gt/.gte and .lt/.lte must be specified.

opts.depth is currently not usable at the same time as opts.match.

If more than one of opts.paths, opts.keys and opts.values is true then the stream will output objects with these as properties.

opts.ignore can be set to a function. This function will receive whatever the stream is about to output (which depends on opts.paths, opts.keys and opts.values) and if the function returns true then those values will not be emitted by the stream.

opts.match allows for streaming search queries on the tree. If set to a string or buffer it will match any path that contains that string or buffer. If set to a RegEx then it will run a .match on the path with that RegEx (only works for string paths). If set to a function then that function will be called with the path as first argument and with the second argument depending on the values of opts.paths, opts.keys and opts.values, e.g:

match: function(path, o) {
  if(o.value.name.match("cattens")) {
   return true;
  }
  return false;
}

Setting opts.matchAncestors to true modifies the behaviour of opts.match to also match all ancestors of matched elements. Ancestors of matched elements will then be streamed in the correct order before the matched element. This requires some buffering so may slow down matches on very large tree indexes.

When using opts.lt/opts.lte you can use the convenience function .lteKey(key). E.g. to stream all paths that begin with 'foo.bar' you could run:

levelTree.stream({
  gte: 'foo.bar',
  lte: levelTree.lteKey('foo.bar')
});

Keep in mind that the above example would also return paths like 'foo.barbar'.

.lteKey(key)

Convenience function that, according to leveldb alphabetical ordering, returns the last possible string or buffer that begins with the specified string or buffer.

.parentStream(path, [opts])

Stream tree index ancestor paths starting from path. Like .stream() but traverses ancestors instead of descendants.

Opts:

height: 0, // how many (grand)children up to go. 0 means infinite
includeCurrent: true, // include the node specified by path in the stream 
paths: true, // output the path for each child
keys: true, // output the key for each child
values: true, // output the value for each child
pathArray: undefined, // output paths as arrays

.parents(path, [opts], cb)

Same as .parentStream but calls back with the results as an array.

.getFromPath(path, cb)

Get key and value from path.

Callback: cb(err, key, value)

.path(key, [opts], cb)

Get tree path given a key.

opts.pathArray: undefined // if true, split path into array

Callback: cb(err, path)

.parentFromValue(value, cb)

Get parent value given a value.

Callback: cb(err, parentValue)

.parentPath(key, [opts], cb)

Get parent path given a key.

opts.pathArray: undefined // if true, split path into array

Callback: cb(err, parentPath)

.parentPathFromValue(key, [opts], cb)

Get parent path given a value.

opts.pathArray: undefined // if true, split path into array

Callback: cb(err, parentPath)

.parentFromPath(path, cb)

Get parent value given a path.

Callback: cb(err, parentValue)

.parentPathFromPath(path, [opts], cb)

Get parent path given a path.

opts.pathArray: undefined // if true, split path into array

Note: this function can be called synchronously

Callback: cb(err, parentPath)

.children(path, [opts], cb)

Get array of children given a value.

Same usage as .stream but this version isn't streaming.

Callback: cb(err, childArray)

.childrenFromKey(path, [opts], cb)

Same as .children but takes a key as input.

Same usage as .stream but this version isn't streaming.

Callback: cb(err, childArray)

.pathStream(parentPath, [opts])

Same as .stream with only opts.paths set to true.

.keyStream(parentPath, [opts])

Same as .stream with only opts.keys set to true.

.valueStream(parentPath, [opts])

Same as .stream with only opts.values set to true.

.clear(cb)

Clear the index. Deletes all of the index's data in the index db.

.build(cb)

Build the index from scratch.

Note: You will likely want to .clear the index first or call .rebuild instead.

.rebuild(cb)

Clear and then build the index.

.put(key, value, [opts], cb)

If you need to wait for the tree index to update after a .put operation then you can use .put directly on the level-tree-index instance and give it a callback. Calling .put this way is much less efficient so if you are planning to use this feature most of the time then you should look into using level-tree-index with the levelup:true option instead.

.del(key, [opts], cb)

Allows you to wait for the tree index to finish building using a callback. Same as .put above but for deletion.

Uniqueness

The way level-tree-index works requires that each indexed database entry has a globally unique path. In other words no two siblings can share the same pathProp.

You might get into a situation where you really need multiple siblings with an identical pathProp. Then you might wonder if you coulds just append e.g. a random string to each pathProp before passing it to level-tree-index and then strip it away again before e.g. showing the data to users.

Well, level-tree-index provides helpers for exactly that. You can set opts.uniquefy to true in the constructor. You will then need database each entry to have a property that, combined with its pathProp, makes it unique. This can be as simple as a long randomly generated string. As with pathProp you will have to inform level-tree-index about this property with uniqProp.

You will then run into the problem that you no longer know the actual path names since they have the uniqueness added. You can either get the actual path name using the synchronous function .getPathName(val) where val is the value from the key-value pair for which you want the path. Or you can call .put or .batch directly on your level-tree-index instance and they will pass your callback a second argument which for .put is the actual path name and for .batch is an array of path names for all put operations.

When uniqefy is turned on any functions returning paths will now be returning paths with the uniqueness data appended. You can use the convenience function .nicify(path) to convert these paths into normal paths without the uniqueness data. For .stream and any functions described as "same as .stream but ..." you can add set opts.nicePaths to true and in you will receive the nicified paths back with each result.

Async quirks

Note that when you call .put, .del or .batch on your database level-tree-index will not be able to delay the callback so you cannot expect the tree index to be up to date when the callback is called. That is why you see the setTimeout used in the usage example above. You can instead call .put, .del or .batch directly on the level-tree-index instance and your callback will not be called until the index has finished building. This works but if opts.listen is set to true then an inefficient and inelegant workaround is used (in order to prevent the change listener from attempting to update the already updated index) which could potentially slow things down.

If you want to wait for the index to update most of the time then you should probably either set opts.listen to false or use the levelup mode by calling the constructor with opts.levelup set to true, though that has its own drawbacks, especially if using valueEncoding:'json'. See the constructor API documentation for more.

Technical explanation

I normal operation (opts.levelup == false) level-tree-index will listen for any changes on your database and update its index every time a change occurs. This is implemented using leveup change event listeners which run after the database operation has already completed.

When running .put or .del directly on level-tree-index the operation is performed on the underlying database then the tree index is updated and then the callback is called. Since we can't turn off the change event listeners for a specific operation, level-tree-index has to remember the operations performed directly through .put or .del on the level-tree-index instance such that the change event listener can ignore them to prevent the tree-index update operation from being called twice. This is done by hashing the entire operation, saving the hash and then checking the hash of each operation picked up by the change event listeners agains the saved hash. This is obviously inefficient. If this feature is never used then nothing is ever hashed nor compared so performance will not be impacted.

ToDo

Before version 1.0

  • Get opts.depth working with opts.match.

Author: Biobricks
Source Code: https://github.com/biobricks/level-tree-index 
License: AGPLv3

#javascript #tree #index #leveldb 

What is GEEK

Buddha Community

Level-tree-index: Tree indexer for Leveldb / Levelup
Dexter Goodwin

Dexter Goodwin

1657258020

Level-tree-index: Tree indexer for Leveldb / Levelup

A streaming tree structure index for leveldb.

Reference every value in your leveldb to its parent, e.g. by setting value.parentKey to the key of the parent, then level-tree-index will keep track of the full path for each value, allow you to look up parents and children, stream the entire tree or a part thereof and even perform streaming search queries on the tree.

This is useful for implementing e.g. nested comments.

level-tree-index works for all keyEncodings. It works for the json valueEncoding automatically and works for other valueEncodings if you provide custom functions for the opts.pathProp and opts.parentProp options. level-tree-index works equally well with string and buffer paths.

level-tree-index automatically keeps the tree updated as you add, change or delete from the database.

Usage

// db contains your data and idb is used to store the index
var tree = treeIndexer(db, idb);

db.put('1', {name: "foo"}, function(err) {
  if(err) fail(err);

  db.put('2', {parentKey: '1', name: "bar"}, function(err) {
    if(err) fail(err);

    db.put('3', {parentKey: '2', name: "baz"}, function(err) {
      if(err) fail(err);

      // wait for index to finish building
      setTimeout(function() {

        // stream child-paths of 'foo' recursively
        var s = tree.stream('foo');

        s.on('data', function(data) {
          console.log(data.path, data.key, data.value);
        });

      }, 500);
    });
  });
});

Read the unit tests in tests/ for more.

API

treeIndex(db, idb, [opts]) [constructor]

  • db: Your database to be indexed
  • idb: Database to use for storing the tree index

opts:

pathProp: 'name' // property used to construct the path
parentProp: 'parentKey' // property that references key of parent
sep: 0x1f, // path separator. can be string or unicode/ascii character code
pathArray: false, // for functions that output paths, output paths as arrays
ignore: false, // set to a function to selectively ignore 
listen: true, // listen for changes on db and update index automatically
uniquefy: false, // add uniqueProp to end of pathProp to ensure uniqueness
uniqProp: 'unique', // property used for uniqueness
uniqSep: 0x1e, // like `sep` but separates pathProp from uniqProp
levelup: false // if true, returns a levelup instance instead
orphanPath: 'orphans' // parent path of orphans

Both pathProp and parentProp can be either a string, a buffer or a function.

If a function is used then the function will be passed a value from your database as the only argument. The pathProp function is expected to return a string or buffer that will be used to construct the path by joining multiple returned pathProp values with the opts.sep value as separator. The parentProp function is expected to return the key in db of the parent.

opts.sep can be a buffer of a string and is used as a separator to construct the path to each node in the tree.

opts.ignore can be set to a function which will receive the key and value for each change and if it returns something truthy then that value will be ignored by the tree indexer, e.g:

Setting orphanPath to a string, buffer or array will cause all orphaned rows to have orphanPath as their parent path. Setting orphanPath to null will cause orphaned rows to be ignored (not indexed). An orphan is defined as a row with its parentProp set to a non-falsy value but where the referenced parent does not exist in the database. This can happen e.g. if a parent is deleted but its children are left in the database.

// ignore items where the .name property starts with an underscore
ignore: function(key, value) {
  if(typeof value === 'object') {
    if(typeof value.name === 'string') {
      if(value.name[0] === '_') {
        return true;
      }     
    }
  }
  return false;
}

If opts.listen is true then level-tree-index will listen to operations on db and automatically update the index. Otherwise the index will only be updated when .put/.del/batch is called directly on the level-tree-index instance. This option is ignored when opts.levelup is true.

If opts.levelup is true then instead of a level-tree-index instance a levelup instance will be returned with all of the standard levelup API + the level-tree-index API. All calls to .put, .del or .batch will operate on the database given as the db argument and only call their callbacks once the tree index has been updated.

Limitations when using levelup:true:

  • Chained batch mode is not implemented.
  • It is currently not possible not to wait for the tree index to update so it will take longer before the .put, .del and .batch callbacks are called.
  • Key and value encoding happens before the data gets to level-tree-index so opts.pathProp and opts.parentProp must be set to functions and if you're using valueEncoding:'json' then those functions will receive the stringified json data.

See tests/levelup.js for how to use the levelup:true mode.

.getRoot(cb)

Get the path and key of the root element. E.g:

tree.getRoot(function(err, path, key) {
  console.log("Path of root element:", path);
  console.log("Key of root element:", key);
});

.stream([parentPath], [opts])

Recursively stream descendants starting from parentPath. If parentPath is falsy then the entire tree will be streamed to the specified depth.

Opts:

depth: 0, // how many (grand)children deep to go. 0 means infinite
paths: true, // output the path for each child
keys: true, // output the key for each child
values: true, // output the value for each child
pathArray: undefined, // output paths as arrays
ignore: false, // optional function that returns true for values to ignore
match: null, // Stream only matching elements. A string, buffer or function.
matchAncestors: false, // include ancestors of matches if true
gt: undefined, // specify gt directly, must then also specify lt or lte
gte: undefined, // specify gte directly, must then also specify lt or lte
lt: undefined, // specify lt directly, must then also specify gt or gte
lte: undefined // specify lte directly, must then also specify lt or gte

If parentPath is not specified then .gt/.gte and .lt/.lte must be specified.

opts.depth is currently not usable at the same time as opts.match.

If more than one of opts.paths, opts.keys and opts.values is true then the stream will output objects with these as properties.

opts.ignore can be set to a function. This function will receive whatever the stream is about to output (which depends on opts.paths, opts.keys and opts.values) and if the function returns true then those values will not be emitted by the stream.

opts.match allows for streaming search queries on the tree. If set to a string or buffer it will match any path that contains that string or buffer. If set to a RegEx then it will run a .match on the path with that RegEx (only works for string paths). If set to a function then that function will be called with the path as first argument and with the second argument depending on the values of opts.paths, opts.keys and opts.values, e.g:

match: function(path, o) {
  if(o.value.name.match("cattens")) {
   return true;
  }
  return false;
}

Setting opts.matchAncestors to true modifies the behaviour of opts.match to also match all ancestors of matched elements. Ancestors of matched elements will then be streamed in the correct order before the matched element. This requires some buffering so may slow down matches on very large tree indexes.

When using opts.lt/opts.lte you can use the convenience function .lteKey(key). E.g. to stream all paths that begin with 'foo.bar' you could run:

levelTree.stream({
  gte: 'foo.bar',
  lte: levelTree.lteKey('foo.bar')
});

Keep in mind that the above example would also return paths like 'foo.barbar'.

.lteKey(key)

Convenience function that, according to leveldb alphabetical ordering, returns the last possible string or buffer that begins with the specified string or buffer.

.parentStream(path, [opts])

Stream tree index ancestor paths starting from path. Like .stream() but traverses ancestors instead of descendants.

Opts:

height: 0, // how many (grand)children up to go. 0 means infinite
includeCurrent: true, // include the node specified by path in the stream 
paths: true, // output the path for each child
keys: true, // output the key for each child
values: true, // output the value for each child
pathArray: undefined, // output paths as arrays

.parents(path, [opts], cb)

Same as .parentStream but calls back with the results as an array.

.getFromPath(path, cb)

Get key and value from path.

Callback: cb(err, key, value)

.path(key, [opts], cb)

Get tree path given a key.

opts.pathArray: undefined // if true, split path into array

Callback: cb(err, path)

.parentFromValue(value, cb)

Get parent value given a value.

Callback: cb(err, parentValue)

.parentPath(key, [opts], cb)

Get parent path given a key.

opts.pathArray: undefined // if true, split path into array

Callback: cb(err, parentPath)

.parentPathFromValue(key, [opts], cb)

Get parent path given a value.

opts.pathArray: undefined // if true, split path into array

Callback: cb(err, parentPath)

.parentFromPath(path, cb)

Get parent value given a path.

Callback: cb(err, parentValue)

.parentPathFromPath(path, [opts], cb)

Get parent path given a path.

opts.pathArray: undefined // if true, split path into array

Note: this function can be called synchronously

Callback: cb(err, parentPath)

.children(path, [opts], cb)

Get array of children given a value.

Same usage as .stream but this version isn't streaming.

Callback: cb(err, childArray)

.childrenFromKey(path, [opts], cb)

Same as .children but takes a key as input.

Same usage as .stream but this version isn't streaming.

Callback: cb(err, childArray)

.pathStream(parentPath, [opts])

Same as .stream with only opts.paths set to true.

.keyStream(parentPath, [opts])

Same as .stream with only opts.keys set to true.

.valueStream(parentPath, [opts])

Same as .stream with only opts.values set to true.

.clear(cb)

Clear the index. Deletes all of the index's data in the index db.

.build(cb)

Build the index from scratch.

Note: You will likely want to .clear the index first or call .rebuild instead.

.rebuild(cb)

Clear and then build the index.

.put(key, value, [opts], cb)

If you need to wait for the tree index to update after a .put operation then you can use .put directly on the level-tree-index instance and give it a callback. Calling .put this way is much less efficient so if you are planning to use this feature most of the time then you should look into using level-tree-index with the levelup:true option instead.

.del(key, [opts], cb)

Allows you to wait for the tree index to finish building using a callback. Same as .put above but for deletion.

Uniqueness

The way level-tree-index works requires that each indexed database entry has a globally unique path. In other words no two siblings can share the same pathProp.

You might get into a situation where you really need multiple siblings with an identical pathProp. Then you might wonder if you coulds just append e.g. a random string to each pathProp before passing it to level-tree-index and then strip it away again before e.g. showing the data to users.

Well, level-tree-index provides helpers for exactly that. You can set opts.uniquefy to true in the constructor. You will then need database each entry to have a property that, combined with its pathProp, makes it unique. This can be as simple as a long randomly generated string. As with pathProp you will have to inform level-tree-index about this property with uniqProp.

You will then run into the problem that you no longer know the actual path names since they have the uniqueness added. You can either get the actual path name using the synchronous function .getPathName(val) where val is the value from the key-value pair for which you want the path. Or you can call .put or .batch directly on your level-tree-index instance and they will pass your callback a second argument which for .put is the actual path name and for .batch is an array of path names for all put operations.

When uniqefy is turned on any functions returning paths will now be returning paths with the uniqueness data appended. You can use the convenience function .nicify(path) to convert these paths into normal paths without the uniqueness data. For .stream and any functions described as "same as .stream but ..." you can add set opts.nicePaths to true and in you will receive the nicified paths back with each result.

Async quirks

Note that when you call .put, .del or .batch on your database level-tree-index will not be able to delay the callback so you cannot expect the tree index to be up to date when the callback is called. That is why you see the setTimeout used in the usage example above. You can instead call .put, .del or .batch directly on the level-tree-index instance and your callback will not be called until the index has finished building. This works but if opts.listen is set to true then an inefficient and inelegant workaround is used (in order to prevent the change listener from attempting to update the already updated index) which could potentially slow things down.

If you want to wait for the index to update most of the time then you should probably either set opts.listen to false or use the levelup mode by calling the constructor with opts.levelup set to true, though that has its own drawbacks, especially if using valueEncoding:'json'. See the constructor API documentation for more.

Technical explanation

I normal operation (opts.levelup == false) level-tree-index will listen for any changes on your database and update its index every time a change occurs. This is implemented using leveup change event listeners which run after the database operation has already completed.

When running .put or .del directly on level-tree-index the operation is performed on the underlying database then the tree index is updated and then the callback is called. Since we can't turn off the change event listeners for a specific operation, level-tree-index has to remember the operations performed directly through .put or .del on the level-tree-index instance such that the change event listener can ignore them to prevent the tree-index update operation from being called twice. This is done by hashing the entire operation, saving the hash and then checking the hash of each operation picked up by the change event listeners agains the saved hash. This is obviously inefficient. If this feature is never used then nothing is ever hashed nor compared so performance will not be impacted.

ToDo

Before version 1.0

  • Get opts.depth working with opts.match.

Author: Biobricks
Source Code: https://github.com/biobricks/level-tree-index 
License: AGPLv3

#javascript #tree #index #leveldb 

Arnulfo Johnson

Arnulfo Johnson

1657572120

Level-tree: R-tree Spatial index for GeoJSON in LevelDB

Level Tree

An RTree index for levelup, usage

npm install --save level-tree
var level = require('level');
var sublevel = require('level-sublevel');
var levelTree = require('level-tree');
var db = levelTree(sublevel(level('./name')));
// load in some geojson
db.treeQuery([xmin, ymin, xmax, ymax]).pipe();
db.treeQuery([xmin, ymin, xmax, ymax], callback);
// nonstrict query
db.treeQuery([xmin, ymin, xmax, ymax], false).pipe();
db.treeQuery([xmin, ymin, xmax, ymax], false, callback);

adds a treeQuery method, which either takes a bbox and returns a stream, or a bbox and a callback.

you can also pass false as the second argument to treeQuery, this turns off checks to make sure that the bbox you query actually intersects the feature that is returned and not just it's bbox. These checks can be very expensive especially for polygons so turning them off when you have mostly rectangular features or when you just don't care will speed things up.

Author: Calvinmetcalf
Source Code: https://github.com/calvinmetcalf/level-tree 
License: MIT license

#javascript #tree #json #node #leveldb 

Dexter Goodwin

Dexter Goodwin

1657228320

Level-indexer: Generic Property indexer for Leveldb

level-indexer

Generic indexer for leveldb. Only stores document keys for space efficiency.

npm install level-indexer

Usage

var indexer = require('level-indexer')

// create a index (by country)
var country = indexer(db, ['country']) // index by country

country.add({
  key: 'mafintosh',
  name: 'mathias',
  country: 'denmark'
})

country.add({
  key: 'maxogden',
  name: 'max',
  country: 'united states'
})

var stream = country.find({
  gte:{country:'denmark'},
  lte:{country:'denmark'}
})

// or using the shorthand syntax

var stream = country.find('denmark')

stream.on('data', function(key) {
  console.log(key) // will print mafintosh
})

The stored index is prefix with the index key names which means you can use the same levelup instance to store multiple indexes.

API

index = indexer(db, [prop1, prop2, ...], [options])

Creates a new index using the given properties. Options include

{
  map: function(key, cb) {
    // map find results to another value
    db.get(key, cb)
  }
}

index.add(doc, [key], [cb])

Add a document to the index. The document needs to have a key or provide one. Only the key will be stored in the index.

index.remove(doc, [key], [cb])

Remove a document from the index.

index.key(doc, [key])

Returns the used leveldb key. Useful if you want to batch multiple index updates together yourself

var batch = [{type:'put', key:index.key(doc), value:doc.key}, ...]

stream = index.find(options, [cb])

Search the index. Use options.{gt,gte,lt,lte} to scope your search.

// find everyone in the age range 20-50 in denmark

var index = indexer(db, ['country', 'age'])

...
var stream = index.find({
  gt: {
    country: 'denmark',
    age: 20
  },
  lt: {
    country: 'denmark',
    age: 50
  }
})

Optionally you can specify the ranges using arrays

var stream = index.find({
  gt: ['denmark', 20],
  lt: ['denmark', 50]
})

Or if you do not care about ranges

var stream = index.find(['denmark', 20])

// equivalent to

var stream = index.find({
  gte: ['denmark', 20],
  lte: ['denmark', 20]
})

The stream will contain the keys of the documents that where found in the index. Use options.map to map the to the document values.

Options also include the regular levelup db.createReadStream options.

If you set cb the stream will be buffered and passed as an array.

index.findOne(options, cb)

Only find the first match in the index and pass that to the callbck

Author: Mafintosh
Source Code: https://github.com/mafintosh/level-indexer 
License: MIT license

#javascript #index #leveldb 

Dexter Goodwin

Dexter Goodwin

1657186080

Level-index-update: A Batch index Updater for Leveldb

level-index-update

A module to save a document into leveldb where the old indexes are removed in the same batch as the new ones are inserted

It loads the old document and creates a single batch of 'del' and 'put' commands from the mapper function you provide.

It can also expand a batch of multiple documents into a single larger batch containing the index 'put' and 'del' commands for each document.

This is a cumbersome way to do it and there are limitations but hey - life is short and suggestions (like how to manage an immutable collection of indexes for changing values) are welcome : )

example

var level = require('level');
var sub = require('level-sublevel');
var indexupdate = require('level-index-update');

var db = sub(level(__dirname + '/pathdb', {
     valueEncoding: 'json'
}))

var indexer = indexupdate(db.sublevel('docs'), '_indexes', function(key, value, emit){

    // you can emit multiple indexes per value
    emit(['color', value.color])
    emit(['heightcolor', value.height, value.color])

})

indexer.save('/my/path', {
    height:50,
    color:'red'
}, function(err, batch){

    console.dir(batch);
    // [{type:'put', key:'/my/path', value:'{color:"red",height:50}'},
    // {type:'put', key:'color~red~/my/path'},
    // {type:'put', key:'heightcolor~red~50~/my/path'}]

    // the index for red is inserted

    indexer.save('/my/path', {
        height:45,
        color:'blue'
    }, function(err, batch){

        console.dir(batch);
        // {type:'put', key:'/my/path', value:'{color:"blue",height:45}'},
        // {type:'del', key:'color~red~/my/path'},
        // {type:'del', key:'heightcolor~50~red~/my/path'},
        // {type:'put', key:'color~blue~/my/path'},
        // {type:'put', key:'heightcolor~45~blue~/my/path'}]

        // the index for red is deleted and the index for blue is inserted
    })
    
})

You can also insert a batch of documents and it will auto-expand the batch for the indexes:

indexer.batch([{
    key:'/my/path',
    color:'red',
    height:50
},{
    key:'/my/otherpath',
    color:'blue',
    height:45
}], function(err, batch){
    console.dir(batch);

    // [{type:'put', key:'/my/path', value:'{color:"blue",height:45}'},
    // {type:'put', key:'color~red~/my/path'},
    // {type:'put', key:'heightcolor~50~red~/my/path'},
    // {type:'put', key:'/my/otherpath', value:'{color:"blue",height:45}'},
    // {type:'put', key:'color~blue~/my/otherpath'},
    // {type:'put', key:'heightcolor~45~blue~/my/otherpath'}],

})

api

var indexer = indexupdate(db, [indexpath], mapper)

Create an updater function by passing a leveldb, an optional path to write the indexes (defaults to 'updateindex') and a mapper function that will emit the index fields and values for each value

indexer.save(key, value, callback(err, batch))

Run the updater function by passing the key and the value for the update.

The callback will be passed the batch that was inserted into the database.

indexer.expandBatch(arr, callback(err, batch))

Pass a batch of commands and it will convert into a larger batch with all the indexes for each 'put' and 'del' resolved.

indexer.batch(arr, callback(err, batch))

Uses expandBatch and then actually runs the batch

mapper(key, value, emit([values], manualkey))

The mapper function is called for each update - once for the old values and once for the new values

Call emit with an array of values to index based on the passed object

You can call emit many times per object - the key will be added to the index entry automatically

Pass an array of values to the indexer - the key will automatically be appended.

If you want to manually manage the index but still want the batch behavious, pass true as the second argument to emit:


var indexer = indexupdate(db.sublevel('docs'), '_indexes', function(key, value, emit){

    // manually manage the index structure
    emit(['color', value.color, key, '__', new Date().getTime()], true)

})

todo

  • handle if a save request for a key arrives whilst another is resolving

Author: Binocarlos
Source Code: https://github.com/binocarlos/level-index-update 
License: MIT license

#javascript #index #leveldb 

Lawrence Lesch

Lawrence Lesch

1657232640

Level-secondary: Secondary indexes for Leveldb

level-secondary

Secondary indexes for leveldb.

Example

Create 2 indexes on top of a posts database.

var level = require('level');
var Secondary = require('level-secondary');
var sub = require('level-sublevel');

var db = sub(level(__dirname + '/db', {
  valueEncoding: 'json'
}));

var posts = db.sublevel('posts');

// add a title index
posts.byTitle = Secondary(posts, 'title');

// add a length index
// append the post.id for unique indexes with possibly overlapping values
posts.byLength = Secondary(posts, 'length', function(post){
  return post.body.length + '!' + post.id;
});

posts.put('1337', {
  id: '1337',
  title: 'a title',
  body: 'lorem ipsum'
}, function(err) {
  if (err) throw err;

  posts.byTitle.get('a title', function(err, post) {
    if (err) throw err;
    console.log('get', post);
    // => get: { id: '1337', title: 'a title', body: 'lorem ipsum' }

    posts.del('1337', function(err) {
      if (err) throw err;
      posts.byTitle.get('a title', function(err) {
        console.log(err.name);
        // => NotFoundError
      });
    });
  });

  posts.byLength.createReadStream({
    start: 10,
    end: 20
  }).on('data', console.log.bind(console, 'read'));
  // => read { key: '1337', value: { id: '1337', title: 'a title', body: 'lorem ipsum' } }

  posts.byLength.createKeyStream({
    start: 10,
    end: 20
  }).on('data', console.log.bind(console, 'key'));
  // => key 1337

  posts.byLength.createValueStream({
    start: 10,
    end: 20
  }).on('data', console.log.bind(console, 'value'));
  // => value { id: '1337', title: 'a title', body: 'lorem ipsum' }
});

API

Secondary(db, name[, reduce])

Return a secondary index that either indexes property name or uses a custom reduce function to map values to indexes.

Secondary#get(key, opts[, cb])

Get the value that has been indexed with key.

Secondary#create{Key,Value,Read}Stream(opts)

Create a readable stream that has indexes as keys and indexed data as values.

Secondary#manifest

A level manifest that you can pass to multilevel.

Breaking changes

1.0.0

What used to be

db = Secondary('name', db);

is now

db.byName = Secondary(db, 'name');

Also hooks are used, so it works perfectly with batches across multiple sublevels.

Installation

With npm do:

npm install level-secondary

Author: juliangruber
Source Code: https://github.com/juliangruber/level-secondary 
License: MIT

#javascript #index #leveldb