Riak client with stream interfaces using protocol buffers
npm install riakdb
riakdb is simple. Create the client, call
.connect and make the
requests. It is important to note that
riakdb comes with two interfaces.
- A low level interface, there directly maps to the Riak protocol
- A high level interface, made for node.js
var riakdb = ;var client =;client;client;
The documentation is separated intro three parts:
Discusses how to setup and configure the Riak connection pool and the associated events.
riakdb comes with two interfaces for communicating with Riak. Generally there
is no difference, however in some cases a convenient abstraction is put around
the underlying low level interace, to make it easier to use.
An example of this is the
.getKeys(request) (stream of all keys in bucket). In
this case Riak returns a paginated stream, meaning that each item can contain
multiply keys. The high level interface performs a depagination such that each
item contain just a single key.
Because of the wast amount of features in Riak, some high level methods may not support all the features of the corresponding low level method.
To give better backward compatibility and ensure that all features in Riak are supported a low level interface is also provided. This is a direct mapping to the Riak protocol buffer definition, with nothing on top. This uses the protocol-buffers module, so the encoding and decoding behaviour is defined by that.
client = RiakClient(settings)
The main export from
riakdb is the
RiakClient constructor function.
The constructor takes a settings object with some required and some
var riakdb = ;var client =;
settings object takes the following properties:
nodes(required): An array of address objects, these objects are used in the
net.connectfunction and thus takes the same arguments. But usually you only need
minConnections(default 0): The minimum amount of connection there should always exists. It is possible to have more connections, but these will only be created when the amount of parallel requests exceeds
maxConnections(default 20): The maximum amount of requests. If all connections are in use and
maxConnectionsprevents more connections from being created. Then the requests will be buffered.
connectionTimeout(default 60000, 1 min): If a connection haven't made any requests within
connectionTimeoutms and there is than
minConnectionsactive connections, then this connection will be closed.
The client won't start connecting before
client.connect() is called. Until
then requests will be buffered.
client.close() is called, all connections are closed. This means that
active requests won't get a response, but they will get an error. Buffered
requests will also not be send.
client.enums contains the enum objects associated with the riak protocol
buffer message definitions. The enum objects are:
minConnections amount of connections are created then this event
is fired. If
minConnections is zero, then the
connect event is fired on
the next tick.
When all connections are closed after a
client.close() call, then this event
Errors there happens on the connection sockets will be emitted here. If there
is an active request on that connection then the
also be notified.
High level interface
Note that if there is no defined high level function, then the same method
definitions there is in
client.low[method] also exists in
A depaginized version of
client.low.getKeys. This means that each stream item
contains only one key. This is different from the direct protocol mapping, where
each item can contain multiply keys.
A depaginized version of
client.low.getIndex. By default each item will
contain a key. This abstraction does not support
continuation. If you need
this please make a pull request or use
return_terms is used each item is an object with the
client.mapred takes a
request object, this will be used as the
content_type is also set to
application/json. The other
application/x-erlang-binary is not supported, if you need this make a pull
request or use
client.mapred expects the response to be
JSON encoded. The response is
parsed and depaginized, such that each stream item contains the
and a single
Low level interface
The low level interface have two response types
both cases the function takes a
request object as the first argument. There
are a few exceptions/details to this pattern:
In some cases (e.q.
ping) there is no request parameters and thus there is no
Some stream requests, requires you to set a request parameter there makes Riak return a stream and not a single message. These are marked with
Example on a
callback response with a request
Example on a
callback response with no
Example on a
stream response with a request
Example on a
stream response with a required stream parameter
Full list of methods
This is a complete list of all the documented Riak requests, with a mapping to the method name, response type and link to the request and response structure (protocol).
|Get Bucket Properties||
|Set Bucket Properties||
|Reset Bucket Properties||
|Bucket Type Operations|
|Get Bucket Type||
|Set Bucket Type||
|Data Type Operations|
|Data Type Fetch||
|Data Type Store||
|Yokozuna Index Get||
|Yokozuna Index Put||
|Yokozuna Index Delete||
|Yokozuna Schema Get||
|Yokozuna Schema Put||
This software is licensed under "MIT"
Copyright (c) 2015 Andreas Madsen
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.