ArangoDB Shell Introduction

The ArangoDB shell (arangosh) is a command-line tool that can be used for administration of ArangoDB, including running ad-hoc queries.

The arangosh binary is shipped with ArangoDB. It offers a JavaScript shell environment providing access to the ArangoDB server. Arangosh can be invoked like this:

unix> arangosh

By default arangosh will try to connect to an ArangoDB server running on server localhost on port 8529. It will use the username root and an empty password by default. Additionally it will connect to the default database (_system). All these defaults can be changed using the following command-line options:

--server.database : name of the database to connect to
--server.endpoint : endpoint to connect to
--server.username : database username
--server.password : password to use when connecting
--server.authentication : whether or not to use authentication

For example, to connect to an ArangoDB server on IP 192.168.173.13 on port 8530 with the user foo and using the database test, use:

unix> arangosh  \
  --server.endpoint tcp://192.168.173.13:8530  \
  --server.username foo  \
  --server.database test  \
  --server.authentication true

arangosh will then display a password prompt and try to connect to the server after the password was entered.

To change the current database after the connection has been made, you can use the db._useDatabase() command in arangosh:

arangosh> db._createDatabase("myapp");
true
arangosh> db._useDatabase("myapp");
true
arangosh> db._useDatabase("_system");
true
arangosh> db._dropDatabase("myapp");
true

To get a list of available commands, arangosh provides a help() function. Calling it will display helpful information.

arangosh also provides auto-completion. Additional information on available commands and methods is thus provided by typing the first few letters of a variable and then pressing the tab key. It is recommend to try this with entering db. (without pressing return) and then pressing tab.

By the way, arangosh provides the db object by default, and this object can be used for switching to a different database and managing collections inside the current database.

For a list of available methods for the db object, type

arangosh> db._help(); 
--------------------------- ArangoDatabase (db) help ---------------------------
Administration Functions:                                                 
  _help()                               this help                         
  _flushCache()                         flush and refill collection cache 

Collection Functions:                                                     
  _collections()                        list all collections              
  _collection(<name>)                   get collection by identifier/name 
  _create(<name>, <properties>)         creates a new collection          
  _createEdgeCollection(<name>)         creates a new edge collection     
  _drop(<name>)                         delete a collection               

Document Functions:                                                       
  _document(<id>)                       get document by handle (_id)      
  _replace(<id>, <data>, <overwrite>)   overwrite document                
  _update(<id>, <data>, <overwrite>,    partially update document         
          <keepNull>)                                                     
  _remove(<id>)                         delete document                   
  _exists(<id>)                         checks whether a document exists  
  _truncate()                           delete all documents              

Database Management Functions:                                            
  _createDatabase(<name>)               creates a new database            
  _dropDatabase(<name>)                 drops an existing database        
  _useDatabase(<name>)                  switches into an existing database
  _drop(<name>)                         delete a collection               
  _name()                               name of the current database      

Query / Transaction Functions:                                            
  _executeTransaction(<transaction>)    execute transaction               
  _query(<query>)                       execute AQL query                 
  _createStatement(<data>)              create and return AQL query       

View Functions:                                                           
  _views()                                  list all views                
  _view(<name>)                             get view by name              
  _createView(<name>, <type>, <properties>) creates a new view

arangosh> db._help();

show execution results

you can paste multiple lines into arangosh, given the first line ends with an opening brace:

arangosh> for (var i = 0; i < 10; i ++) {
........>         require("@arangodb").print("Hello world " + i + "!\n");
........> }
Hello world 0!

Hello world 1!

Hello world 2!

Hello world 3!

Hello world 4!

Hello world 5!

Hello world 6!

Hello world 7!

Hello world 8!

Hello world 9!

arangosh> for (var i = 0; i < 10; i ++) {
........>         require("@arangodb").print("Hello world " + i + "!\n");
........> }

show execution results

To load your own JavaScript code into the current JavaScript interpreter context, use the load command:

require("internal").load("/tmp/test.js")     // <- Linux / MacOS
require("internal").load("c:\\tmp\\test.js") // <- Windows

Exiting arangosh can be done using the key combination <CTRL> + D or by typing quit<CR>

Escaping

In AQL, escaping is done traditionally with the backslash character: \. As seen above, this leads to double backslashes when specifying Windows paths. Arangosh requires another level of escaping, also with the backslash character. It adds up to four backslashes that need to be written in Arangosh for a single literal backslash (c:\tmp\test.js):

db._query('RETURN "c:\\\\tmp\\\\test.js"')

You can use bind variables to mitigate this:

var somepath = "c:\\tmp\\test.js"
db._query(aql`RETURN ${somepath}`)