ArangoDB Manual

We recently started a new open source project - a universal nosql database called AvocadoDB which became ArangoDB in May 2012.

Key features include:

Schema-free schemata let you combine the space efficiency of MySQL with the performance power of NoSQL
Use ArangoDB as an application server and fuse your application and database together for maximal throughput
JavaScript for all: no language zoo, you can use one language from your browser to your back-end
ArangoDB is multi-threaded - exploit the power of all your cores
Flexible data modeling: model your data as combination of key-value pairs, documents or graphs - perfect for social relations
Free index choice: use the correct index for your problem, be it a skip list or a n-gram search
Configurable durability: let the application decide if it needs more durability or more performance
No-nonsense storage: ArangoDB uses all of the power of modern storage hardware, like SSD and large caches
It is open source (Apache Licence 2.0)

For more in-depth information

read more on the design goals of ArangoDB
watch the video - Martin Schoenert, architect of ArangoDB, gives an introduction of what the ArangoDB project is about.
or give it a try.

The ArangoDB database groups documents into collections. Collections and documents can be accessed using queries. For simple queries involving just one collection and one search criteria, you can use a simple interface from within JavaScript code or other languages supported by an API. This interface allows you to select documents from one collection based on just one search criteria. For more complex queries, you can use the Arango Query Language (AQL), which is an evolution of SQL resp. UNQL for the NoSQL world. AQL allows you to use more then one collection, similar to joins from SQL, while still retaining the document and list structures like UNQL.

The ArangoDB database packages comes with various programs:

arangod: The ArangoDB database daemon. This server program is intended to run as daemon process and to server the various clients connection to the server via TCP / HTTP. See Starting the ArangoDB Server.
arangosh: The ArangoDB shell. A client that implements a read-eval-print loop (REPL) and provides functions to access and administrate the ArangoDB server. See Starting the ArangoDB Shell.
arangoimp: A bulk importer for the ArangoDB server. See ArangoDB Importer Manual (1.0.0)

About ArangoDB

Starting the ArangoDB Server

The ArangoDB database server has two modes of operation: as server, where it will answer to client requests, and an emergency console, in which you can access the database directly. The latter - as the name suggests - should only be used in case of an emergency, for example, a corrupted collection. Using the emergency console allows you to issue all commands normally available in actions and transactions. When starting the server in emergency console mode, the server cannot handle any client requests.

You should never start more than one server using the same database directory, independent from the mode of operation. Normally ArangoDB will prevent you from doing this by placing a lockfile in the database directory and not allowing a second ArangoDB instance to use the same database directory if a lockfile is already present.

The following command starts the ArangoDB database in server mode. You will be able to access the server using HTTP requests on port 8529. See below for a list of frequently used options, see here for a complete list.

> ./arangod /tmp/vocbase
2012-05-13T12:37:08Z [8145] INFO using built-in JavaScript startup files
2012-05-13T12:37:08Z [8145] INFO ArangoDB (version 1.x.y) is ready for business
2012-05-13T12:37:08Z [8145] INFO Have Fun!

After starting the server, point your favorite browser to:

http://localhost:8529/

to access the administration front-end.

To start the server at system boot time, you should use one of the pre-rolled packages that will install the necessary start / stop scripts for ArangoDB. To start and stop the server manually, you can use the start / stop script like this (provided the start / stop script is located in /etc/init.d/arangod, the command actual name and invocation are platform-dependent):

/etc/init.d/arangod start

To stop the server, you can use the command

/etc/init.d/arangod stop

You may require root privileges to execute these commands.

If you compiled ArangoDB from source and did not use any installation package, or you are using non-default locations and/or multiple ArangoDB instances on the same host, you may want to start the server process manually. You can do so by invoking the arangod binary from the command line as shown before. To stop the database server gracefully, you can either pressCTRL-C or by send the SIGINT signal to the server process. On many systems, this can be achieved with the following command:

kill -2 `pidof arangod`

Frequently Used Options

The following command-line options are frequently used. For a full list of options see here.

database-directory

Uses the database-directory as base directory. There is an alternative version available for use in configuration files, see here.

--help

-h

Prints a list of the most common options available and then exits. In order to see all options use --help-all.

--log level

Allows the user to choose the level of information which is logged by the server. The level is specified as a string and can be one of the following values: fatal, error, warning, info, debug, trace. For more information see here.

--server.endpoint endpoint

Specifies an endpoint for HTTP requests by clients. Endpoints have the following pattern:

tcp://ipv4-address:port - TCP/IP endpoint, using IPv4
tcp://[ipv6-address]:port - TCP/IP endpoint, using IPv6
ssl://ipv4-address:port - TCP/IP endpoint, using IPv4, SSL encryption
ssl://[ipv6-address]:port - TCP/IP endpoint, using IPv6, SSL encryption
unix:///path/to/socket - Unix domain socket endpoint

If a TCP/IP endpoint is specified without a port number, then the default port (8529) will be used. If multiple endpoints need to be used, the option can be repeated multiple times.

Examples

> ./arangod --server.endpoint tcp://127.0.0.1:8529 --server.endpoint ssl://127.0.0.1:8530 -server.keyfile server.pem /tmp/vocbase
2012-07-26T07:07:47Z [8161] INFO using SSL protocol version 'TLSv1'
2012-07-26T07:07:48Z [8161] INFO using endpoint 'ssl://127.0.0.1:8530' for http ssl requests
2012-07-26T07:07:48Z [8161] INFO using endpoint 'tcp://127.0.0.1:8529' for http tcp requests
2012-07-26T07:07:49Z [8161] INFO ArangoDB (version 1.1.alpha) is ready for business
2012-07-26T07:07:49Z [8161] INFO Have Fun!

Note that if you are using SSL-encrypted endpoints, you must also supply the path to a server certificate using the --server.keyfile optionn.

--server.disable-authentication value

Setting value to true will turn off authentication on the server side so all clients can execute any action without authorisation and privilege checks.

The default value is false.

--server.keep-alive-timeout

Allows to specify the timeout for HTTP keep-alive connections. The timeout value must be specified in seconds. Idle keep-alive connections will be closed by the server automatically when the timeout is reached. A keep-alive-timeout value 0 will disable the keep alive feature entirely.

--daemon

Runs the server as a daemon (as a background process).

ArangoDB's Front-End

The ArangoDB server has a graphical front-end, which allows you to inspect the current state of the server. You can read the front-end using the following URL:

http://localhost:8529/_admin

Unless you have loaded an application into the ArangoDB server, which remaps the paths, the front-end will also be available under

http://localhost:8529/.

The front-end allows you the browser through the collections and documents. If you need to administrate the database, please use the ArgangoDB shell described in the next section.

Starting the ArangoDB Shell

After the server has been started, you can use the ArangoDB shell (arangosh) to administrate the server. Without any arguments, the ArangoDB shell will try to contact the server on port 8529 on the localhost. For more information see The Arango Shell.

> ./arangosh
                                       _     
  __ _ _ __ __ _ _ __   __ _  ___  ___| |__  
 / _` | '__/ _` | '_ \ / _` |/ _ \/ __| '_ \ 
| (_| | | | (_| | | | | (_| | (_) \__ \ | | |
 \__,_|_|  \__,_|_| |_|\__, |\___/|___/_| |_|
                       |___/                 

Welcome to arangosh 1.x.y. Copyright (c) 2012 triAGENS GmbH.
Using Google V8 3.9.4 JavaScript engine.
Using READLINE 6.1.

Connected to Arango DB 127.0.0.1:8529 Version 1.x.y

------------------------------------- Help -------------------------------------
Predefined objects:                                                 
  arango:                                ArangoConnection           
  db:                                    ArangoDatabase             
Example:                                                            
 > db._collections();                    list all collections       
 > db.<coll_name>.all();                 list all documents         
 > id = db.<coll_name>.save({ ... });    save a document            
 > db.<coll_name>.remove(<_id>);         delete a document          
 > db.<coll_name>.document(<_id>);       get a document             
 > help                                  show help pages            
 > helpQueries                           query help                 
 > exit                                                             
arangosh>

You might need to set additional options (endpoint, username, and password) when connecting:

> ./arangosh --server.endpoint tcp://127.0.0.1:8529 --server.username root

The shell will print its own version number and, if successfully connected to a server, the version number of the ArangoDB server.

Command-Line Options

Use --help to get a list of command-line options:

> ./arangosh --help
STANDARD options:
  --help                                     help message
  --javascript.modules-path <string>         one or more directories separated by cola (default: "bin/../js/client/modules;bin/../js/common/modules")
  --javascript.startup-directory <string>    startup paths containing the JavaScript files; multiple directories can be separated by cola
  --javascript.unit-tests <string>           do not start as shell, run unit tests instead
  --jslint <string>                          do not start as shell, run jslint instead
  --log.level <string>                       log level (default: "info")
  --max-upload-size <uint64>                 maximum size of import chunks (in bytes) (default: 500000)
  --no-auto-complete                         disable auto completion
  --no-colors                                deactivate color support
  --pager <string>                           output pager (default: "less -X -R -F -L")
  --pretty-print                             pretty print values
  --quiet                                    no banner
  --server.connect-timeout <int64>           connect timeout in seconds (default: 3)
  --server.endpoint <string>                 endpoint to connect to, use 'none' to start without a server (default: "tcp://127.0.0.1:8529")
  --server.password <string>                 password to use when connecting (leave empty for prompt)
  --server.request-timeout <int64>           request timeout in seconds (default: 300)
  --server.username <string>                 username to use when connecting (default: "root")
  --use-pager                                use pager

Starting the ArangoDB Emergency Console

The following command starts a emergency console. See below for a list of frequently used options, see here for a complete list.

Note:: Never start the emergency console for a database which also has a server attached to it. In general the ArangoDB shell is what you want.