ArangoDB v3.11 is under development and not released yet.

This documentation is not final and potentially incomplete.

Tutorial: Java in 10 Minutes

This is a short tutorial with the Java Driver and ArangoDB. In less than 10 minutes you can learn how to use ArangoDB Java driver in Maven and Gradle projects.

Check out this repository for the tutorial code.

Project configuration

To use the ArangoDB Java driver you need to import 2 libraries into your project:

In a Maven project, you need to add the following dependencies to pom.xml:

<dependencies>
    <dependency>
        <groupId>com.arangodb</groupId>
        <artifactId>arangodb-java-driver</artifactId>
        <version>...</version>
    </dependency>
    <dependency>
        <groupId>com.arangodb</groupId>
        <artifactId>jackson-dataformat-velocypack</artifactId>
        <version>...</version>
    </dependency>
</dependencies>

In a Gradle project, add the following to build.gradle:

dependencies {
    implementation 'com.arangodb:arangodb-java-driver:...'
    implementation 'com.arangodb:jackson-dataformat-velocypack:...'
}

Connection

First, you need to configure and open a connection to start ArangoDB.

ArangoDB arangoDB = new ArangoDB.Builder()
    .serializer(new ArangoJack())
    .build();

The default connection is to 127.0.0.1:8529.

Creating a database

Then you can create a new database:

ArangoDatabase db = arangoDB.db(DbName.of("mydb"));
System.out.println("Creating database...");
db.create();

Creating a collection

Now you can create your first collection:

ArangoCollection collection = db.collection("firstCollection");
System.out.println("Creating collection...");
collection.create();

Creating a document

After you’ve created the collection, you can add documents to it. Any object can be added as a document to the database and be retrieved from the database as an object.

In this example, the BaseDocument class provided with the driver is used. The attributes of the document are stored in a map as key/value pair:

String key = "myKey";
BaseDocument doc = new BaseDocument(key);
doc.addAttribute("a", "Foo");
doc.addAttribute("b", 42);
System.out.println("Inserting document...");
collection.insertDocument(doc);

Note that:

  • the document key is passed to the BaseDocument constructor
  • addAttribute() puts a new key/value pair into the document
  • each attribute is stored as a single key/value pair in the document root

Read a document

To read the created document:

System.out.println("Reading document...");
BaseDocument readDocument = collection.getDocument(key, BaseDocument.class);
System.out.println("Key: " + readDocument.getKey());
System.out.println("Attribute a: " + readDocument.getAttribute("a"));
System.out.println("Attribute b: " + readDocument.getAttribute("b"));

After executing this program the console output should be:

Key: myKey
Attribute a: Foo
Attribute b: 42

Note that getDocument() reads the stored document data and deserializes it into the given class (BaseDocument).

Read a document as Jackson JsonNode

You can also read a document as a Jackson JsonNode:

System.out.println("Reading document as Jackson JsonNode...");
JsonNode jsonNode = collection.getDocument(key, ObjectNode.class);
System.out.println("Key: " + jsonNode.get("_key").textValue());
System.out.println("Attribute a: " + jsonNode.get("a").textValue());
System.out.println("Attribute b: " + jsonNode.get("b").intValue());

After executing this program the console output should be:

Key: myKey
Attribute a: Foo
Attribute b: 42

Please note that getDocument() returns the stored document as an instance of com.fasterxml.jackson.databind.JsonNode.

Update a document

doc.addAttribute("c", "Bar");
System.out.println("Updating document ...");
collection.updateDocument(key, doc);

Read the document again

To read the document again, run the following:

System.out.println("Reading updated document ...");
BaseDocument updatedDocument = collection.getDocument(key, BaseDocument.class);
System.out.println("Key: " + updatedDocument.getKey());
System.out.println("Attribute a: " + updatedDocument.getAttribute("a"));
System.out.println("Attribute b: " + updatedDocument.getAttribute("b"));
System.out.println("Attribute c: " + updatedDocument.getAttribute("c"));

After executing this program the console output should look like this:

Key: myKey
Attribute a: Foo
Attribute b: 42
Attribute c: Bar

Delete a document

To delete a document, run the following:

System.out.println("Deleting document ...");
collection.deleteDocument(key);

Execute AQL queries

First you need to create some documents with the Homer name in the firstCollection collection:

for (int i = 0; i < 10; i++) {
    BaseDocument value = new BaseDocument(String.valueOf(i));
    value.addAttribute("name", "Homer");
    collection.insertDocument(value);
}

To get all documents with the Homer name in the firstCollection collection and iterate over the result:

String query = "FOR t IN firstCollection FILTER t.name == @name RETURN t";
Map<String, Object> bindVars = Collections.singletonMap("name", "Homer");
System.out.println("Executing read query ...");
ArangoCursor<BaseDocument> cursor = db.query(query, bindVars, null, BaseDocument.class);
cursor.forEach(aDocument -> System.out.println("Key: " + aDocument.getKey()));

After executing this program the console output should look something like this:

Key: 1
Key: 0
Key: 5
Key: 3
Key: 4
Key: 9
Key: 2
Key: 7
Key: 8
Key: 6

Please note that:

  • the AQL query uses the @name placeholder which has to be bound to a value
  • query() executes the defined query and returns ArangoCursor with the given class (here: BaseDocument)
  • the order is not guaranteed

Delete a document with AQL

To delete the document created before, execute the following:

String query = "FOR t IN firstCollection FILTER t.name == @name "
    + "REMOVE t IN firstCollection LET removed = OLD RETURN removed";
Map<String, Object> bindVars = Collections.singletonMap("name", "Homer");
System.out.println("Executing delete query ...");
ArangoCursor<BaseDocument> cursor = db.query(query, bindVars, null, BaseDocument.class);
cursor.forEach(aDocument -> System.out.println("Removed document " + aDocument.getKey()));

After executing this program the console output should look something like this:

Removed document: 1
Removed document: 0
Removed document: 5
Removed document: 3
Removed document: 4
Removed document: 9
Removed document: 2
Removed document: 7
Removed document: 8
Removed document: 6

Learn more