Table Of Contents

6.12. Node.js

6.12.1. Quick Reference

Return type Name Arguments
Tag.getEntries() (callback(err, entities))
Integer.add() (value, callback(err, data))
Integer.remove() (callback)
Integer.get() (callback(err, data))
Integer.update() (value, expiry_time, callback(err))
Integer.put() (value, expiry_time, callback(err))
Error.code() ()
Error.message() ()
Error.severity() ()
Error.origin() ()
Error.informational() ()
Deque.setAt() (index, callback(err, data))
Deque.at() (index, callback(err, data))
Deque.size() (callback(err, size))
Deque.back() (callback(err, data))
Deque.front() (callback(err, data))
Deque.popBack() (callback(err, data))
Deque.popFront() (callback(err, data))
Deque.pushBack() (content, callback(err))
Deque.pushFront() (content, callback(err))
Cluster.setTimeout() (timeout)
Cluster.getTimeout() ()
Cluster.ts() (alias)
Cluster.tag() (tagName)
Cluster.suffix() (suffix)
Cluster.range() ()
Cluster.queryFind() (Query)
Cluster.prefix() (prefix)
Cluster.integer() (alias)
Cluster.deque() (alias)
Cluster.blob() (alias)
Cluster.connect() (callback(), callback_on_failure(err))
Blob.get() (callback(err, data))
Blob.update() (content, expiry_time, callback(err))
Blob.put() (content, expiry_time, callback(err))
ExpirableEntity.getExpiry() ()
ExpirableEntity.expiresFromNow() (seconds, callback(err))
ExpirableEntity.expiresAt() (expiry_time, callback(err))
Entity.getTags() (callback(err, tags))
Entity.hasTags() (tagNames, callback(err, success_count, result))
Entity.hasTag() (tagName, callback(err))
Entity.detachTags() (tagNames, callback(err))
Entity.detachTag() (tagName, callback(err))
Entity.attachTags() (tagNames, callback(err))
Entity.attachTag() (tagName, callback(err))
Entity.remove() (callback(err))
Entity.alias() ()

6.12.2. Introduction

Using quasardb cluster from a Node.js installation is extremely straightforward, just create a qdb.Cluster and perform the operations.

var qdb = require('./qdb');

var c = new qdb.Cluster('qdb://127.0.0.1:2836');
var b = c.blob('key 0');

b.put(new Buffer('value 0'), function(err) {});
b.get(new Buffer('key 0'), function(err, data) {
    console.log(data);
});

You may download the Node.js API from the quasardb site or from GitHub at https://github.com/bureau14/qdb-api-nodejs.

6.12.3. Requirements and Installation

To build the Node.js API, you will need the C API. It can either be installed on the machine (e.g. on Unix in /usr/lib or /usr/local/lib) or you can unpack the C API archive in deps/qdb.

You will need to have node-gyp installed.

In the directory run:

npm install

You will then find a qdb.node file which is the quasardb add-on in build/Release directory.

6.12.4. Reference

The Entity interface

Entity is the base interface for all entry classes stored in quasardb. All the classes inherit the following methods.

class Entity()
Entity.alias()

Returns the alias of the entity

Returns:A string representing the alias of the Entity
Entity.remove(callback(err))

Removes the Entity

Arguments:
  • callback(err) (function) – A callback function with error parameter
Returns:

A string representing the alias of the Entity

Entity.attachTag(String tagName, callback(err))

Attaches the Entity to the specified tag. Errors if the tag is already assigned.

Arguments:
  • tagName (String) – The name of the tag.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Entity.attachTags(String[] tagNames, callback(err))

Attaches the Entity to the specified tags. Errors if any of the tags is already assigned.

Arguments:
  • tagNames (String[]) – Array of names of the tags (Array of Strings).
  • callback(err) (function) – A callback or anonymous function with error parameter.
Entity.detachTag(String tagName, callback(err))

Detaches the Entity from the specified tag. Errors if the tag is not assigned.

Arguments:
  • tagName (String) – The name of the tag.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Entity.detachTags(String[] tagNames, callback(err))

Detaches the Entity from the specified tags. Errors if any of the tags is not assigned.

Arguments:
  • tagNames (String[]) – Array of names of the tags (Array of Strings).
  • callback(err) (function) – A callback or anonymous function with error parameter.
Entity.hasTag(String tagName, callback(err))

Determines if the Entity has the specified tag.

Arguments:
  • tagName (String) – The name of the tag.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Entity.hasTags(String[] tagNames, callback(err, success_count, result))

Determines if the Entity has the specified tags.

Arguments:
  • tagNames (String[]) – Array of names of the tags (Array of Strings).
  • callback(err, success_count, result) (function) – A callback or anonymous function with: error parameter, number of specified tags assigned to the Entity and query result. Result is an Object with as many fields as the length of tagNames array, each having a bool value true (tag assigned) or false (otherwise).
Entity.getTags(callback(err, tags))

Gets an array of tag objects associated with the Entity.

Arguments:
  • callback(err, tags) (function) – A callback or anonymous function with error and array of tags parameters.

The ExpirableEntity interface

Entity is the base interface for entry classes that may expire, i.e. be removed from the database automatically at some time point or after some time (duration). ExpirableEntity is inherited by Blob and Integer. These classes inherit the following methods.

class ExpirableEntity()
ExpirableEntity.expiresAt(Date expiry_time, callback(err))

Sets the expiration time for the ExpirableEntity at a given Date.

Arguments:
  • expiry_time (Date) – A Date at which the ExpirableEntity expires.
  • callback(err) (function) – A callback or anonymous function with error parameter.
ExpirableEntity.expiresFromNow(int seconds, callback(err))

Sets the expiration time for the ExpirableEntity as a number of seconds from call time.

Arguments:
  • seconds (int) – A number of seconds from call time at which the ExpirableEntity expires.
  • callback(err) (function) – A callback or anonymous function with error parameter.
ExpirableEntity.getExpiry()

Gets the expiration time of the ExpirableEntity.

The Blob class

Represents a blob in a quasardb database. Blob stands for Binary Large Object, meaning that you can store arbitrary data in this blob.

You get a Blob instance by calling Cluster.blob(). Then you can perform atomic operations on the blob:

var b = c.blob('bam');

b.put(new Buffer("boom"), function(err) { /* */  });
b.get(function(err, data) { /* */  });

Passing in the blob value wrapped in the node::Buffer class is important, as JavaScript does not play nice with binary data.

class Blob()
Blob.put(Buffer content, Date expiry_time, callback(err))

Sets blob’s content but fails if the blob already exists. See also update().

Arguments:
  • content (Buffer) – A string representing the blob’s content to be set.
  • expiry_time (Date) – An optional Date with the absolute time at which the entry should expire.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Blob.update(Buffer content, Date expiry_time, callback(err))

Updates the content of the blob.

Arguments:
  • content (Buffer) – A Buffer representing the blob’s content to be added.
  • expiry_time (Date) – An optional Date with the absolute time at which the entry should expire.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Blob.get(callback(err, data))

Retrieves the blob’s content, passes to callback as data.

Arguments:
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.

The Cluster class

Represents a connection to a quasardb cluster.

Example:

var qdb = require('./qdb');

var c = new qdb.Cluster('qdb://127.0.0.1:2836');
c.blob('key 0');
c.deque('key 1');
c.integer('key 2');
c.integer('key 3');
class Cluster()
Cluster.connect(callback(), callback_on_failure(err))

Connects to a quasardb cluster. The successful function is run when the connection is made. The failure callback is called for major errors such as disconnections from the cluster after the connection is successful.

Arguments:
  • callback() (function) – A callback or anonymous function without parameters.
  • callback_on_failure(err) (function) – A callback or anonymous function with error parameter.
Cluster.blob(String alias)

Creates a Blob associated with the specified alias. No query is performed at this point.

Arguments:
  • alias (String) – the alias of the blob in the database.
Returns:

the Blob

Cluster.deque(String alias)

Creates a Deque associated with the specified alias. No query is performed at this point.

Arguments:
  • alias (String) – The alias of the deque in the database
Returns:

the Deque

Cluster.integer(String alias)

Creates an Integer associated with the specified alias. No query is performed at this point.

Arguments:
  • alias (String) – the alias of the integer in the database.
Returns:

the Integer

Cluster.prefix(String prefix)

Retrieves aliases with the input prefix argument

Arguments:
  • prefix (String) – The prefix to search for.
Returns:

the Prefix

Cluster.queryFind(String Query)

Retrieves list of aliases that matches the query condition

Arguments:
  • Query (String) – the query string
Returns:

List of matched aliases.

Cluster.range()

Returns a range object which supports BlobScan, BlobScanRegex

Returns:The Range object
Cluster.suffix(String suffix)

Retrieves aliases with the input suffix argument

Arguments:
  • suffix (String) – The prefix to search for.
Returns:

the Suffix

Cluster.tag(String tagName)

Creates a Tag with the specified name.

Arguments:
  • tagName (String) – the name of the tag in the database.
Returns:

the Tag

Cluster.ts(String alias)

Creates a timeseries object with the given alias

Arguments:
  • alias (String) – the name of the timeseries
Returns:

the ts object

Cluster.getTimeout()

Returns the current set timeout in milliseconds

Returns:Current set timeout in milliseconds
Cluster.setTimeout(Integer timeout)

Set the current timeout in milliseconds

Arguments:
  • timeout (Integer) – this timeout is in milliseconds

The Deque class

Represents a double-ended queue of blob in the quasardb database. You can both enqueue and dequeue from the front and the back.

You get a Deque instance by calling Cluster.deque(). Then you can perform atomic operations on the queue:

var q = c.deque('q2');
q.pushBack(new Buffer("boom"), function(err) { /* */ });
q.popFront(function(err, data) { /* */ });
q.pushFront(new Buffer("bang"), function(err) { /* */ });

Passing in the blob value wrapped in the node::Buffer class is important, as JavaScript does not play nice with binary data.

class Deque()
Deque.pushFront(Buffer content, callback(err))

Add a value to the front of the queue.

Arguments:
  • content (Buffer) – The value to add to the queue.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Deque.pushBack(Buffer content, callback(err))

Add a value to the back of the queue.

Arguments:
  • content (Buffer) – The value to add to the queue.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Deque.popFront(callback(err, data))

Remove the value at the front of the queue and return it.

Arguments:
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.
Deque.popBack(callback(err, data))

Remove the value at the end of the queue and return it.

Arguments:
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.
Deque.front(callback(err, data))

Retrieves the value at the front of the queue, without removing it.

Arguments:
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.
Deque.back(callback(err, data))

Retrieves the value at the end of the queue, without removing it.

Arguments:
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.
Deque.size(callback(err, size))

Returns the size of the Deque.

Arguments:
  • callback(err, size) (function) – A callback or anonymous function with error and size parameters.
Deque.at(Integer index, callback(err, data))

Retrieves the value at the index in the queue. The item at the index must exist or it will throw an error.

Arguments:
  • index (Integer) – The index of the object in the Deque.
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.
Deque.setAt(Integer index, callback(err, data))

Sets the value at the index in the deque.

Arguments:
  • index (Integer) – The index of the object in the Deque.
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.

The Error class

quasardb callbacks return error messages. When the callback is successful, the error object is null. You may not want to throw at every error: some errors are transient and some are informational. You can check their types with the transient and informational methods.

Transient errors may resolve by themselves given time. Transient errors are commonly transaction conflicts, network timeouts, or an unstable cluster.

An informational error means that the query has been successfully processed by the server and your parameters were valid but the result is either empty or unavailable. Informational errors include non-existent entries, empty collections, indexes out of range, or integer overflow/underflows.

Example:

var b = c.blob('bam');

b.put(new Buffer("boom"), function(err)
{
    if (err)
    {
        // error management
        throw error.message;
    }

    // ...
});
class Error()
Error.informational()

Determines if the error is an informational error.

Returns:True if the error is informational, false otherwise.
Error.origin()

Gets the origin of the error

Returns:A string containing the origin of the error.
Error.severity()

Gets the severity of the errror

Returns:A string containing the severity of the error.
Error.message()

Gets a description of the error.

Returns:A string containing the error message.
Error.code()

Gets the error code.

Returns:An integer with the error code.

The Integer class

Represents an signed 64-bit integer in a quasardb database.

You get an Integer instance by calling Cluster.integer(). Then you can perform atomic operations on the integer:

var i = c.integer('will_be_ten');
i.put(3, function(err){ /* */});
i.add(7, function(err, data){ /* */});
class Integer()
Integer.put(int value, Date expiry_time, callback(err))

put a new entry, with an optional expiry time

Arguments:
  • value (int) – The value of the integer.
  • expiry_time (Date) – An optional Date with the absolute time at which the entry should expire.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Integer.update(int value, Date expiry_time, callback(err))

put a new entry, with an optional expiry time

Arguments:
  • value (int) – The value of the integer.
  • expiry_time (Date) – An optional Date with the absolute time at which the entry should expire.
  • callback(err) (function) – A callback or anonymous function with error parameter.
Integer.get(callback(err, data))

return the alias content

Arguments:
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.
Integer.remove(err callback)

remove the alias

Arguments:
  • callback (err) – A callback function with error parameter
Integer.add(int value, callback(err, data))

Atomically increment the value in the database.

Arguments:
  • value (int) – The value to add to the value in the database.
  • callback(err, data) (function) – A callback or anonymous function with error and data parameters.

The Tag class

Represents a tag in a quasardb database. Any entry can be tagged, including other tags. Most tag functions are performed on the object itself:

var b = c.blob('myBlob');

b.put(new Buffer("boom"), function(err) { /* */  });
b.attachTag('myTag', function(err) { /* */  });
b.hasTag('myTag', function(err) { /* */ });
b.getTags(function(err, tags) { /* */ });
b.detachTag('myTag', function(err) { /* */ } );

You can create a Tag instance by calling Cluster.tag(). Then, you can look up entries by their association with the tag:

var t = c.tag('myTag');

t.getEntries(function(err, entries} { /* entries is the list of entries */ });
class Tag()
Tag.getEntries(callback(err, entities))

Gets an array of entities associated with the Tag.

Arguments:
  • callback(err, entities) (function) – A callback or anonymous function with error and array of entities parameters.