arangosh Details

The behavior and configuration of the ArangoDB Shell

Interaction

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

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

Show output

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!

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

require("internal").load("/tmp/test.js")

You can exit arangosh using the key combination Ctrl + D or by typing quit and hitting Return .

Shell Output

The ArangoDB shell prints the output of the last evaluated expression by default:

42 * 23

Show output

In order to prevent printing the result of the last evaluated expression, the expression result can be captured in a variable, e.g.

var calculationResult = 42 * 23

Show output

Empty Output

There is also the print function to explicitly print out values in the ArangoDB shell:

print({ a: "123", b: [1,2,3], c: "test" });

Show output

{ 
  "a" : "123", 
  "b" : [ 
    1, 
    2, 
    3 
  ], 
  "c" : "test" 
}

By default, the ArangoDB shell uses a pretty printer when JSON documents are printed. This ensures documents are printed in a human-readable way:

db._create("five")
for (var i = 0; i < 5; i++) {
  db.five.save({value:i});
}
db.five.toArray()

Show output

[ArangoCollection 68469, "five" (type document, status loaded)]

{ 
  "_id" : "five/68483", 
  "_key" : "68483", 
  "_rev" : "_mLPDK6W---" 
}

[ 
  { 
    "_key" : "68475", 
    "_id" : "five/68475", 
    "_rev" : "_mLPDK6O---", 
    "value" : 0 
  }, 
  { 
    "_key" : "68477", 
    "_id" : "five/68477", 
    "_rev" : "_mLPDK6S---", 
    "value" : 1 
  }, 
  { 
    "_key" : "68479", 
    "_id" : "five/68479", 
    "_rev" : "_mLPDK6S--_", 
    "value" : 2 
  }, 
  { 
    "_key" : "68481", 
    "_id" : "five/68481", 
    "_rev" : "_mLPDK6S--A", 
    "value" : 3 
  }, 
  { 
    "_key" : "68483", 
    "_id" : "five/68483", 
    "_rev" : "_mLPDK6W---", 
    "value" : 4 
  } 
]

While the pretty-printer produces nice looking results, it needs a lot of screen space for each document. Sometimes a more dense output might be better. In this case, the pretty printer can be turned off using the command stop_pretty_print().

To turn on pretty printing again, use the start_pretty_print() command.

Escaping

In AQL, escaping is done traditionally with the backslash character: \. For literal backslashes, you need to double backslashes to \\. 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}`)

Database Wrappers

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

db._help();

Show output

--------------------------- 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>,           creates a new view                
              <properties>)                                               
  _dropView(<name>)                     delete a view                     
                                                                          
License Functions:                                                        
  _getLicense()                         get license information           
  _setLicense(<license-string>)         set license string

The arangosh implementation of the db object wraps HTTP requests to ArangoDB’s HTTP API. The arangod implementation provides JavaScript wrappers around ArangoDB’s native C++ implementation and is used by Foxx and other server-side JavaScript contexts.

It means that the following code performs around 100k HTTP requests when using the arangosh implementation, whereas the arangod implementation writes to the database system directly and therefore requires less time and the CPU usage is lower. The code basically produces the same results with both:

for (var i = 0; i < 100000; i++) {
  db.test.save({ name: { first: "Jan" }, count: i});
}

You should avoid making excessive calls like this when using arangosh and instead save batches of documents in fewer HTTP requests:

var batch = [];
for (var i = 0; i < 100000; i++) {
  batch.push({ name: { first: "Jan" }, count: i});
  if (batch.length >= 1000) {
    db.test.save(batch);
    batch = [];
  }
}
if (batch.length > 0) {
  db.test.save(batch);
}

Using arangosh via Unix shebang mechanisms

In Unix operating systems, you can start scripts by specifying the interpreter in the first line of the script. This is commonly called shebang or hash bang. You can also do that with arangosh, i.e. create ~/test.js:

#!/usr/bin/arangosh --javascript.execute 
require("internal").print("hello world")
db._query("FOR x IN test RETURN x").toArray()

Note that the first line has to end with a blank in order to make it work. Mark it executable to the OS:

> chmod a+x ~/test.js

and finally try it out:

> ~/test.js

Shell Configuration

arangosh looks for a user-defined startup script named .arangosh.rc in the user’s home directory on startup. The home directory is likely at /home/<username>/ on Unix/Linux.

If the file .arangosh.rc is present in the home directory, arangosh executes the contents of this file inside the global scope.

You can use this to define your own extra variables and functions that you need often. For example, you could put the following into the .arangosh.rc file in your home directory:

// "var" keyword avoided intentionally...
// otherwise "timed" would not survive the scope of this script
global.timed = function (cb) {
  console.time("callback");
  cb();
  console.timeEnd("callback");
};

This makes a function named timed available in arangosh in the global scope.

You can now start arangosh and invoke the function like this:

timed(function () { 
  for (var i = 0; i < 1000; ++i) {
    db.test.save({ value: i }); 
  }
});

Please keep in mind that, if present, the .arangosh.rc file needs to contain valid JavaScript code. If you want any variables in the global scope to survive you need to omit the var keyword for them. Otherwise, the variables are only visible inside the script itself, but not outside.