db.save('airlines', 'KLM', {fleet: 111, country: 'NL'}, { links:
[{ bucket: 'flights', key: 'KLM-8098', tag: 'cargo' },
{ bucket: 'flights', key: 'KLM-1196', tag: 'passenger' }]
})
db.getAll('flights', { where: { ready: true }})
// npm install riak-js@latest
var db = require('riak-js').getClient()
// git clone git://github.com/frank06/riak-js.git # or cloning the repo
var db = require('/path/to/riak-js/lib').getClient()
There are two APIs: http
and protobuf
. Just ask for them: getClient({api: 'protobuf'})
.
HTTP is the default and what the following API guide is based upon. Expect similar behaviour for the Protocol Buffers interface, but keep in mind it is lagging a bit behind. One example is that the HTTP implementation internally queues requests and issues them serially. Reason why there are no race conditions in this guide only for HTTP.
db.get('flights', 'KLM-5034', function(err, flight, meta) {
if (err) throw err
flight.status = 'delayed'
meta.links.push({ bucket: 'airlines', key: 'IBE', tag: 'operated_by' })
db.save('flights', 'KLM-5034', flight, meta)
})
Meta is an important concept in riak-js. It is a implementation-agnostic object that carries all metadata associated to a document, such as the bucket, key, vclock, links, and so on. It is meant to be recycled — all properties that make sense to be updated for a subsequent store operation can be modified and sent back. Any given properties that aren't used by Riak are assumed to be custom metadata for Riak values. This will become more clear as we go through the guide.
An example meta
object could look like:
{ bucket: 'riakjs_airlines'
, key: 'CPA'
, usermeta: { important: false }
, _type: 'application/json'
, binary: false
, links:
[ { tag: 'flight'
, key: 'CPA-729'
, bucket: 'riakjs_client_test_flights'
}
]
, raw: 'riak'
, clientId: 'riak-js'
, host: 'localhost'
, vclock: 'a85hYGBgymDKBVIsTO+1QzKYEhnzWBm+rRc6xgcRZmtOYvg6tx4q8QMkkQUA'
, lastMod: 'Sat, 25 Sep 2010 17:40:08 GMT'
, etag: '8I9CsEwo8kScElgvCOC0k'
, statusCode: 200
}
Riak properties such as 'contentType', 'vclock', 'clientId', 'links', 'etag', 'r', 'w', 'dw', 'returnBody'
can be set on this object. It also contains handy methods to deal with links, and provides sensible defaults, which can of course be overriden.
Examples are contentType: 'application/json'
and clientId: 'riak-js'
. Note that you cannot change host or port once the client is instantiated.
Not only these are tunable per-request. If you need certain defaults to apply to the whole session,
provide them at initialization time: getClient({clientId: 'lan-27', raw: 'data', debug: false})
.
fs.readFile("drunk-pilot.png", 'binary', function (err, image) {
if (err) throw err;
db.save('evidence', 'pilot-smith-drunk', image, { contentType: 'jpeg', immediateAction: 'fire' })
});
Note that 'jpeg'
is a shortcut and immediateAction
is custom metadata.
Buffer
s are only returned when the responseEncoding
property is set to binary
.
This happens automatically for known binary types, such as image/*
, video/*
or
application/octet-stream
, otherwise you have to provide yourself through Meta
.
If you don't provide a content type while sending a request body, riak-js will do its best to guess one:
Buffer
it will assume application/octet-stream
typeof
yields object
, it will assume application/json
text/plain
db.save('flights', 'KLM-5034', flight)
riak-js follows the Node convention: last argument is the callback, whose first argument is the err
variable.
If you don't provide a callback the result will be logged through console.log
.
All commands take two optional last arguments: meta
(options) and callback
,
in that order, and so they will not necessarily be shown below.
db.get('airlines', 'KLM')
A typical response would be:
{ name: 'KLM'
, fleet: 111
, alliance: 'SkyTeam'
, european: true
}
If, however, there is a sibling conflict (when allow_mult = true
) then a typical response would have a meta.statusCode = 300
and would look like:
[ { meta:
{ bucket: 'airlines'
, key: 'KLM'
, usermeta: {}
, _type: 'application/json'
, binary: false
, links: []
, raw: 'riak'
, clientId: 'riak-js'
, host: 'localhost'
, lastMod: 'Sun, 26 Sep 2010 16:28:17 GMT'
, etag: '5QDmB8ezT8hpMNX9Ias8DU'
, vclock: 'a85hYGBgymDKBVIsTO+1QzKYEhnzWBkWfhA+xgcRZmtOYlvXp4MskQUA'
}
, data: { name: 'KLM'
, fleet: 111
, alliance: 'SkyTeam'
, european: true
}
}
, { meta:
{ bucket: 'airlines'
, key: 'KLM'
, usermeta: {}
, _type: 'application/json'
, binary: false
, links: []
, raw: 'riak'
, clientId: 'riak-js'
, host: 'localhost'
, lastMod: 'Sun, 26 Sep 2010 16:28:17 GMT'
, etag: '4wz9tAlKC49RVqQmhcAvHz'
, vclock: 'a85hYGBgymDKBVIsTO+1QzKYEhnzWBkWfhA+xgcRZmtOYlvXp4MskQUA'
}
, data: { name: 'KLM'
, fleet: 113
, alliance: 'SkyTeam'
, european: true
}
}
]
Head will only get the meta
object back — no data. (It uses the HTTP HEAD verb under the hood.)
db.head('airlines', 'KLM')
Exists is a shortcut to tell you if a document exists or not. Internally, it uses head
and checks for a 404
.
db.exists('airlines', 'AIR_FRIGGIN_MADRID')
Just like as with the sibling conflict, getAll
will return an Array
of Object
s
with the meta
and data
properties. withId
is no longer necessary:
you can grab the key from meta.key
.
db.getAll('airlines')
db.getAll('airlines', { where: { country: 'NL', fleet: 111 } })
db.keys('airlines')
db.count('airlines')
db.walk('airlines', 'KLM', [["_", "flight"]])
db.save('airlines', 'ARG', { name: 'Aerolíneas Argentinas', fleet: 40, european: false })
db.save('flights', 'KLM-5034', flight, { returnBody: true, dw: 'quorum', method: 'POST' })
db.remove('airlines', 'KLM')
db.add('albums').map({name: 'Riak.mapValuesJson'}).run()
You can chain any number of phases or pass arrays, too:
db
.add('airlines')
.link({ bucket: 'flights', keep: false })
.map('Riak.mapValuesJson')
.reduce(['Riak.filterNotFound', function(value, count) { return value.slice(0, count - 1) }])
.run(function(err, flights) {
console.log(flights)
})
These commands (getLarge
, saveLarge
, removeLarge
) behave much like
their counterparts get
, save
, remove
.
Except they don't take a bucket
argument, internally reference the luwak
raw resource, and always use responseEncoding = 'binary'
therefore returning Buffer
s.
db.getLarge('lowcost-pilot')
db.saveLarge('lowcost-pilot', buffer)
db.removeLarge('lowcost-pilot')
callback
db.ping()
callback
db.stats()
db.updateProps('airlines', { n_val: 8, allow_mult: true })
props
property
db.getProps('airlines')
Please report issues here.
Run this in the main directory to compile coffeescript to javascript as you go:
cake dev
Checkout the spec
folder.
Test with cake test
. Requires Vows 0.5.2.