Orchestrate is a database service. It is a simple REST API that is optimized for queries. Orchestrate combines full-text search, graph, time-series, and key/value.
Node Driver for Orchestrate.io.
$ npm install orchestrate
Currently, Orchestrate.js runs against the actual Orchestrate API. At the moment, there is no available local version to work with.
Ensure all dependencies are installed within the orchestrate director by running
$ npm install
To run tests:
$ npm test
var db = require'orchestrate'token
Note, the client defaults to the Amazon US East Datacenter. If you've created your Application in a different datacenter, you'll need to configure the client with that Datacenter's Api URL. For example, for Amazon EU West:
var oio = require'orchestrate';var db = oiotoken 'api.aws-eu-west-1.orchestrate.io';
Please see the Orchestrate MDC Docs for more information on Multi-Datacenter.
Orchestrate comes with support for GET/PUT/DEL for key-value queries, as well as search, graph, and events. Documentation can be found here.
All queries are promise based. Just as a typical function would return a callback containing an error field followed by a result, orchestrate.js returns
To get a value:
To set a value:
dbput'collection' 'key'"name": "Steve Kaliski""hometown": "New York, NY""twitter": "@stevekaliski"thenfail
Or, setting a value and allowing the server to generate a key:
dbpost'collection'"name": "Steve Kaliski""hometown": "New York, NY""twitter": "@stevekaliski"thenfail
To merge (or update) new values into an existing key, construct a partial document with the desired changes and then use
dbmerge'collection' 'key'"name": "Stephen Kaliski"thenfail
Alternatively, you can apply a series of controlled changes to a key by constructing a patch:
dbnewPatchBuilder'collection' 'key'add'age' 25replace'hometown' 'NY'applythen// All changes were applied successfullyfail// No changes were applied
Orchestrate also supports conditional put statements that determines whether or not the store operation will occur.
db.put takes a fourth argument
match which is either the
ref value or
false. If a ref value is provided an
update will occur if there is a valid match, if false is provided, a
create will occur if there is no match.
dbput'collection' 'key' data 'cbb48f9464612f20' // updatedbput'collection' 'key' data false // create
To remove a value:
dbremove'collection' 'key' truethenfail
The last parameter is optional. If supplied the ref history will be removed as well.
To get a value at a specific ref:
dbget'collection' 'key' 'ref'thenfail
To list refs for a particular key in a collection:
dblist_refs'collection' 'key'thenvar items = resultbodyresults;fail
There is no need to explicitly create a collection. Collections are implicitly created when putting a key/value object.
To list items in a collection, you can use collection listings.
dblist'collection'thenvar items = resultbodyresults;fail
Collection listings allow you to page through your collection in key order (sorted lexicographically so be aware of that if you have numeric keys). It is also useful to list parts of your collection starting from a particular key. For example, to list the first 10 keys starting from key 'c':
dblist'address-book' limit:10 startKey:'c'thenfail
Note: if there is no item with key 'c', the first page will simply have the first 10 results that sort after 'c'.
Collection listings support pagination. If there are more items that follow the page that was retrieved, the result will have a 'links.next' that you can use to fetch the next page.
dblist'address-book' limit:10 startKey:'c'then// Got First Pageif page1links && page1linksnextpage1linksnextgetthen// Got Second Pagefail
To run a quick search, you can simply provide the collection you'd like to search within, your query, and optionally, any query parameters like a
sort argument. Currently, Orchestrate supports the Lucene query syntax.
dbsearch'collection' 'query'sort: 'value.sort:desc'limit: 5offset: 2thenfail
The more verbose
SearchBuilder is also available for a more stately approach:
dbnewSearchBuildercollection'users'limit100offset10sort'name' 'desc'sort'age' 'asc'aggregate'stats' 'value.name'stats'username'// these two range aggregates are identical// but they use different interfacesrange'coolness' '*~1:1~2:2~*'range'radness'return builderbefore1between1 2after2;// these two distance aggregates are identical// but they use different interfacesdistance'location' '*~1:1~2:2~*'distance'hometown'return builderbefore1between1 2after2;time_series'path' 'day'query'steve'
Searching Events is also supported. Event Searching is done by adding a '@path.kind' predicate to the query to indicate what should be searched. By default, Orchestrate will only Search for 'item's in the collection.
dbnewSearchBuildercollectionfirstname.lastname@example.org:event AND steve'
There is a builder method to set the 'kind' for you:
This query will find all events in the users collection that have a field containing 'steve'. You can further limit what event types are searched by adding another @path metadata predicate:
dbnewSearchBuildercollectionemail@example.com:activities AND steve'
This further restricts the search to event type 'activities'.
You can also Search both items and events.
The result items will have a mix of matching items and events. Each result has a 'path' element, and the 'path.kind' element can be used to determine what the result kind is. For example:
For more information about Orchestrate search, read the docs.
An awesome feature Orchestrate includes is the ability to generate graphs between collections. For example, consider the collections
movies. Some user Steve will
like a variety of movies. We can generate this relationship:
dbnewGraphBuildercreatefrom'users' 'Steve'related'likes'to'movies' 'Superbad'
We can then look up all the different items Steve likes:
We can even take this another step further:
dbnewGraphReadergetfrom'users' 'Steve'related'friends' 'likes'
This will return all of the things that friends of Steve have liked. This assumes a friend relation has previously been defined between Steve and another user.
Orchestrate supports offsets and limits for graph relationships as well. To set those values:
dbnewGraphReadergetlimit1offset1from'users' 'Steve'related'friends' 'likes'
If we want to delete a graph relationship:
dbnewGraphBuilderremovefrom'users' 'Steve'related'likes'to'movies' 'Superbad'
Events are time-ordered objects that exist with the context of a Key-Value object. Consider comments on a post or messages in a thread.
Creating an event:
dbnewEventBuilderfrom'users' 'Steve'type'update'data"text": "Hello!"create
Creating an event at a specified time:
dbnewEventBuilderfrom'users' 'Steve'type'update'.time1384534722568data"text": "Hello!"create
Getting a specific event:
Updating an event:
dbnewEventBuilderfrom'users' 'Steve'type'update'.time1369832019085ordinal9data"text": "Orchestrate is awesome!"update
Updating an event, conditionally:
dbnewEventBuilderfrom'users' 'Steve'type'update'.time1369832019085ordinal9data"text": "Orchestrate is awesome!"ref'ae3dfa4325abe21e'update
Deleting an event:
If you want to make sure your key is valid, you can simply "ping" Orchestrate.
dbpingthen// you key is VALIDfail// your key is INVALID