Arangosh Details

Interaction

You can paste multiple lines into Arangosh, given the first line ends with anopening brace:

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

Show execution results

Hide execution results

  1. Hello world 0!
  2.  
  3. Hello world 1!
  4.  
  5. Hello world 2!
  6.  
  7. Hello world 3!
  8.  
  9. Hello world 4!
  10.  
  11. Hello world 5!
  12.  
  13. Hello world 6!
  14.  
  15. Hello world 7!
  16.  
  17. Hello world 8!
  18.  
  19. Hello world 9!

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

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

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

Shell Output

The ArangoDB shell will print the output of the last evaluated expressionby default:

  1. arangosh> 42 * 23

Show execution results

Hide execution results

  1. 966

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

  1. arangosh> var calculationResult = 42 * 23

Show execution results

Hide execution results

  1.  

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

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

Show execution results

Hide execution results

  1. { 
  2.   "a" : "123", 
  3.   "b" : [ 
  4.     1, 
  5.     2, 
  6.     3 
  7.   ], 
  8.   "c" : "test" 
  9. }

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

  1. arangosh> db._create("five")
  2. arangosh> for (i = 0; i < 5; i++) db.five.save({value:i})
  3. arangosh> db.five.toArray()

Show execution results

Hide execution results

  1. [ArangoCollection 88683, "five" (type document, status loaded)]
  2. [ 
  3.   { 
  4.     "_key" : "88688", 
  5.     "_id" : "five/88688", 
  6.     "_rev" : "_Z2KDUXO---", 
  7.     "value" : 0 
  8.   }, 
  9.   { 
  10.     "_key" : "88690", 
  11.     "_id" : "five/88690", 
  12.     "_rev" : "_Z2KDUXO--A", 
  13.     "value" : 1 
  14.   }, 
  15.   { 
  16.     "_key" : "88692", 
  17.     "_id" : "five/88692", 
  18.     "_rev" : "_Z2KDUXS---", 
  19.     "value" : 2 
  20.   }, 
  21.   { 
  22.     "_key" : "88694", 
  23.     "_id" : "five/88694", 
  24.     "_rev" : "_Z2KDUXS--A", 
  25.     "value" : 3 
  26.   }, 
  27.   { 
  28.     "_key" : "88696", 
  29.     "_id" : "five/88696", 
  30.     "_rev" : "_Z2KDUXS--C", 
  31.     "value" : 4 
  32.   } 
  33. ]

While the pretty-printer produces nice looking results, it will need a lot ofscreen space for each document. Sometimes a more dense output might be better.In this case, the pretty printer can be turned off using the commandstop_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: \.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 singleliteral backslash (c:\tmp\test.js):

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

You can use bind variables tomitigate this:

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

Database Wrappers

Arangosh provides the db object by default, and this object canbe used for switching to a different database and managing collections inside thecurrent database.

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

  1. arangosh> db._help();

Show execution results

Hide execution results

  1. --------------------------- ArangoDatabase (db) help ---------------------------
  2. Administration Functions:                                                 
  3.   _help()                               this help                         
  4.   _flushCache()                         flush and refill collection cache 
  5.  
  6. Collection Functions:                                                     
  7.   _collections()                        list all collections              
  8.   _collection(<name>)                   get collection by identifier/name 
  9.   _create(<name>, <properties>)         creates a new collection          
  10.   _createEdgeCollection(<name>)         creates a new edge collection     
  11.   _drop(<name>)                         delete a collection               
  12.  
  13. Document Functions:                                                       
  14.   _document(<id>)                       get document by handle (_id)      
  15.   _replace(<id>, <data>, <overwrite>)   overwrite document                
  16.   _update(<id>, <data>, <overwrite>,    partially update document         
  17.           <keepNull>)                                                     
  18.   _remove(<id>)                         delete document                   
  19.   _exists(<id>)                         checks whether a document exists  
  20.   _truncate()                           delete all documents              
  21.  
  22. Database Management Functions:                                            
  23.   _createDatabase(<name>)               creates a new database            
  24.   _dropDatabase(<name>)                 drops an existing database        
  25.   _useDatabase(<name>)                  switches into an existing database
  26.   _drop(<name>)                         delete a collection               
  27.   _name()                               name of the current database      
  28.  
  29. Query / Transaction Functions:                                            
  30.   _executeTransaction(<transaction>)    execute transaction               
  31.   _query(<query>)                       execute AQL query                 
  32.   _createStatement(<data>)              create and return AQL query       
  33.  
  34. View Functions:                                                           
  35.   _views()                              list all views                    
  36.   _view(<name>)                         get view by name                  
  37.   _createView(<name>, <type>,           creates a new view                
  38.               <properties>)                                               
  39.   _dropView(<name>)                     delete a view

The db object is available in arangosh_as well as on _arangod i.e. if you’re using Foxx. While itsinterface is persistent between the arangosh and the arangod implementations,its underpinning is not. The arangod implementation are JavaScript wrappersaround ArangoDB’s native C++ implementation, whereas the arangosh implementationwraps HTTP accesses to ArangoDB’s RESTfull API.

So while this code may produce similar results when executed in arangosh andarangod, the CPU usage and time required will be really different since thearangosh version will be doing around 100k HTTP requests, and thearangod version will directly write to the database:

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

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:

  1. #!/usr/bin/arangosh --javascript.execute 
  2. require("internal").print("hello world")
  3. 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:

  1. #> chmod a+x ~/test.js

and finaly try it out:

  1. #> ~/test.js

Shell Configuration

arangosh will look for a user-defined startup script named .arangosh.rc in theuser’s home directory on startup. The home directory will likely be /home/<username>/on Unix/Linux, and is determined on Windows by peeking into the environment variables%HOMEDRIVE% and %HOMEPATH%.

If the file .arangosh.rc is present in the home directory, arangosh will executethe 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 homedirectory:

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

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

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

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

Please keep in mind that, if present, the .arangosh.rc file needs to contain validJavaScript code. If you want any variables in the global scope to survive you need toomit the var keyword for them. Otherwise the variables will only be visible insidethe script itself, but not outside.