ArangoDB client
A client for the ArangoDB nosql database for nodejs and browsers.
NOTE: This repo is now officially maintained by the developers of ArangoDB @ https://github.com/triAGENS/ArangoDB-JavaScript.
Latest changes
The Query API returns result from Aql cursors unfiltered. Before you only got the result Array missing some 'extra' information.
db.query
.for('u').in('_users').return('u')
.exec()
.then(function(ret){
console.log("ret.result", ret.result); // array with results
console.log("ret.extra", ret.extra); // extra information
});
A callback
method has been added that can be used instead of a callback passed as argument.
x = db.database.create("newdb")
.callback(function(err,ret){
... same as above ...
});
// x => Promise
You may however still pass a callback to the API methods in which case promises are bypassed so you achieve a little less overhead in your db.api calls.
var x = db.collection.list(function(err,ret){
console.log("err(%s):",err,ret);
});
// x => undefined
Introduction
You can use arango-client either as node.js server module or from a web client. Since arango-client is written as a commonJS module you can just require it in your nodejs project or using the generated build file which you can include into your client side app.
Install
From source: `git clone git://github.com/triAGENS/ArangoDB-JavaScript`
web component: `component install triAGENS/ArangoDB-JavaScript`
nodejs module: `npm install arangojs`
Building
make build
Creates a single build.js component in the ./build
directory.
A standalone is built separately and named arango.js.
Documentation
make docs
Generates the documentation in the documentation folder. An installation of yuidocjs is required (npm i -g yuidocjs). You can visit the latest documentation on http://www.arangodb.org/manuals-javascript/master/.
Test
make test
Runs the test suite sequentially under nodejs and karma (supporting Firefox and Chrome). Feel free to chip in by writing tests if you want a more stable package.
Quick start
To use the client you require it at a commonJS module.
var arango = ;
Then you initialize a connection which returns a db handle.
var db = arango; dbcollection;
In a browser
For usage in a web browser you can either use the standalone version arango.js or the build.js component. A minimal html page using the arangodb client from a web app can look like this.
ArangoDB in your browser
The standalone version yields a global arango
object.
ArangoDB in your browser <!-- Note: Exports global arango -->
API
The following API:s are (more or less) supported, check out the ArangoDB documentation.
- transaction
- collection
- database
- document
- action
- cursor
- simple
- index
- admin
- aqlfunction
- batch
- query
- graph
- batch
- edge
- user
The API methods return a promise. If you like nodejs callbacks you can use the callback utility provided by the micropromise framework.
Example using a promise:
dbdocument;
Example when using a callback:
dbdocument ;
Usage
Connect()
Factory for arango connection.
Sets up a connection to localhost http://127.0.0.1:8529
by default.
db = arango
Connection string
db = arango;
Connection with http auth
db = arango;
Connection object
db = arango.Connection({_name:"database",_collection:"collection",_server:{hostname:"test.host"}});
Connecting to a unix socket (nodejs only)
db = arango.Connection({_server:{socketPath:"/var/tmp/arango.sock"}});
String and object
db = arango;
String and api plugin
db = arango;
use()
With use() you can switch connection settings
var test = db
Use another database
var test_mydb = test;
Change to another database & collection
var test_mydb2_mail = test_mydb;
Change collection
var test_mydb2__users = test_mydb2_mail;
Creating collections & documents
Initialize a Connection
var db = arango;
Create a new database
dbdatabase
Use mydb database
var mydb = db;
Create a 'test' collection
mydbcollection;
List all collections in mydb, note the use of done()
mydbcollection;
Create a collection with options
mydbcollection;
Delete collection (using callback)
mydbcollection;
Create a 'test2' collection (using callback)
mydbcollection;
Create a new document in 'test' collection
mydbdocument ;
Get a list of all documents in 'test' collection
mydbdocument ;
Create a new document and create a new collection by passing in options
mydbdocument ;
Create document and wait for disk sync
mydbdocument ;
Create another document in the collection
dbdocument ;
Joining
dbadminversion ;
Calling API methods directly
You may also request any arangodb API method by using db[METHOD]()
.
This is particulary usefull when you create your own REST API in ArangoDB.
db;
Methods supported are: get(), put(), post(), delete(), options(), head(), patch().
Queries
/* using a query string */dbquery; .../* query string with a bindVar */dbquery ;
Note: ArangoDB expects @@ in front of collection names when using a bindvar. The bindvar attribute in this case needs to be prefixed with a single @. In all other cases the bindvar atttribute can be provided without any prefix and the variable in the query string is denoted with a single @ .
Query builder
Result batch size can be set using the query.count(<number>)
method.
In case of partial results the next batch can be retrieved with res.next().
/* using the query builder and a bindVar */dbquery ; /* test run a query */dbquery ; /* detailed query explanation */dbquery ; /* nested queries embedded as functions(){} */query = dbquery ; /* limit the result set to 1 item each iteration */query ;
Actions
ArangoDB supports user defined actions that can be used for implementing business logic or creating complex queries serverside.
To invoke an action you first need to define it.
/* define an action */dbaction; /* submit the action */var data = test:"data"dbaction; /* submit using a callback */dbaction; /* Define an action that injects code serverside.*//* the last argument reloads the routes, or use *//* db.admin.routesReload() to reload the routes. */ dbaction; dbaction;
Transactions
Transactions are sent to arangodb using transaction.submit(collections,action,params,options,callback)
.
collections
defines read/write access to collections used within the transaction.
action
is a serverside handler for the transaction.
options
can be used for adding parameters etc
dbcollection;
Batch jobs
The BatchAPI allows you to bundle database requests.
Use db.batch.start()
to initialize a batch job and db.batch.exec()
to execute jobs.
// start a batch dbbatchstart; // collect admin information dbadminversion; dbadmin; dbadmin; dbadmin; // execute batch dbbatch;
Individual job results can be fetched as usual.
// start a batch dbbatchstart; // collect admin information dbadminversion; dbadmin; // using callback dbadmin; dbadmin; // execute batch dbbatch;
api
An API can be implemented like this.
{ return { return db; } { return db; } { return db; } { return db; } { return db; } { return db; } { return dboptions'/path' /*,headers*/; } ;} /* Attach the API into 'stub' namespace */exportsstub = StubAPI;
To attach your API into the db instances you use the Arango.api
class method.
/* attach to db instances */
Arango.api(require('myAPI'));
var db = new Arrango.Connection;
/* call API method */
db.stub.get();
License
Copyright (c) 2012 Kaerus (kaerus.com), Anders Elo <anders @ kaerus com>.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.