A java introduction to OrientDB document database

OrientDB is a NoSQL document database, like the very popular MongoDB. It has some very interesting additional features:

• support for relationships between documents
• native support of SQL query language (except for JOIN operations, which are not required thanks to the relations between documents)

The support for links makes that OrientDB can also be used has a (very fast) graph database.

For this introduction we will use:

• Ubuntu 16.04 as host operating system
• OrientDB 3.0.2 (the current release)
• Java and maven for the client code

Installation and first run

OrientDB server is written in Java. It requires at least java 8:

$ sudo apt-get install openjdk-8-jdk

You can now download and unpack OrientDB itself:

$ wget https://s3.us-east-2.amazonaws.com/orientdb3/releases/3.0.2/orientdb-3.0.2.tar.gz
$ tar xvzf orientdb-3.0.2.tar.gz

To run , simply

$ cd orientdb-3.0.2
$ ./bin/server.sh

At the first run, the server will ask you for a root password. Don't forget to write it down!

Web interface

OrientDB has a built-in web interface, available on port 2480: http://127.0.0.1:2480

Using your root password, you can now create a new database, called testdb for example.

Maven

Even though OrientDB is written in java, bindings exist for most programming languages like NodeJS, PHP, Python and .NET: https://orientdb.com/docs/last/

For this introduction, we will use java and maven. So we start by creating a maven project, either using an IDE or the command line:

mvn archetype:generate -DarchetypeArtifactId=maven-archetype-quickstart

Then add OrientDB client dependency to your pom:

<dependency>
    <groupId>com.orientechnologies</groupId>
    <artifactId>orientdb-client</artifactId>
    <version>3.0.2</version>
</dependency>

Java

You can now start with the java code. In this post we will only review the document API. The graph API will be covered in another post.

All the javadoc is available online: https://orientdb.com/javadoc/develop/ Be warned, as OrientDB is evolving very quickly, it is not always up-to-date. For example, at the time of writing, the javadoc for the OrientDB() constructor was not correct!

// Connect to the server
OrientDB orient = new OrientDB(
        "remote:localhost",
        new OrientDBConfigBuilder().build());

// Connect to the database
// OrientDB.open() actually returns an ODatabase interface
// Here we will use the Document API
ODatabaseDocument db = orient.open("testdb", "root", "abc1234!");

// Insert a document
OElement person = db.newElement("Person");
person.setProperty("name", "Luke");
person.setProperty("surname", "Skywalker");
person.save();

// The document now has an ID (called Record ID or RID) that can be used to
// fetch the document from the database
ORID id = person.getIdentity();
System.out.println(id);
ORecord person_2 = db.load(id);
System.out.println("Are equal: " + person_2.equals(person));
System.out.println("Are identical: " + (person_2 == person));

// If we have a string version of the ID, it can also be used to
// load the document:
OElement record = db.load(new ORecordId("#33:0"));
System.out.println("Document #33:0: " + record);

// Create another document
OElement planet = db.newElement("Planet");
planet.setProperty("name", "Dagoba");
planet.save();

// Create a relation
person.setProperty("planet", planet);
person.save();

// SQL can be used to query the data
OResultSet rs = db.query("SELECT FROM Person");
while (rs.hasNext()) {
    OResult row = rs.next();
    System.out.println("Name: " + row.getProperty("name"));
    System.out.println("Planet: " + row.getProperty("planet"));

    // Follow the relation
    OElement row_planet = row.getElementProperty("planet");
    System.out.println(row_planet);
    System.out.println("" + row_planet.getProperty("name"));
}
// don't forget to close the result set!
rs.close();

db.close();
orient.close();

Running this code will produce a result like the one below:

#33:0
Are equal: true
Are identical: true
Document #33:0: Person#33:0{name:Luke,surname:Skywalker} v1
Name: Luke
Planet: #41:0
Planet#41:0{name:Dagoba} v1
Dagoba

As we can see, row.getProperty("planet") returns the id of the related document, while row.getElementProperty("planet") returns the document itself.

RID

In OrientDB, every document has a Record ID (or RID), with the format #<cluster-id>:<cluster-position>

• cluster-id is (as the name states) the id of the cluster. A cluster is the equivalent of a table in a relational database, or a collection in MongoDB.
• cluster-position is the position of the record inside the cluster. Each cluster can handle up to 9,223,372,036,854,780,000 (2^63) records, namely 9,223,372 Trillion of records!

The Record ID of a document is actually the physical position of the record inside the database. This means that loading a record by its RID is extremely fast. It also allows to follow relations between documents very fast!

This blog post is licensed under CC BY-SA 4.0