OrientDB: Java API

The following example show how to use OrientDB Java API to work with local Document Database.
Take a look to database types.

Document Database  offers a good compromise between speed and flexibility.




We show how to

• Connect to a database and open it
• Create a document (record) and populate fields
• Persist the document (record) created
• Close database

public class OrientDBTest {
   public static void main(String[] args) {
      //Connect to database
      ODatabaseDocumentTx db = new ODatabaseDocumentTx("local:/tmp/db/scratchpad");
      //Open database with user and password
      db.open("admin", "admin");
      //Create a new document (record)
      ODocument doc = db.newInstance();
      //Populate the fields
      doc.field("name", "Jay");
      doc.field("surname", "Miner");
      //Persist data
      doc.save();
      //Close database
      db.close();
   }
}

OrientDB create, populate, connect and query

Create Class (Table)
Examples: 
create class Person extends V 
create class Restaurant extends V

Create Vertex (Populate)
Examples:
create vertex Person set name = 'Luca'
create vertex Person set name = 'Bill'
create vertex Person set name = 'Jay'

create vertex Restaurant set name = 'Dante', type = 'Pizza'
create vertex Restaurant set name = 'Charlie', type = 'French'

Create Edge (Relatio)
Examples:
create class Eat extends E 
create class Friend extends E

Create Connections
Examples: 
create edge Eat from (select from Person where name = 'Luca') to (select from Restaurant where name = 'Dante')

If you know the RID of vertices you can connect them with a shorter and faster command: 
create edge Eat from #11:1 to #12:0
create edge Eat from #11:2 to #12:1 
create edge Friend from #11:0 to #11:2

Cross Edges (Join)
To cross edges we can use special graph functions like:

• out(), to retrieve the adjacent outgoing vertices
• in(), to retrieve the adjacent incoming vertices
• both(), to retrieve the adjacent incoming and outgoing vertices

Examples:
Note: expands() is a special function very useful to transforms a resultset of vertices in a expanded resultset (showing all data).

To know all the people that eat in Dante restaurant we can get Dante's record and then cross back traversing the incoming edges to discover the Person records connected 
select expand( in() ) from Restaurant where name = 'Dante'

In the following example we've passed the Edge's class "Friend" as argument of the both() function to cross only the relationships of kind "Friend" (so skip the "Eat" this time). 
select expand( both('Friend') ) from Person where name = 'Luca' 

Get all the restaurants where go Luca's friends. 
select expand( both('Friend').out('Eat') ) from Person where name = 'Luca'

OrientDB console commands and query syntax

Run console via
[OrientDB_Home]/bin/console.sh

Type the "help" or "?" command to see all available console commands.

All avilable console commands at this url: Tutorial:-Run-the-console



Some usefull console commands and query

---

Connect to database or a remote server instance
Synopsis: 
connect <url> <user> <password>
Ex:  
connect remote:localhost root someUglyPassword
connect remote:localhost/dbname admin admin

Let's analyze the URL we have used: remote:localhost/demo.
The first part is the protocol, remote in this case, which means to contact the server using the TCP/IP protocol. localhost is the host name or the IP address where the server resides, in this case it is on the same machine. demo is the name of the database with which we want to connect.

---

List all databases
Synopsis: 
list databases

---

Database info
Synopsis: 
info

---

Create a new database
Synopsis: 
create database <database-url> <user> <password> <storage-type> <db-type>
Parameters:
- storage-type (local or memory)
- db-type (document or graph)
Ex:
create database remote:localhost/mytest root admin local graph

---

Display all classes on database
Synopsis: 
classes

---

Display all clusters on database
Synopsis: 
clusters

---

Class info
Synopsis: 
info class <class-name>
Ex:
info class Student

---

Create a class
Synopsis: 
create class <command-text>
Ex:
create class Student 

---

Create a class property
Synopsis: 
create property <command-text>
Ex:
create property Student.surname string
create property Student.birthDate date

---

Alter a class property
Synopsis: 
alter property <command-text>
Ex:
alter property Student.name min 3

---

Retrieve all records of a class
Synopsis: 
browse class <class-name>
Ex:
browse class OUser

---

Display  record attributes
Synopsis: 
display record <number>
Parameters:
- number (record number)
Ex:
display record 0

---

Select a record (OrientDB syntax)
Synopsis: 
load record <record-id>
Ex:
load record #12:4

---

Select records (SQL like syntax)
Synopsis: 
select <query-text>

Base Ex:

• select from MyClass (select work on classes by default)
• select from cluster:MyCluster (peform select on cluster)
• select from #10:3 oppure select from [#10:3, #10:3, #10:5](select specific records by RID)
• select from OUser where name like 'l%'
• select from Employee where city = 'Rome' order by surname asc, name asc
• select sum(salary) from Employee where age < 40 group by job
• select from Employee where gender = 'male' limit 20
• select from Employee where gender = 'male' skip 40 limit 20 (usefull for pagination)
• select name, phones from student where phone.keys() in ('mobile') (select by the key "mobile" of th asociative map attribute "phone")

Join Ex:

• Perform JOIN between "city" and "country" tables (classes)
  select * from city where country.name = 'Italy'
• Select first 3 names of city from records of type "address" for italian (country) address
  select city.name from address where city.country.name = 'Italy' limit 3 
• Select all account with atleast  one address (Note: "addresses" is a special attribute of type collection in the class (table) "account".  It realizes a 1-N relation).
  select from account where addresses.size() > 0
• Find accounts with at least one address of Washington.
  Note: "addresses" is a special attribute of type collection in the class (table) "account".  It realizes a 1-N relation.
  Note: FLATTEN() ectrat results from different collections and put all them in a single collection to facilitate data management.
  select flatten(addresses) from account where addresses contains ( city.country.name = 'Washington' ) 

Note: when we perform a select, values inside an array are not shown. By default we can see only a number of element inside the collection.

---

Insert records (SQL like syntax)
Note:
in OrientDB sql insert syntax, the list of fields is mandatory. The reason is simple: OrientDB is a schema-less DBMS;
is it possible to insert array and associatives mapps values using "[]" and "{}".

Ex:
insert into student (name,surname) values ('Jay','Miner')

---

Update records (SQL like syntax)

Ex:
UPDATE test SET city = 'Rome' WHERE name = 'Luca'

UPDATE has been extended with new keywords:

• ADD and PUT, to insert elementin collections as array or map respectively. If the array or mapp does not existit will be created automatically;
• REMOVE, to remove an element from a collection. Creiamo una nuova collection di string, che rappresentarà il set di tag che assoceremo ai record: 

Add element to array:
UPDATE student ADD tags = 'tutorial'

Add element to associative ma:
UPDATE test put phones = 'mobile', '+393333888' WHERE name = 'Luca'

Note: when we perform a select, values inside an array are not shown. By default we can see only a number of element inside the collection. 

---

Delete records (SQL like syntax) 

Ex:
DELETE FROM student WHERE tags.size() > 0

---

OrientDB configuration and running

Configuration file
[OrientDB_Home]/config/orientdb-server-config.xml

Run server
[OrientDB_Home]/bin/server.sh

Run console
[OrientDB_Home]/bin/console.sh


Note: by default each database has "admin" user with password "admin".

OrientDB tips

Document (Object instance) = Record

Class (Object descriptor) = Table

Property (Object attribute) = Column

Cluster: even though by default one class = one cluster, a class can relies on multiple clusters. Why? This is because you can spawn records physically in multiple places.
Clusters are "containers" in which Classes (tables) organize documents (records) .
A class can have one or more cluster (one by default).

Types of clusters:

• Physical: write on file system; 
• Logic: use Phisical, but do not create files. It si slower than phisical;
• Memory: all informations in this clusters are not permanent, and will be lost at the end of the process or  server. Memory cluster are usefull for applicative cache.

Select queries search in all clusters of a class by default.
Insert queries by default insert data in the default cluster.
We can refer to a specific cluster (so we can improve performance and launch parallel query):
select * from cluster:clusterName

Record id RID:
<cluster-id>:<cluster-position>
RID identifies uniquely a Document (a record) in the whole database (not just in a table). It is the physical position of the record inside the database.

• cluster-id is the id of the cluster. Each database can have a maximum of 32,767 clusters (2^15)
• cluster-position is the position of the record inside the cluster. Each cluster can handle up to 9,223,372,035,000,000,000 (2^63) records.

So the maximum size of a database is 2^78 records = 302,231,454,903,657,000,000,000 records.

Example of use in query:
load record #12:4

Amazing performance:
"THE JOIN IS THE EVIL"
Looking for an ID at runtime, every time you execute a query and foreach record it could be very very expensive!
The first optimization is using indexes. That's true, indexes speed up searches but slow down INSERT, UPDATE and DELETE operations.
Furthermore they occupy substantial space on disk and memory.

In OrientDB a RID (RecordID) is the physical position of the record inside the database. This means that loading a record by its RID it's blazing fast with response time close to be constant O(1) even if the database grows. This is huge in the BigData age!