From Clojure to ArangoDB – Clarango Version 0.6 released

Clarango is the bridge between Clojure and the multi-model database ArangoDB. I just released version 0.6 of this driver and here is an overview of the new functionalities.

HTTP API compatibility updates

Some necessary changes had to be made to make Clarango work with the ever changing HTTP API of the latest version of ArangoDB (2.3).

The admin namespace had to be deleted completely because ArangoDB 2.3 no longer supports the former admin interface. Instead a misc namespace was added to hold methods of general functionality in the future. Currently it only has one method, version, that retrieves ArangoDB version info.

ArangoDB’s HTTP API also has a new graph interface that is way more flexible than the old one. I started the migration, but du to lack of time there is still a lot to be done here to complete the migration.

Helper Methods to test if a Database, Graph or Collection exists

In the database namespace you now will now find find the following methods to do a quick check if a database, collection or graph already exists: database-exists?, collection-exists? and graph-exists?. They work just like you would expect, taking a name as argument and returning true or false as a result.

Getting a whole collection at once with delayed documents

Wouldn’t it be cool if you could just get a whole collection with all its content at once? That’s what I thought. But since collections can be arbitrarily large and every Clarango method call should only result in one HTTP request, I thought of this:

You can now call the method get-delayed-collection in the collection namespace and it will return a map associating the keys of every document in the collection with the document itself, represented as a delay.

That means you can retrieve all document keys like so:

(keys (collection/get-delayed-collection :my-collection :my-db))

For getting the content of all documents one after another you could do something like:

(let [delayed-collection (collection/get-delayed-collection :my-collection :my-db)]
      (doseq [k (keys delayed-collection)]
        (pprint @(get delayed-collection k))))

This is an experimental feature, let me know what you think about it!

More Nesting possible

It’s now possible to do more method nesting in order to shorten expressions. Instead of doing everything in a strictly sequential style, you can create resources e.g. like this:

(clacore/with-db (database/create :my-db [])
  (document/create-with-key {:description "nice stuff"} :my-doc 
    (collection/create :my-collection)))
(graph/create :test-graph 
  (collection/create :people {"type" 2})
  (collection/create :friendships {"type" 3}))

So what would be the shortest possible way to create a document? I can think of several, but one would for example be:

  {:connection-url "http://localhost:8529/"
   :db-name (database/create "my-db" [])
   :collection-name (collection/create "my-collection")}
  (document/create-with-key {:description "nice stuff"} :my-doc))

This is as much an experimental feature as the last one, so let me know if you find this useful. I’m sure it’s convenient in some cases, but it also makes the method signatures be defined less precisely. To make this work, I’m storing the collection and database names in the metadata of the return values of their respective create methods. That means the Clarango methods now accept also maps as arguments where before they only accepted keywords or strings. This may be confusing at some points and can also make the debugging harder, since Clarango can’t just throw an error anymore if you pass a map instead of a resource name.

To learn more about Clarango, check out the Github repository. You will find more examples there and also links to further documentation.

Btw: There is still a lot to be done to make Clarango a complete driver and I can’t do it all on my own since the ArangoDB HTTP API is changing quite a lot. If you wish to contribute to Clarango, send me a message or just pull request!