Useful ArangoSH Tips and Tricks | ArangoDB 2012

arangosh, The ArangoDB shell, provides some options that may simplify an ArangoDB user’s life. Some of these options have been added in version 1.1.2, and some options have been around for a while but are probably still less known. It’s time to showcase them.

Pretty printing results

arangosh prints query results in a compact format by default. This format provides a lot of detail and reduces the amount of (vertical) scrolling. However, it is not very legible:

arangosh> db._routing.all().toArray();
[{ _id : "_routing/6790520", _rev : 6790520, _key : "6790520", url : "/", action : { do : "org/arangodb/actions/redirectRequest", options : { permanently : true, destination : "/_admin/html/index.html" } } }]

arangosh allows using a more readable, pretty-printed result format by executing the command

start_pretty_print();

The same query’s result will look as follows now:

arangosh> db._routing.all().toArray();
[
  { 
    _id : "_routing/6790520", 
    _rev : 6790520, 
    _key : "6790520", 
    url : "/", 
    action : { 
      do : "org/arangodb/actions/redirectRequest", 
      options : { 
        permanently : true, 
        destination : "/_admin/html/index.html"
       }
     }
   }
]

This takes more space, but may still be easier to digest. The choice is yours.

If you have had enough of this format, you can turn it off again by executing

stop_pretty_print();

Executing Javascript files

Starting with ArangoDB version 1.1.2, arangosh allows to be run in non-interactive mode. It can then be used to execute arbitrary Javascript files, e.g. for batch processing.

It can be invoked as follows:

arangosh --javascript.execute --javascript.execute ...

If execution of these files produces any output, the output is written to stdout (or stderr in case of errors). If an exception is thrown during execution, the execution is aborted and arangosh will return with a non-null exit code.
If execution of all files succeeds, arangosh will exit with a return code of 0.

Syntax checking Javascript files

Instead of executing the files, it is possible to just syntax check them. Syntax checking means running the file through V8’s parser. If the file can be parsed, it may still contain errors and not run as intended, but you can be sure that it is at least syntactically valid Javascript.

Syntax checking can be done as follows:

arangosh --javascript.check  --javascript.check  ...

If any errors occur, the error is printed on stderr, and arangosh will exit with a non-null exit code. If all files can be parsed without trouble, the return code will be 0.

Please note that there are subtle differences between different Javascript implementations. For example, the V8 implementation allows the usage of trailing commas and Javascript array and object definitions, whereas some other engines (notably the ones used in Internet Explorer) choke on that and consider that to be parse errors.

Logging the session to a file

Sometimes it is helpful to keep track of what has done done in a client session. To make tracking as easy as possible, arangosh allows logging the entire session with all executed commands and all results to an audit log file.
The option –audit-log allows specifying the file name on arangosh startup, e.g.

arangosh --audit-log session.log

Please note that an existing audit log file will be truncated at start, so the log will only contain data from the last session.
Logging can be combined with the Javascript execution mentioned above, so you can execute Javascript code and log the result to an audit log file, too.

Using a pager to process results

arangosh allows using a pager to process the results of each command executed. Using a pager is nice for checking big result sets that span multiple “pages”. It is hard to inspect those from the command without any tools. Paging comes in handy because any program can be run to process the result. A good candidate for this the less command that can be found on almost Unix/Linux distribution. less is also arangosh’s default pager if paging is enabled, but paging is turned off by default.

To turn paging on, arangosh can be started with the option –use-pager true. This will invoke the pager to process results. Paging can also be turned on later during an arangosh session by executing the command

start_pager();

arangosh’s default pager is less, and it is invoked with the parameters -X -R -F -L. The -F parameter makes less quit immediately if the complete output will fit on a single screen. The normal terminal window will do fine in this case, and using the pager would be just unnecessary. This is also the reason why you won’t see less being used for small results even if you have turned on paging.

You can use a different pager (or less with different parameters) by modifying arangosh’s –pager parameter at startup. Here are some geeky example pagers that produce best results when used together with pretty printing:

# reverses lines in multi-line result sets
arangosh --pager tac 

# remove empty lines from result sets (needs Perl-compatible grep)
arangosh --pager 'grep -v -P "^\s*[\[\]\{\}]\s*$"'

# figlet!
arangosh --pager figlet # figlet!

If you have had enough, turn off paging dynamically by executing

stop_pager();

Getting rid of the password prompt

The ArangoDB server allows using authentication to restrict access to the database to allowed users only.
However, if authentication is turned off for the server, arangosh still prompts for the user password at startup. This may be unintuitive at first, but an arangosh client may be used to connect to different ArangoDB servers, and one of them could still be using authentication. So there must still be a way to provide username and password.

If you do not plan to use authentication and are annoyed by the password prompt of arangosh, there’s now the following option to turn it off for a session:

arangosh --server.disable-authentication true

If you don’t want to retype that on every invocation of arangosh, you can put the line server.disable-authentication=true into into the server section of your arangosh.conf config file as follows:

[server]
disable-authentication=true