Spring Data with ArangoDB

1. Introduction

In this tutorial, we’ll learn how to work with the Spring Data module and ArangoDB database. ArangoDB is a free and open-source multi-model database system. It supports key-value, document, and graph data models with one database core and a unified query language: AQL (ArangoDB Query Language).

We’ll cover the required configuration, basic CRUD operations, custom queries, and entities relations.

2. ArangoDB Setup

To install ArangoDB, we’ll first need to download the package from the Download page of the official ArangoDB website.

For the purpose of this tutorial, we will go with installing the community edition of ArangoDB. Detailed installation steps can be found here.

The default installation contains a database called _system and a root user which has access to all databases.

Depending upon the package, the installer will either ask for a root password during the installation process or will set a random password.

With the default configuration, we’ll see the ArangoDB server running on 8529 port.

Once the setup is done, we can interact with the server using the Web Interface accessible on http://localhost:8529. We will use this host and port for Spring Data configuration later in the tutorial.

We can also alternatively use arangosh, a synchronous shell for interaction with the server.

Let’s start with launching arangosh to create a new database called baeldung-database and a user baeldung with access to this newly created database.

arangosh> db._createDatabase("baeldung-database", {}, [{ username: "baeldung", passwd: "password", active: true}]);

3. Dependencies

To use Spring Data with ArangoDB in our application, we’ll need the following dependency:

<dependency>
    <groupId>com.arangodb</groupId>
    <artifactId>arangodb-spring-data</artifactId>
    <version>3.5.0</version>
</dependency>

4. Configuration

Before we start working with the data, we need to set up a connection to ArangoDB. We should do it by creating a configuration class that implements the ArangoConfiguration interface:

@Configuration
public class ArangoDbConfiguration implements ArangoConfiguration {}

Inside we’ll need to implement two methods. The first one should create ArangoDB.Builder object that will generate an interface to our database:

@Override
public ArangoDB.Builder arango() {
    return new ArangoDB.Builder()
      .host("127.0.0.1", 8529)
      .user("baeldung").password("password"); }

There are four required parameters to create a connection: host, port, username, and password.

Alternatively, we can skip setting these parameters in the configuration class:

@Override
public ArangoDB.Builder arango() {
    return new ArangoDB.Builder();
}

As we can store them in arango.properties resource file:

arangodb.host=127.0.0.1
arangodb.port=8529
arangodb.user=baeldung
arangodb.password=password

It’s a default location for Arango to look for. It can be overwritten by passing an InputStream to a custom properties file:

InputStream in = MyClass.class.getResourceAsStream("my.properties");
ArangoDB.Builder arango = new ArangoDB.Builder()
  .loadProperties(in);

The second method we have to implement is simply providing a database name that we need in our application:

@Override
public String database() {
    return "baeldung-database";
}

Additionally, the configuration class needs the @EnableArangoRepositories annotation that tells Spring Data where to look for ArangoDB repositories:

@EnableArangoRepositories(basePackages = {"com.baeldung"})

5. Data Model

As a next step, we’ll create a data model. For this piece, we’ll use an article representation with a name, author, and publishDate fields:

@Document("articles")
public class Article {

    @Id
    private String id;

    @ArangoId
    private String arangoId;

    private String name;
    private String author;
    private ZonedDateTime publishDate;

    // constructors
}

The ArangoDB entity must have the @Document annotation that takes the collection name as an argument. By default, it’s a decapitalize class name.

Next, we have two id fields. One with a Spring’s @Id annotation and a second one with Arango’s @ArangoId annotation. The first one stores the generated entity id. The second one stores the same id nut with a proper location in the database. In our case, these values could be accordingly 1 and articles/1.

Now, when we have the entity defined, we can create a repository interface for data access:

@Repository
public interface ArticleRepository extends ArangoRepository<Article, String> {}

It should extend the ArangoRepository interface with two generic parameters. In our case, it’s an Article class with an id of type String.

6. CRUD Operations

Finally, we can create some concrete data.

As a start point, we’ll need a dependency to the articles repository:

@Autowired
ArticleRepository articleRepository;

And a simple instance of the Article class:

Article newArticle = new Article(
  "ArangoDb with Spring Data",
  "Baeldung Writer",
  ZonedDateTime.now()
);

Now, if we want to store this article in our database, we should simply invoke the save method:

Article savedArticle = articleRepository.save(newArticle);

After that, we can make sure that both the id and arangoId fields were generated:

assertNotNull(savedArticle.getId());
assertNotNull(savedArticle.getArangoId());

To fetch the article from a database, we’ll need to get its id first:

String articleId = savedArticle.getId();

Then simply call the findById method:

Optional<Article> articleOpt = articleRepository.findById(articleId);
assertTrue(articleOpt.isPresent());

Having the article entity, we can change its properties:

Article article = articleOpt.get();
article.setName("New Article Name");
articleRepository.save(article);

Finally, invoke again the save method to update the database entry. It won’t create a new entry because the id was already assigned to the entity.

Deleting entries is also a straightforward operation. We simply invoke the repository’s delete method:

articleRepository.delete(article)

Delete it by the id is also possible:

articleRepository.deleteById(articleId)

7. Custom Queries

With Spring Data and ArangoDB, we can make use of the derived repositories and simply define the query by a method name:

@Repository
public interface ArticleRepository extends ArangoRepository<Article, String> {
    Iterable<Article> findByAuthor(String author);
}

The second option is to use AQL (ArangoDb Query Language). It’s a custom syntax language that we can apply with the @Query annotation.

Now, let’s take a look at a basic AQL query that’ll find all articles with a given author and sort them by the publish date:

@Query("FOR a IN articles FILTER a.author == @author SORT a.publishDate ASC RETURN a")
Iterable<Article> getByAuthor(@Param("author") String author);

8. Relations

ArangoDB gives as a possibility to create relations between entities.

As an example, let’s create a relation between an Author class and its articles.

To do so, we need to define a new collection property with @Relations annotation that will contain links to each article written by a given author:

@Relations(edges = ArticleLink.class, lazy = true)
private Collection<Article> articles;

As we can see, the relations in ArangoDB are defined through a separate class annotated with @Edge:

@Edge
public class ArticleLink {

    @From
    private Article article;

    @To
    private Author author;

    // constructor, getters and setters
}

It comes with two fields annotated with @From and @To. They define the incoming and outcoming relation.

9. Conclusion

In this tutorial, we’ve learned how to configure ArangoDB and use it with Spring Data. We’ve covered basic CRUD operations, custom queries, and entity relations.