OrientDB Manual 1.7.8

Basic Concepts


A record is the smallest unit that can be loaded from and stored into the database.

Record types

There are several types of records.


Documents are the most flexible record available in OrientDB. They are softly typed and are defined by schema classes with the defined constraints, but can be used also in schema-less mode. Documents handle fields in a flexible way. A Document can be easily imported and exported in JSON format. Below is an example of a Document in JSON format:

  "name": "Jay",
  "surname": "Miner",
  "job": "Developer",
  "creations": [
    { "name": "Amiga 1000",
      "company": "Commodore Inc."
    { "name": "Amiga 500",
      "company": "Commodore Inc."

OrientDB Documents support complex relationships. From a programmer's perspective this can be seen as a sort of persistent Map.


Records are strings. No fields are supported, no indexing, no schema.


In OrientDB, each record has an auto assigned Unique ID. The RecordID (or RID) is composed in this way:



  • cluster, is the cluster id. Positive numbers mean persistent records. Negative numbers mean temporary records, like those used in result sets for queries that use projections.
  • position, is the absolute position of the record inside a cluster.

NOTE: The prefix character # is mandatory to recognize a RecordID.

The record never looses its identity unless is deleted. Once deleted its identity is never recycled (but with "local" storage). You can access a record directly by its RecordID. For this reason you don't need to create a field as a primary key like in a Relational DBMS.

Record version

Each record maintains its own version number that is incremented at every update. When a record is created, the version is zero. In optimistic transactions the version is checked in order to avoid conflicts at commit time.


A Class is a concept taken from the Object Oriented paradigm. In OrientDB it defines a type of record. It's the closest concept to a Relational DBMS Table. Classes can be schema-less, schema-full or mixed.

A class can inherit from another, creating a tree of classes. Inheritance) means that the sub-class extends the parent one, inheriting all the attributes.

Each class has its own clusters. A class must have at least one cluster defined (its default cluster), but can support multiple ones. In this case by default OrientDB will write new records in the default cluster, but reads will always involve all the defined clusters.

When you create a new class by default a new physical cluster is created with the same name of the class in lowercase.

Abstract Class

If you know Object-Orientation you already know what is an abstract class. For all the rest:

To create a new abstract class look at SQL Create Class.

Abstract classes are essential to support Object Orientation without the typical spamming of the database with always empty auto-created clusters. NOTE: available since 1.2.0

When to use class or cluster in queries?

Let's use an example: Let's assume you created a class "Invoice" and 2 clusters "invoice2011" and "invoice2012".

You can now query all the invoices by using the class as target in SQL select:


If you want to filter per year 2012 and you've created a "year" field in Invoice class do:

SELECT FROM Invoice where year = 2012

You may also query specific objects from a single cluster (so, by splitting the Class Invoice in multiple clusters, e.g. one per year, you narrow your candidate objects):

SELECT FROM cluster:invoice2012

This query may be significantly faster because OrientDB can narrow the search to the targeted cluster.

The combination of Classes and Clusters is very powerful and has many use cases.


OrientDB supports two kinds of relationships: referenced and embedded. OrientDB can manage relationships in a schema-full or in schema-less scenario.

Referenced relationships

Relationships in OrientDB are managed natively without computing costly JOINs as in a Relational DBMS. In fact, OrientDB stores the direct link(s) to the target objects of the relationship. This boosts up the load of entire graph of connected objects like in Graph and Object DBMSs. Example:

  Record A     ------------->    Record B
CLASS=Invoice                 CLASS=Customer
  RID=5:23                       RID=10:2

Record A will contain the reference to Record B in the property called "customer". Note that both records are reachable by other records since they have a RecordID.

1-1 and N-1 referenced relationships

This kind of relationships are expressed using the LINK type.

1-N and N-M referenced relationships

This kind of relationships are expressed using the collection of links such as:

  • LINKLIST, as an ordered list of links
  • LINKSET, as an unordered set of links. It doesn't accepts duplicates
  • LINKMAP, as an ordered map of links with String as key type. Keys doesn't accepts duplicated

Embedded relationships

Embedded records, instead, are contained inside the record that embeds them. It's a kind of relationship stronger than the reference. It can be represented like the UML Composition relationship. The embedded record will not have an own RecordID, since it can't be directly referenced by other records. It's only accessible through the container record. If the container record is deleted, then the embedded record will be deleted too. Example:

  Record A     <>---------->   Record B
CLASS=Account               CLASS=Address
  RID=5:23                     NO RID!

Record A will contain the entire Record B in the property called "address". Record B can be reached only by traversing the container record.


SELECT FROM account WHERE address.city = 'Rome'

1-1 and N-1 embedded relationships

These kinds of relationships are expressed using the EMBEDDED type.

1-N and N-M embedded relationships

These kinds of relationships are expressed using a collection of links such as:

  • EMBEDDEDLIST, as an ordered list of records
  • EMBEDDEDSET, as an unordered set of records. It doesn't accepts duplicates
  • EMBEDDEDMAP, as an ordered map of records as value with key a String. It doesn't accept duplicated keys

Inverse relationships

In OrientDB, all Graph Model edges (connections between vertices) are bi-directional. This differs from the Document Model where relationships are always mono-directional, thus requiring the developer to maintain data integrity. In addition, OrientDB automatically maintains the consistency of all bi-directional relationships (aka edges).


A database is an interface to access the real Storage. The database understands high-level concepts like Queries, Schemas, Metadata, Indexes, etc. OrientDB also provides multiple database types. Take a look at the Database types to learn more about them.

Each server or JVM can handle multiple database instances, but the database name must be UNIQUE. So you can't manage 2 databases named "customer" in 2 different directories at the same time. To handle this case use the $ (dollar) as separator instead of / (slash). OrientDB will bind the entire name, so it will be unique, but at the file system level it will convert $ with / allowing multiple databases with the same name in different paths. Example:

test$customers -> test/customers
production$customers = production/customers

The database must be opened as:

test = new ODatabaseDocumentTx("remote:localhost/test$customers");
production = new ODatabaseDocumentTx("remote:localhost/production$customers");

Database URL

OrientDB has its own URL format:



  • db-name is the database name and depends on the engine used (see below)
  • engine can be:
Engine Description Example
plocal This engine writes to the file system to store data. There is a LOG of changes to restore the storage in case of crash. plocal:/temp/databases/petshop/petshop
memory Open a database completely in memory memory:petshop
remote The storage will be opened via remote network connection. It requires an OrientDB Server up and running. In this mode, the database is shared among multiple clients. Syntax: remote:<server>:[<port>]/db-name. The port is optional and defaults to 2424. remote:localhost/petshop

Database usage

The database must always be closed once you've finished working with it.

NOTE: OrientDB automatically closes all opened storages when the process dies softly (not by force killing). This is assured if the Operating System allows a graceful shutdown.