Hibernate OGM Reference Guide

Hibernate OGM is a young project. The code, the direction and the documentation are all in flux and being built by the community. Join and help us shape it!

#get the sources
git clone https://github.com/hibernate/hibernate-ogm
cd hibernate-ogm

#build project
mvn clean install -s settings-example.xml

mvn clean install -DbuildDocs=true -s settings-example.xml

OGM-123 Summary of commit operation

Optional details on the commit
and a longer description can be
added here.

If you are familiar with JPA, you are almost good to go :-) We will nevertheless walk you through the first few steps of persisting and retrieving an entity using Hibernate OGM.

Before we can start, make sure you have the following tools configured:

Hibernate OGM is published in the JBoss hosted Maven repository. Adjust your ~/.m2/settings.xml file according to the guidelines found on this webpage. In this example we will use Infinispan as the targeted datastore.

Add org.hibernate.ogm:hibernate-ogm-infinispan:4.0.0.Beta4 to your project dependencies.

<dependency>

    <groupId>org.hibernate.ogm</groupId>

    <artifactId>hibernate-ogm-infinispan</artifactId>

    <version>4.0.0.Beta4</version>

</dependency>

<dependency>

    <groupId>org.hibernate.javax.persistence</groupId>

    <artifactId>hibernate-jpa-2.0-api</artifactId>

    <version>1.0.1.Final</version>

</dependency>

We will use the JPA APIs in this tutorial.

Let’s now map our first Hibernate OGM entity.

@Entity

public class Dog {

   @Id @GeneratedValue(strategy = GenerationType.TABLE, generator = "dog")

   @TableGenerator(

      name = "dog",

      table = "sequences",

      pkColumnName = "key",

      pkColumnValue = "dog",

      valueColumnName = "seed"

   )

   public Long getId() { return id; }

   public void setId(Long id) { this.id = id; }

   private Long id;


   public String getName() { return name; }

   public void setName(String name) { this.name = name; }

   private String name;


   @ManyToOne

   public Breed getBreed() { return breed; }

   public void setBreed(Breed breed) { this.breed = breed; }

   private Breed breed;

}


@Entity

public class Breed {


   @Id @GeneratedValue(generator = "uuid")

   @GenericGenerator(name="uuid", strategy="uuid2")

   public String getId() { return id; }

   public void setId(String id) { this.id = id; }

   private String id;


   public String getName() { return name; }

   public void setName(String name) { this.name = name; }

   private String name;

}

I lied to you, we have already mapped two entities! If you are familiar with JPA, you can see that there is nothing specific to Hibernate OGM in our mapping.

In this tutorial, we will use JBoss Transactions for our JTA transaction manager. The final list of dependencies should look like this:

<dependencies>

    <!-- Hibernate OGM dependency -->

    <dependency>

        <groupId>org.hibernate.ogm</groupId>

        <artifactId>hibernate-ogm-core</artifactId>

        <version>4.0.0.Beta4</version>

    </dependency>



    <!-- standard APIs dependencies - provided in a Java EE container -->

    <dependency>

        <groupId>org.hibernate.javax.persistence</groupId>

        <artifactId>hibernate-jpa-2.0-api</artifactId>

        <version>1.0.1.Final</version>

    </dependency>

    <dependency>

        <groupId>org.jboss.spec.javax.transaction</groupId>

        <artifactId>jboss-transaction-api_1.1_spec</artifactId>

        <version>1.0.0.Final</version>

        <scope>provided</scope>

    </dependency>



    <!-- JBoss Transactions dependency -->

    <dependency>

        <groupId>org.jboss.jbossts</groupId>

        <artifactId>jbossjta</artifactId>

        <version>4.16.4.Final</version>

    </dependency>

</dependencies>

Next we need to define the persistence unit. Create a META-INF/persistence.xml file.

<?xml version="1.0"?>

<persistence xmlns="http://java.sun.com/xml/ns/persistence"

             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"

             version="2.0">



    <persistence-unit name="ogm-jpa-tutorial" transaction-type="JTA">

        <!-- Use Hibernate OGM provider: configuration will be transparent -->

        <provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>

        <properties>

            <!-- property optional if you plan and use Infinispan, otherwise adjust to your favorite

                NoSQL Datastore provider.

            <property name="hibernate.ogm.datastore.provider"

                      value="org.hibernate.ogm.datastore.infinispan.impl.InfinispanDatastoreProvider"/>

            -->

            <!-- defines which JTA Transaction we plan to use -->

            <property name="hibernate.transaction.jta.platform"

                      value="org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform"/>

        </properties>

    </persistence-unit>

</persistence>

Let’s now persist a set of entities and retrieve them.

//accessing JBoss's Transaction can be done differently but this one works nicely

TransactionManager tm = getTransactionManager();


//build the EntityManagerFactory as you would build in in Hibernate ORM

EntityManagerFactory emf = Persistence.createEntityManagerFactory(

    "ogm-jpa-tutorial");


final Logger logger = LoggerFactory.getLogger(DogBreedRunner.class);


[..]


//Persist entities the way you are used to in plain JPA

tm.begin();

logger.infof("About to store dog and breed");

EntityManager em = emf.createEntityManager();

Breed collie = new Breed();

collie.setName("Collie");

em.persist(collie);

Dog dina = new Dog();

dina.setName("Dina");

dina.setBreed(collie);

em.persist(dina);

Long dinaId = dina.getId();

em.flush();

em.close();

tm.commit();


[..]


//Retrieve your entities the way you are used to in plain JPA

tm.begin();

logger.infof("About to retrieve dog and breed");

em = emf.createEntityManager();

dina = em.find(Dog.class, dinaId);

logger.infof("Found dog %s of breed %s", dina.getName(), dina.getBreed().getName());

em.flush();

em.close();

tm.commit();


[..]


emf.close();


public static TransactionManager getTransactionManager() throws Exception

    Class<?> tmClass = Main.class.getClassLoader().loadClass(JBOSS_TM_CLASS_NAME);

    return (TransactionManager) tmClass.getMethod("transactionManager").invoke(null);

}

A working example can be found in Hibernate OGM’s distribution under hibernate-ogm-documentation/examples/gettingstarted.

What have we seen?

Let’s explore more in the next chapters.

In this chapter we will will explore:

Let’s start with the general architecture.

3.1. General architecture

Hibernate OGM is really made possible by the reuse of a few key components:

• Hibernate ORM for JPA support
• Hibernate Search for indexing and query purposes
• the NoSQL drivers to interact with the underlying datastore
• Infinispan’s Lucene Directory to store indexes in Infinispan itself, or in many other NoSQL using Infinispan’s write-through cachestores
• Hibernate OGM itself

Figure 3.1. General architecture

Hibernate OGM reuses as much as possible from the Hibernate ORM infrastructure. There is no need to rewrite an entirely new JPA engine. The Persisters and the Loaders (two interfaces used by Hibernate ORM) have been rewritten to persist data in the NoSQL store. These implementations are the core of Hibernate OGM. We will see in Section 3.2, “How is data persisted” how the data is structured.

The particularities between NoSQL stores are abstracted by the notion of a DatastoreProvider and a GridDialect.

• DatastoreProvider abstracts how to start and maintain a connection between Hibernate OGM and the datastore.
• GridDialect abstracts how data itself including association is persisted.

Think of them as the JDBC layer for our NoSQL stores.

Other than these, all the Create/Read/Update/Delete (CRUD) operations are implemented by the Hibernate ORM engine (object hydration and dehydration, cascading, lifecycle etc).

As of today, we have implemented four datastore providers:

• a Map based datastore provider (for testing)
• an Infinispan based datastore provider to persist your entities in Infinispan
• a Ehcache based datastore provider to persist your entities in Ehcache
• a MongoDB based datastore provider to persist data in a MongoDB database

To implement JP-QL queries, Hibernate OGM parses the JP-QL string and calls the appropriate translator functions to build a native query. If the query is too complex for the native capabilities of the NoSQL store, the Teiid query engine is used as an intermediary engine to implement the missing features (typically joins between entities, aggregation). Finally, if the underlying engine does not have any query support, we use Hibernate Search as an external query engine.

Reality is a bit more nuanced, we will discuss the subject of querying in more details in Section 3.3, “How is data queried”.

Hibernate OGM best works in a JTA environment. The easiest solution is to deploy it on a Java EE container. Alternatively, you can use a standalone JTA TransactionManager. We explain how to in Section 4.2.2, “In a standalone JTA environment”.

Let’s now see how and in which structure data is persisted in the NoSQL data store.

3.2. How is data persisted

Hibernate OGM tries to reuse as much as possible the relational model concepts, at least when they are practical and make sense in OGM’s case. For very good reasons, the relational model brought peace in the database landscape over 30 years ago. In particular, Hibernate OGM inherits the following traits:

• abstraction between the application object model and the persistent data model
• persist data as basic types
• keep the notion of primary key to address an entity
• keep the notion of foreign key to link two entities (not enforced)

If the application data model is too tightly coupled with your persistent data model, a few issues arise including:

• any change in the application object hierarchy / composition must be reflected in the persistent data
• any change in the application object model will require a migration at the data level
• any access to the data by another application ties both applications losing flexibility
• any access to the data from another platform become somewhat more challenging
• serializing entities leads to many additional problems (see note below)

Why aren’t entities serialized in the key/value entry

There are a couple of reasons why serializing the entity directly in the datastore can lead to problems:

• When entities are pointing to other entities are you storing the whole graph? Hint: this can be quite big!
• If doing so, how do you guarantee object identity or even consistency amongst duplicated objects? It might make sense to store the same object graph from different root objects.
• What happens in case of class schema change? If you add or remove a property or include a superclass, you must migrate all entities in your datastore to avoid deserialization issues.

Entities are stored as tuples of values by Hibernate OGM. More specifically, each entity is conceptually represented by a Map<String,Object> where the key represents the column name (often the property name but not always) and the value represents the column value as a basic type. We favor basic types over complex ones to increase portability (across platforms and across type / class schema evolution over time). For example a URL object is stored as its String representation.

The key identifying a given entity instance is composed of:

• the table name
• the primary key column name(s)
• the primary key column value(s)

Figure 3.2. Storing entities

The GridDialect specific to the NoSQL datastore you target is then responsible to convert this map into the most natural model:

• for a key/value store or a data grid, we use the logical key as the key in the grid and we store the map as the value. Note that it’s an approximation and some key/value providers will use more tailored approaches.
• for a document oriented store, the map is represented by a document and each entry in the map corresponds to a property in a document.

Associations are also stored as tuple as well or more specifically as a set of tuples. Hibernate OGM stores the information necessary to navigate from an entity to its associations. This is a departure from the pure relational model but it ensures that association data is reachable via key lookups based on the information contained in the entity tuple we want to navigate from. Note that this leads to some level of duplication as information has to be stored for both sides of the association.

The key in which association data are stored is composed of:

• the table name
• the column name(s) representing the foreign key to the entity we come from
• the column value(s) representing the foreign key to the entity we come from

Using this approach, we favor fast read and (slightly) slower writes.

Figure 3.3. Storing associations

Note that this approach has benefits and drawbacks:

• it ensures that all CRUD operations are doable via key lookups
• it favors reads over writes (for associations)
• but it duplicates data

Note

We might offer alternative association data persistence options in the future based on feedback.

Again, there are specificities in how data is inherently stored in the specific NoSQL store. For example, in document oriented stores, the association information including the identifier to the associated entities can be stored in the entity owning the association. This is a more natural model for documents.

TODO: this sentence might be worth a diagram to show the difference with the key/value store.

Some identifiers require to store a seed in the datastore (like sequences for examples). The seed is stored in the value whose key is composed of:

• the table name
• the column name representing the segment
• the column value representing the segment

Make sure to check the chapter dedicated to the NoSQL store you target to find the specificities.

Many NoSQL stores have no notion of schema. Likewise, the tuple stored by Hibernate OGM is not tied to a particular schema: the tuple is represented by a Map, not a typed Map specific to a given entity type. Nevertheless, JPA does describe a schema thanks to:

• the class schema
• the JPA physical annotations like @Table and @Column.

While tied to the application, it offers some robustness and explicit understanding when the schema is changed as the schema is right in front of the developers' eyes. This is an intermediary model between the strictly typed relational model and the totally schema-less approach pushed by some NoSQL families.

3.3. How is data queried

Note

Query support is in active development. This section describes where the project is going.

Since Hibernate OGM wants to offer all of JPA, it needs to support JP-QL queries. Hibernate OGM parses the JP-QL query string and extracts its meaning. From there, several options are available depending of the capabilities of the NoSQL store you target:

• it directly delegates the native query generation to the datastore specific query translator implementation
• it uses Teiid as an intermediary engine, Teiid delegating parts of the query to the datastore specific query translator implementation
• it uses Hibernate Search as a query engine to execute the query

If the NoSQL datastore has some query capabilities and if the JP-QL query is simple enough to be executed by the datastore, then the JP-QL parser directly pushes the query generation to the NoSQL specific query translator. The query returns the list of matching identifiers snd uses Hibernate OGM to return managed objects.

Some of the JP-QL features are not supported by NoSQL solutions. Two typical examples are joins between entities - which you should limit anyways in a NoSQL environment - and aggregations like average, max, min etc. When the NoSQL store does not support the query, we use Teiid - a database federation engine - to build simpler queries executed to the datastore and perform the join or aggregation operations in Teiid itself.

Finally some NoSQL stores have poor query support, or none at all. In this case Hibernate OGM can use Hibernate Search as its indexing and query engine. Hibernate Search is able to index and query objects - entities - and run full-text queries. It uses the well known Apache Lucene to do that but adds a few interesting characteristics like clustering support and an object oriented abstraction including an object oriented query DSL. Let’s have a look at the architecture of Hibernate OGM when using Hibernate Search:

Figure 3.4. Using Hibernate Search as query engine - greyed areas are blocks already present in Hibernate OGM’s architecture

In this situation, Hibernate ORM Core pushes change events to Hibernate Search which will index entities accordingly and keep the index and the datastore in sync. The JP-QL query parser delegates the query translation to the Hibernate Search query translator and executes the query on top of the Lucene indexes. Indexes can be stored in various fashions:

• on a file system (the default in Lucene)
• in Infinispan via the Infinispan Lucene directory implementation: the index is then distributed across several servers transparently
• in NoSQL stores like Voldemort that can natively store Lucene indexes
• in NoSQL stores that can be used as overflow to Infinispan: in this case Infinispan is used as an intermediary layer to serve the index efficiently but persists the index in another NoSQL store.

Note that for complex queries involving joins or aggregation, Hibernate OGM can use Teiid as an intermediary query engine that will delegate to Hibernate Search.

Note that you can use Hibernate Search even if you do plan to use the NoSQL datastore query capabilities. Hibernate Search offers a few interesting options:

• clusterability
• full-text queries - ie Google for your entities
• geospatial queries
• query faceting (ie dynamic categorization of the query results by price, brand etc)

What’s the progress status on queries?

Well… now is a good time to remind you that Hibernate OGM is open source and that contributing to such cutting edge project is a lot of fun. Check out Chapter 1, How to get help and contribute on Hibernate OGM for more details.

But to answer your question, we have finished the skeleton of the architecture as well as the JP-QL parser implementation. The Hibernate Search query translator can execute simple queries already. However, we do not yet have a NoSQL specific query translator but the approach is quite clear to us. Teiid for complex queries is also not integrated but work is being done to facilitate that integration soon. Native Hibernate Search queries are fully supported.

Hibernate OGM favors ease of use and convention over configuration. This makes its configuration quite simple by default.

<?xml version="1.0"?>

<persistence xmlns="http://java.sun.com/xml/ns/persistence"

             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"

             version="2.0">



    <persistence-unit name="org.hibernate.ogm.tutorial.jpa" transaction-type="JTA">

        <!-- Use Hibernate OGM provider: configuration will be transparent -->

        <provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>

        <properties>

            <property name="hibernate.transaction.jta.platform"

                      value="org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform" />

            <property name="hibernate.ogm.datastore.provider"

                      value="infinispan" />

        </properties>

    </persistence-unit>

</persistence>

Configuration cfg = new OgmConfiguration();


//assuming you are using JTA in a non contained environment

cfg.setProperty(environment.TRANSACTION_STRATEGY,

                 "org.hibernate.transaction.JTATransactionFactory");

//assuming JBoss TransactionManager in standalone mode

cfg.setProperty(Environment.JTA_PLATFORM,

     "org.hibernate.service.jta.platform.internal.JBossStandAloneJtaPlatform");


//assuming the default infinispan settings

cfg.setProperty("hibernate.ogm.datastore.provider",

                "infinispan");


//add your annotated classes

cfg.addAnnotatedClass(Order.class)

   .addAnnotatedClass(Item.class)


//build the SessionFactory

SessionFactory sf = cfg.buildSessionFactory();

<?xml version="1.0"?>

<persistence xmlns="http://java.sun.com/xml/ns/persistence"

             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"

             version="2.0">



    <persistence-unit name="org.hibernate.ogm.tutorial.jpa" transaction-type="JTA">

        <!-- Use Hibernate OGM provider: configuration will be transparent -->

        <provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>

        <jta-data-source>java:/DefaultDS</jta-data-source>

        <properties>

            <property name="hibernate.transaction.jta.platform"

                      value="org.hibernate.service.jta.platform.internal.JBossAppServerJtaPlatform" />

            <property name="hibernate.ogm.datastore.provider"

                      value="infinispan" />

        </properties>

    </persistence-unit>

</persistence>

<dependency>

    <groupId>org.jboss.jbossts</groupId>

    <artifactId>jbossjta</artifactId>

    <version>4.16.4.Final</version>

</dependency>

TransactionManager transactionManager =

   com.arjuna.ats.jta.TransactionManager.transactionmanager();

//note that you must start the transaction before creating the EntityManager

//or else call entityManager.joinTransaction()

transactionManager.begin();


final EntityManager em = emf.createEntityManager();


Poem poem = new Poem();

poem.setName("L'albatros");

em.persist(poem);


transactionManager.commit();


em.clear();


transactionManager.begin();


poem = em.find(Poem.class, poem.getId());

assertThat(poem).isNotNull();

assertThat(poem.getName()).isEqualTo("L'albatros");

em.remove(poem );


transactionManager.commit();


em.close();

Dependencies: org.hibernate:ogm services

<jboss-deployment-structure>

    <deployment>

        <dependencies>

            <module name="org.hibernate" slot="ogm" services="export" />

        </dependencies>

    </deployment>

</jboss-deployment-structure>

Currently Hibernate OGM supports the following datastores:

More are planned, if you are interested, come talk to us (see Chapter 1, How to get help and contribute on Hibernate OGM).

Hibernate OGM interacts with NoSQL datastores via two contracts:

The main thing you need to do is to configure which datastore provider you want to use. This is done via the hibernate.ogm.datastore.provider option. Possible values are the fully qualified class name of a DatastoreProvider implementation or one preferably of the following shortcuts:

You also need to add the relevant Hibernate OGM module in your classpath. In maven that would look like:

<dependency>

    <groupId>org.hibernate.ogm</groupId>

    <artifactId>hibernate-ogm-infinispan</artifactId>

    <version>4.0.0.Beta4</version>

</dependency>

We have respectively hibernate-ogm-infinispan, hibernate-ogm-ehcache, hibernate-ogm-mongodb and hibernate-ogm-neo4j. The map datastore is included in the Hibernate OGM engine module.

By default, a datastore provider chooses the best grid dialect transparently but you can manually override that setting with the hibernate.ogm.datastore.grid_dialect option. Use the fully qualified class name of the GridDialect implementation. Most users should ignore this setting entirely and live happy.

<dependency>

    <groupId>org.hibernate.ogm</groupId>

    <artifactId>hibernate-ogm-infinispan</artifactId>

    <version>4.0.0.Beta4</version>

</dependency>

<?xml version="1.0" encoding="UTF-8"?>

<infinispan

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="urn:infinispan:config:5.1 http://www.infinispan.org/schemas/infinispan-config-5.1.xsd"

    xmlns="urn:infinispan:config:5.1">



    <global>

    </global>



    <default>

    </default>



    <namedCache name="ENTITIES">

    </namedCache>



    <namedCache name="ASSOCIATIONS">

    </namedCache>



    <namedCache name="IDENTIFIERS">

    </namedCache>



</infinispan>

<namedCache name="ENTITIES">

  <eviction strategy="LIRS" maxEntries="2000" />

  <loaders

    passivation="true" shared="false">

    <loader

      class="org.infinispan.loaders.file.FileCacheStore"

      fetchPersistentState="false"

      purgeOnStartup="false">

      <properties>

        <property name="location" value="/var/hibernate-ogm/myapp/entities-data" />

      </properties>

    </loader>

  </loaders>

</namedCache>

#192.168.122.1 is an example IPv4 address
-Djava.net.preferIPv4Stack=true -Djgroups.bind_addr=192.168.122.1

<?xml version="1.0" encoding="UTF-8"?>

<infinispan

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="urn:infinispan:config:5.1 http://www.infinispan.org/schemas/infinispan-config-5.1.xsd"

    xmlns="urn:infinispan:config:5.1">



    <global>

        <transport

            clusterName="HibernateOGM-Infinispan-cluster">

            <properties>

                <property name="configurationFile" value="my-jgroups-conf.xml" />

            </properties>

        </transport>

    </global>



    <default>

        <clustering

            mode="distribution" />

    </default>



    <!-- Cache to store the OGM entities -->

    <namedCache

        name="ENTITIES">

    </namedCache>



    <!-- Cache to store the relations across entities -->

    <namedCache

        name="ASSOCIATIONS">

    </namedCache>



    <!-- Cache to store identifiers -->

    <namedCache

        name="IDENTIFIERS">

        <!-- Override the cache mode: -->

        <clustering

            mode="replication" />

    </namedCache>



</infinispan>

<default>

   <transaction

      transactionMode="TRANSACTIONAL"

      transactionManagerLookupClass=

    "org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup" />

</default>

<dependency>

    <groupId>org.hibernate.ogm</groupId>

    <artifactId>hibernate-ogm-ehcache</artifactId>

    <version>4.0.0.Beta4</version>

</dependency>

@Entity

public class News {

    @Id

    private String id;

    private String title;

    @Column(name="desc")

    private String description;

    @Embedded

    private NewsPaper paper;


    //getters, setters ...

}


@Embeddable

public class NewsPaper {

    private String name;

    private String owner;

    //getters, setters ...

}

{
    "_id" : "1234-5678-0123-4567",
    "title": "On the merits of NoSQL",
    "desc": "This paper discuss why NoSQL will save the world for good",
    "paper": {
        "name": "NoSQL journal of prophecies",
        "owner": "Delphy"
    }
}

@Entity

public class News {

    @EmbeddedId

    private NewsID newsId;

    //getters, setters ...

}


@Embeddable

public class NewsID implements Serializable {

    private String title;

    private String author;

    //getters, setters ...

}

{
    "_id" :{
        "title": "How does Hibernate OGM MongoDB work?",
        "author": "Guillaume"
    }
}

@Entity

public class AccountOwner {

@Id

private String id;


@ManyToMany

public Set<BankAccount> bankAccounts;


//getters, setters, ...

{
    "_id" : "owner0001",
    "bankAccounts" : [
        { "bankAccounts_id" : "accountXYZ" }
    ]
}

{
    "_id": {
        "owners_id": "owner0001",
        "table": "AccountOwner_BankAccount"
    },
    "rows": [
        { "bankAccounts_id": "accountXYZ" }
    ]
}

{
    "_id": {
        "owners_id": "owner0001",
        "table": "AccountOwner_BankAccount"
    },
    "rows": [{
        "bankAccounts_id": "accountXYZ"
        }]
}
{
    "_id": {
        "bankAccounts_id": "accountXYZ",
        "table": "AccountOwner_BankAccount"
    },
    "rows": [{
        "owners_id": "owner0001"
    }]
}

{
    "_id" : { "owners_id" : "owner0001" },
    "rows" : [
        { "bankAccounts_id" : "accountXYZ" }
    ]
}

{
    "_id" : { "owners_id" : "owner0001" },
    "rows" : [
        { "bankAccounts_id" : "accountXYZ" }
    ]
}
{
    "_id" : { "bankAccounts_id" : "accountXYZ" },
    "rows" : [
        { "owners_id" : "owner0001" }
    ]
}

<dependency>

    <groupId>org.hibernate.ogm</groupId>

    <artifactId>hibernate-ogm-neo4j</artifactId>

    <version>4.0.0.Beta4</version>

</dependency>

hibernate.ogm.datastore.provider = neo4j_embedded
hibernate.ogm.neo4j.database.path = C:\example\mydb

@Entity

class Account {


    @Id

    String login;

    String password;

    Address homeAddress;


    //...

}


@Embeddable

class Address {

    String city;

    String zipCode;


  //...

}

Node properties:
   _table
   id
   login
   password
   homeAddress_city
   homeAddress_zipCode

Session session = factory.openSession();

Transaction tx = session.beginTransaction();


Account account = new Account();

account.setLogin( "myAccount" );

session.persist( account );


tx.commit();


...


tx = session.beginTransaction();

Account savedAccount =  (Account) session.get( Account.class, account.getId() );

tx.commit();

TODO:

@Entity

public class Breed {


    @Id @GeneratedValue(generator = "uuid")

    @GenericGenerator(name="uuid", strategy="uuid2")

    public String getId() { return id; }

    public void setId(String id) { this.id = id; }

    private String id;


    public String getName() { return name; }

    public void setName(String name) { this.name = name; }

    private String name;

}

To query a NoSQL database is a complex feat, especially as not all NoSQL solutions support all forms of query. One of the goals of Hibernate OGM is to deal with this complexity so that users don’t have to. However, that’s not yet all implemented and depending on your use case there might be better approaches you can take advantage of.

If you skipped to this section without reading Chapter 3, Architecture, I’d suggest to read at least Section 3.3, “How is data queried” as it will greatly help you choosing a query approach.

Query query = session

    .createQuery("from Hypothesis h where h.description = :desc")

    .setString("desc", "tomorrow it's going to rain");

@Entity @Indexed

public class Hypothesis {


    @Id

    public String getId() { return id; }

    public void setId(String id) { this.id = id; }

    private String id;


    @Field(analyze=Analyze.NO)

    public String getDescription() { return description; }

    public void setDescription(String description) { this.description = description; }

    private String description;

}

EntityManager entityManager = ...

//Add full-text superpowers to any EntityManager:

FullTextEntityManager ftem = Search.getFullTextEntityManager(entityManager);


//Optionally use the QueryBuilder to simplify Query definition:

QueryBuilder b = ftem.getSearchFactory()

   .buildQueryBuilder()

   .forEntity(Hypothesis.class)

   .get();


//Create a Lucene Query:

Query lq = b.keyword().onField("description").matching("tomorrow").createQuery();


//Transform the Lucene Query in a JPA Query:

FullTextQuery ftQuery = ftem.createFullTextQuery(lq, Hypothesis.class);

//This is a requirement when using Hibernate OGM instead of ORM:

ftQuery.initializeObjectsWith(ObjectLookupMethod.SKIP,

      DatabaseRetrievalMethod.FIND_BY_ID);


//List all matching Hypothesis:

List<Hypothesis> resultList = ftQuery.getResultList();

@Entity @Indexed

public class Hypothesis {


    @Id

    public String getId() { return id; }

    public void setId(String id) { this.id = id; }

    private String id;


    @Field(analyze=Analyze.YES)

    public String getDescription() { return description; }

    public void setDescription(String description) { this.description = description; }

    private String description;

}