How To Install and Use OrientDB on an Ubuntu 12.04 VPS

OrientDB is not available from Ubuntu’s default repositories, so we will have to get it from the project’s GitHub page. Before we do that, however, we should install some prerequisite software:

sudo apt-get update
sudo apt-get install openjdk-7-jdk git ant

Once that process is complete, you can clone the latest snapshot from the GitHub page. We will do this in our home directory:

cd
git clone https://github.com/orientechnologies/orientdb.git

This will create a directory called “orientdb” in your home directory. Enter this directory and then use the Apache ant tool that we installed to build the software:

cd orientdb
ant clean install

After OrientDB is finished building, you will have a new directory under your home directory called “releases”. We have the database system below this in a versioned folder:

cd ../releases/orientdb*

Change to the bin directory and start the server by typing:

cd bin
./server.sh &

This will start running the server on your system in the background. If you need to kill the server instance, you can search for the pid with ps and then kill the process:

ps aux | grep server.sh | grep -v grep | awk '{ print $2; }' | xargs kill

When started, the server exposes two separate ports that you can use depending on the protocol you wish to employ:

• 2424: This port is opened and used for binary access to the database. This means that you can use clients and drivers that operate with the network binary protocol, or the database console to interact with the database through this port.
• 2480: This port is opened and used for HTTP interaction through a RESTful API. You can access your server’s web tool by visiting this port with your browser.

We will connect with the database we started in the terminal to learn about how OrientDB operates.

We can do this from the same “bin” directory where we started the server, but first, we must get the default password so we can connect to the database:

nano ../config/orientdb-server-config.xml

In this file, search for the “users” section. You should see an entry with an associated name of “root”. There will also be an extremely long password. Copy this password somewhere where you can paste it momentarily.

Close the file once you have the information.

In the bin directory, start the OrientDB console by typing:

./console.sh

You will be dropped into the OrientDB prompt, where you can interact with the software.

First, we need to connect to the server instance that we started. We can do this by typing:

<pre> connect remote:localhost root <span class=“highlight”>copied_password</span> </pre>

You can test if the server is available by trying to list the databases:

list databases

If it is successful, you should see a GratefulDeadConcerts database, which is used as the sample database in OrientDB. If not, you should see this warning:

Not connected to the Server instance. You've to connect to the Server using server's credentials (look at orientdb-*server-config.xml file)

You should now be connected to the server and ready to give it commands.

Connect to the database we have using a similar syntax to the server connection. This database has a user of admin and a password of admin as well:

connect remote:localhost/GratefulDeadConcerts admin admin

OrientDB organizes its information using a various categories at a number of different hierarchical levels.

Because of its hybrid design, OrientDB can organize its records into documents or graphs. Documents are, for the most part, the same as they are in other NoSQL systems. They are simple chunks of information without a predefined set of fields, which can be altered and morphed as necessary.

Graphs are another form of storage that organizes data in a different way. Graphs are useful for forming relational patterns between different points of data. Each point of data is called a vertex and each relationship is called an edge. Basically, it is just a link with a label describing the relationship that can be used to follow and find connections between different distinct objects.

Borrowing from object-oriented programming languages, OrientDB organizes documents into classes. A class, in OrientDB, is a way to organize sets of data using certain constraints and rules. It basically defines a document format in a broad sense.

A cluster is a way of storing groups of records in an organized way. It is similar to a table in a relational database. It is perhaps easier to think of clusters as pools of data, because clusters can contain documents of different types.

Generally, by default, OrientDB will create one cluster for each class and store all of the documents of that class in that single cluster. However, there is flexibility here, and you can have a cluster group two related classes documents together, or you can have two separate clusters serving one class.

We will begin by exploring how OrientDB works with documents, since this is perhaps a more familiar way of organizing data to most people.

Rather than starting with documents themselves, though, we will get to them by examining the class and cluster structures so that we have some context for our discussion.

We can see the existing classes by typing:

classes

CLASSES:
----------------------------------------------+------------------------------------+------------+----------------+
 NAME                                         | SUPERCLASS                         | CLUSTERS   | RECORDS        |
----------------------------------------------+------------------------------------+------------+----------------+
 E                                            |                                    | 10         |              0 |
 Eat                                          | E                                  | 14         |              0 |
 Friend                                       | E                                  | 15         |              0 |
. . .

You can see many different classes. The one that are preceded with a “O” are OrientDB internal classes that can be used to get information about the database and system themselves. Other important classes are the “V” class, which means vertex, and “E” which means edge, which are used for the graph functionality.

We can create a new class by typing:

<pre> create class <span class=“highlight”>New_class</span> </pre>

You can then add fields to the document by typing:

<pre> create property <span class=“highlight”>New_class</span>.<span class=“highlight”>field_name</span> <span class=“highlight”>data_type</span> </pre>

For instance, if we wanted to create a class called “vegetables” and begin to define some important properties, we could type this:

create class Vegetable
create property Vegetable.name string
create property Vegetable.color string
create property Vegetable.quantity integer
create property Vegetable.good_on_pizza boolean

We can see information including the properties associated with the Vegetable class by typing:

info class Vegetable

To view the members of the class, you can use browse. We can use this syntax:

<pre> browse class <span class=“highlight”>class_name</span> </pre>

In a similar way, you can view clusters by just typing:

clusters

As you can see, this list is pretty much the same as the class list due to the fact that OrientDB by default creates a cluster for each new class. If there is a difference between the class and cluster, we can browse by cluster as well:

<pre> browse cluster <span class=“highlight”>cluster_name</span> </pre>

When we’ve found a record in our browsing that we’d like more info on, we can display it by referencing its RecordID.

Each record stored in the system has its own RecordID. This value is simply the cluster that the data is stored on followed by the sequential item number that it is stored under. For instance, the first record in cluster 9 would be given the recordID #9:0. The second would be given the recordID of #9:1.

You can view records using this syntax:

<pre> display record <span class=“highlight”>record_number</span> </pre>

This will reference whatever the most recent browsing operation was, so it does not use the full recordID, just the last number that shows sequence.

To load a record, we can type:

<pre> load record <span class=“highlight”>recordID</span> </pre>

In this case, we must specify the full record number.

Operating on Documents with SQL Syntax

We can interact with documents in much the same way as with relational databases. This was implemented as a design choice to lessen the learning curve for common database interactions.

For instance, to query data, you can use a select statement. We don’t need a wildcard if we want to get the entire record:

<pre> select from <span class=“highlight”>class_name</span> </pre>

To select from a cluster instead, we can use:

<pre> select from cluster:<span class=“highlight”>cluster_name</span> </pre>

Another option is to select from the recordID:

<pre> select from <span class=“highlight”>recordID</span> </pre>

We can use “where” and “order” to constrain and sort the data:

select from OIdentity where name = 'admin' order by rules

There are quite a few other ways you can query for data, most of which follow the SQL syntax.

A less common way of dealing with records, but one which adds a lot of flexibility to OrientDB, is the graph relational behavior.

OrientDB can create records in a graph context. We position points of data as vertices. These are independent pieces of data that can be connected through “edges”, which are basic pointers that draw a connection between two unrelated pieces.

We can create vertex classes by extending the default vertex class called “V”:

create class Animal extends V

This will create a class called Animal. Each member of this class represents a point that we can connect to other members of the class, or other members of other vertex classes.

Let’s create a food class and an environment class so that we can draw up some connections.

create class Food extends V
create class Environment extends V

Now we have 3 vertex classes. We should also create some relations. These relations are called edges, and they basically describe how the two pieces are related:

create class Eat extends E
create class Live extends E

Let’s create a member in each:

create vertex Animal set name = 'Rabbit'
create vertex Food set name = 'Carrot'
create vertex Environment set name = 'Forest'

Now we need to apply the edges to these data points to create relationships:

create edge Eat from (select from Animal where name = 'Rabbit') to (select from Food where name = 'Carrot')

Since we only have one record in each, we can actually leave off the where clause:

create edge Live from (select from Animal) to (select from Environment)

These edge connections create “in” and “out” lines that point to the connected record. For instance, our rabbit has two “out” lines that connect it to the other pieces (food and environment).

The other two pieces each have “in” connections that specify that there is a relationship going from another element to these elements.

We can explore these relationships using a combination of standard select queries and a function called expand, which can provide more in-depth information. You can specify an in connection, an out connection, or both:

select expand( out() ) from Animal

----+-----+------+------+-------
#   |@RID |name  |in_Eat|in_Live

----+-----+------+------+-------
0   |#18:0|Carrot|#17:0 |null   
1   |#19:0|Forest|null  |#17:0  

----+-----+------+------+-------

We can use these to form complex webs that explain the relationships between different pieces of data. The advantage of making these connections using edges and links as opposed to traditional relational means is that returning the related data is much faster and less expensive.

You can create many different connections without adding significant overhead to your queries.

You should now have a good idea of how to work with a OrientDB database system. As you can see, it blends many elements from different systems. It keeps SQL select querying syntax, while leveraging traditional NoSQL document storage, and builds graph relational behavior.

This has only been a brief introduction meant to introduce you to some of the ways that OrientDB can operate on data. The project’s documentation is a great resource for building off of this introduction.

<div class=“author”>By Justin Ellingwood</div>