Introduction

Neo4j a Graph database that fits nicely in a Grails application.

The goal of GORM for Neo4j is to provide a as-complete-as-possible GORM implementation that maps domain classes and instances to the Neo4j nodespace. The following features are supported:

  • Marshalling from Neo4j Nodes to Groovy types and back again

  • Support for GORM dynamic finders, criteria and named queries

  • Session-managed transactions

  • access to Neo4j’s traversal capabilities

  • Access the Neo4j graph database via the Bolt Java Driver

  • Neo4j autoindexing

Compatibility with GORM for Hibernate

This implementation tries to be as compatible as possible with GORM for Hibernate. In general you can refer to the GORM for Hibernate documentation as the majority of features are implemented across both.

The following key features are supported by GORM for Neo4j:

  • Simple persistence methods (save,delete etc)

  • Dynamic finders

  • Criteria queries

  • Named queries

  • Inheritance

  • Embedded types

  • Query by example

  • Many-to-many associations (these can be modelled with a mapping class)

However, some features are not supported:

  • HQL queries (however Cypher Queries are)

  • Composite primary keys

  • Any direct interaction with the Hibernate API

  • Custom Hibernate user types

There may be other limitations not mentioned here so in general it shouldn’t be expected that an application based on GORM for Hibernate will "just work" without some tweaking involved. Having said that, the large majority of common GORM functionality is supported.

Release History

6.0.x

  • Support for Neo4j 3.0.x or above

  • Rewritten for Neo4j Bolt Java Driver

  • Support for Multiple Data Sources (Connections)

  • Multi Tenancy support for DATABASE and DISCRIMINATOR approaches

  • Refactored Bootstrapping

  • Uses new DynamicAttributes trait

5.0.x

The following new features are available in this release.

  • Support for Neo4j 2.3.x or above

  • Ability to query using Cypher with the default GORM methods (find, findAll)

  • Robust Spring Transaction Management

  • Support for Lazy & Eager Loading using OPTIONAL MATCH

  • Improved Performance

  • Dirty Checking Implementation

If you are using an older version of the plugin, and looking to upgrade the following changes may impact you:

  • Neo4j JDBC is no longer used and the corresponding CypherEngine interface was removed

  • Dynamic associations are disabled by default, you can re-enable them in your entity mapping

4.0.x

  • Rewritten for Groovy traits & Grails 3

3.0.x

  • Initial support for Neo4j 2.0.x

  • Support for Cypher via Neo4j JDBC

2.0.x

  • Refinements from 1.0.x

1.0.x

  • works with Neo4j HA

  • implementing new GORM property criteria filters

  • uses Neo4j 1.8.2

  • first GORM compliant version of the plugin

  • works with embedded and REST Neo4j databases

  • exposing traversal options to domain classes

Upgrading from previous versions

If you are upgrading from a previous version of the plugin to the 6.0.13.RELEASE, you will need to take into account the following changes.

Configuration Changes

Since the plugin now uses the Neo4j Bolt driver the configuration has been altered.

The grails.neo4j.options setting no longer configures the Neo4j embedded options, but instead configures the Bolt driver options.

If you want to continue to configure Neo4j in embedded mode you must use grails.neo4j.embedded.options.

Bolt Java Driver and API Changes

The API has changed to accommodate the Neo4j Bolt driver and all references to the Neo4j server itself have been removed.

Therefore you need to replace the usages of the following interfaces with their bolt equivalents:

Neo4j Class Bolt Driver Replacement

org.neo4j.graphdb.GraphDatabaseService

org.neo4j.driver.v1.Driver

org.neo4j.graphdb.Transaction

org.neo4j.driver.v1.Transaction

org.neo4j.graphdb.Node

org.neo4j.driver.v1.types.Node

org.neo4j.graphdb.Relationship

org.neo4j.driver.v1.types.Relationship

org.neo4j.graphdb.Result

org.neo4j.driver.v1.StatementResult

There may be other classes that you need to replace references too. Generally the org.neo4j.graphdb package is considered the server-side API and only the org.neo4j.driver.v1 package should be used in applications.

General Neo4j 3.x Changes

Since GORM for Neo4j 6.0.13.RELEASE is based on Neo4j 3.x, if you are upgrading from Neo4j 2.x there will be other changes related to Neo4j 3 that you may need to make. These are described in the upgrade guide on the Neo4j website.

Getting Started

To get started with GORM for Neo4j you need to install the plugin into a Grails application.

For Grails 3.x you need to edit your build.gradle file and add the plugin as a dependency:

dependencies {
	compile 'org.grails.plugins:neo4j:6.0.13'
}
GORM for Neo4j requires Grails 2.5.x or above and Neo4j 3.0.x or above, if you wish to use Neo4j 2.3.x use the 5.x version of GORM

To configure the plugin for Grails 2.x edit the grails-app/conf/BuildConfig.groovy file and add the following plugin definitions:

plugins {
    compile ':neo4j:6.0.13'
    build ':tomcat:8.22'
}
Grails 2.5.x must be configured with Tomcat 8 when using Neo4j in embedded mode, since the Neo4j server depends newer versions of the Servlet API and will not work with Tomcat 7.

By default the Grails plugin assumes you have a Neo4j instance running on port 7687, however you can run Neo4j embedded by including the following configuration in grails-app/conf/application.yml:

grails:
    neo4j:
        type: embedded

And then adding the Neo4j test harness to your provided dependencies:

provided 'org.neo4j.test:neo4j-harness:3.0.2'
The Neo4j server uses Jetty, so when you add Neo4j as embedded Grails will also use Jetty (not Tomcat) as the container since it discovered on the classpath, therefore it is not recommended to use Neo4j embedded.

To configure the Neo4j server URL you can use the grails.neo4j.url setting in grails-app/conf/application.yml:

grails:
    neo4j:
        url: bolt://localhost:7687

Neo4j Bolt Driver Configuration Options

The following options can be configured in grails-app/conf/application.yml:

  • grails.neo4j.url - The Neo4j Bolt URL

  • grails.neo4j.buildIndex - Whether to build the Neo4j index on startup (defaults to true)

  • grails.neo4j.type - The Neo4j server type. If set to embedded loads an embedded server

  • grails.neo4j.flush.mode - The flush mode to use when working with Neo4j sessions. Default to AUTO.

  • grails.neo4j.username - The username to use to authenticate

  • grails.neo4j.password - The password to use to authenticate

  • grails.neo4j.default.mapping - The default database mapping. Must be a closure configured in application.groovy

  • grails.neo4j.options - Any options to be passed to the driver

The grails.neo4j.options setting allows you to configure the properties of org.neo4j.driver.v1.Config, for example:

grails:
    neo4j:
        options:
            maxSessions: 100
            encryptionLevel: NONE
            sessionLivenessCheckTimeout: 200

Using Neo4j Standalone

If you plan to use Neo4j as your primary datastore then you need to remove the Hibernate plugin by editing your BuildConfig or build.gradle (dependending on the version of Grails) and removing the Hibernate plugin definition

With this done all domain classes in grails-app/domain will be persisted via Neo4j and not Hibernate. You can create a domain class by running the regular create-domain-class command:

grails create-domain-class Person

The Person domain class will automatically be a persistent entity that can be stored in Neo4j.

Combining Neo4j And Hibernate

If you have both the Hibernate and Neo4j plugins installed then by default all classes in the grails-app/domain directory will be persisted by Hibernate and not Neo4j. If you want to persist a particular domain class with Neo4j then you must use the mapWith property in the domain class:

static mapWith = "neo4j"

Using GORM in Spring Boot

To use GORM for Neo4j in Spring Boot add the necessary dependencies to your Boot application:

compile("org.grails:gorm-neo4j-spring-boot:6.0.13.RELEASE")

Ensure your Boot Application class is annotated with ComponentScan, example:

import org.springframework.boot.SpringApplication
import org.springframework.boot.autoconfigure.EnableAutoConfiguration
import org.springframework.context.annotation.*

@Configuration
@EnableAutoConfiguration
@ComponentScan
class Application {
    static void main(String[] args) {
        SpringApplication.run Application, args
    }
}
Using ComponentScan without a value results in Boot scanning for classes in the same package or any package nested within the Application class package. If your GORM entities are in a different package specify the package name as the value of the ComponentScan annotation.

Finally create your GORM entities and ensure they are annotated with grails.persistence.Entity:

import grails.persistence.*

@Entity
class Person {
    String firstName
    String lastName
}

To configure GORM for Neo4j within Spring Boot create an application.yml file and populate your configuration options within it.

GORM for Neo4j without Grails

If you wish to use GORM for Neo4j outside of a Grails application you should declare the necessary dependencies, for example in Gradle:

compile "org.grails:grails-datastore-gorm-neo4j:6.0.13.RELEASE"

Then annotate your entities with the grails.gorm.annotation.Entity annotation and implement the Neo4jEntity trait:

import grails.neo4j.*
import grails.gorm.annotation.*

@Entity
class Person implements Neo4jEntity<Person>{
    String name
}

Then you need to place the bootstrap logic somewhere in your application which uses Neo4jDatastore:

def datastore = new Neo4jDatastore(Person)

println Person.count()

For configuration you can either pass a map or an instance of the org.springframework.core.env.PropertyResolver interface:

def datastore = new Neo4jDatastore(['grails.neo4j.url':'bolt://...'], Person)

println Person.count()

If you are using Spring with an existing ApplicationContext you can instead call use Neo4jDataStoreSpringInitializer and call configureForBeanDefinitionRegistry prior to refreshing the context. You can pass the Spring Environment object to the constructor for configuration:

ApplicationContext myApplicationContext = ...
def initializer = new Neo4jDataStoreSpringInitializer(myApplicationContext.getEnvironment(), Person)
initializer.configureForBeanDefinitionRegistry(myApplicationContext)

println Person.count()

Mapping Domain Classes to Neo4j Nodes

GORM for Neo4j will map each Grails domain instance to a Node in the node space. For example given the following domain class:

class Pet {
    String name
}

Each domain class will implement the Neo4jEntity trait. You can define this explicitly if you prefer:

class Pet implements Neo4jEntity<Pet> {
    String name
}

When an instance of Pet is saved:

def p = new Pet(name:"Dino")
p.save(flush:true)

Then the following Cypher CREATE is issued:

CREATE (n2:Pet {props})

The properties of the class are converted to native Neo4j types and set as the props parameter to the query.

If you want to see what queries GORM for Neo4j generates, enabling logging for the org.grails.datastore.gorm.neo4j package

Neo4j ID generators

GORM by default uses a custom identity generator based on the Snowflake algorithm and stores the generated identifier in a property of each Neo4j node called __id__.

This has the advantage of enabling GORM to batch insert operations into a single CREATE cypher statement, hence why it is the default.

However, if you prefer to use native Neo4j node identifiers then you can do so by changing the generator used in the mapping:

class Club {

    ...
    static mapping = {
        id generator:'native'
    }

}

This will instead use the Neo4j node identifier as the object identifier with the downside being that GORM has to execute individual CREATE statements for each new object saved, similar to the way GORM for Hibernate has to perform a SQL INSERT if the id generation strategy is an auto-increment column.

This disadvantage can be worked around by using the saveAll method to save multiple domain classes at once:

Club.saveAll([
    new Club(name:"Manchester United"),
    new Club(name:"Arsenal")
])

If you wish to globally change id generation then you can do so in grails-app/conf/application.groovy (Config.groovy in Grails 2.x):

grails.neo4j.default.mapping = {
    id generator:'native'
}

In addition, if you wish to use a custom identity generation strategy you can do so by specifying a class name that implements the IdGenerator interface:

grails.neo4j.default.mapping = {
    id generator:'com.foo.MyIdGenerator'
}

Understanding Association Mapping

GORM for Neo4j will create Neo4j relationships between nodes for you based on the relationship ownership rules defined in your GORM mapping. For example the following mapping:

class Owner {
    String name
    static hasMany = [pets:Pet]
}
class Pet {
    String name
    static belongsTo = [owner:Owner]
}

Will generate a Cypher relationship creation query as follows:

MATCH (from:Owner {__id__:{start}}), (to:Pet) WHERE to.__id__ IN {end} CREATE (from)-[r:PETS]->(to)

As you can see from the query the relationship is defined as (from)-[r:PETS]->(to), with the direction of the association defined by who "owns" the association. Since Pet defines a belongTo association to Owner, this means that Owner owns the association and the relationship is from Owner to Pet.

You can customize the Neo4j relationship type and direction using the mapping block if necessary:

import static grails.neo4j.Direction.*

class Owner {
    String name
    static hasMany = [pets:Pet]

    static mapping = {
         pets type:"PETZ", direction:BOTH
    }
}

In this case a bidirectional relationship will be created in the graph such as (from)<-[r:PETZ]->(to).

For more information on defining relationships with GORM, see the corresponding guide in the GORM documentation.

Customizing the Label Strategy

The default strategy for defining labels is to use the class name, however the strategy to define labels for a given node is completely configurable. For example you can use static mapping to define you labels:

class Person {
    static mapping = {
        labels "Person", "People"
    }
}

You can also define labels dynamically. For example:

class Person {
    static mapping = {
        labels { GraphPersistentEntity pe -> "`${pe.javaClass.name}`" }
    }
}

Or mix static and dynamic labels:

static mapping = {
    labels "People", { GraphPersistentEntity pe -> "`${pe.javaClass.name}`" }
}

At a small read/write performance cost you can define dynamic labels based on an instance:

static mapping = {
    labels { GraphPersistentEntity pe, instance ->  // 2 arguments: instance dependent label
        "`${instance.profession}`"
    }
}

Dynamic Properties and Associations

Neo4j is a schemaless database. This means that, unlike SQL where you can only have a fixed number of rows and columns, nodes can have unlimited properties.

Most existing object mapping tools in statically typed languages don’t allow you to harness this power, but GORM for Neo4j allows you to define both statically defined properties (ie the properties of the domain class) and domain properties.

For example, take the following domain class:

class Plant {
    String name
 }

You can set both the statically defined name property, but also any arbitrary number of dynamic properties using the subscript operator in Groovy:

def p = new Plant(name:"Carrot")
  p['goesInPatch'] = true
  p.save(flush:true)

Any simple properties can be included, however if you wish to have dynamic associations you can as well by modifying the mapping:

class Plant {
    String name
    static mapping = {
        dynamicAssociations true
    }
 }

With this in place you can define dynamic associations:

def p = new Plant(name:"Carrot")
  p['related'] = [ new Plant(name:"Potato").save() ]
  p.save(flush:true)

The downside of dynamic associations is that GORM has to issue a separate query for each loaded instance when retrieving entities. If you have a small amount of data this is not a problem, but for larger data sets it is not recommended.

Querying with GORM for Neo4j

GORM for Neo4j supports all the different querying methods provided by GORM including:

However, HQL queries are not supported, instead you can use Cypher directly if you so choose.

If you want to see what queries GORM for Neo4j generates, enabling logging for the org.grails.datastore.gorm.neo4j package

Understanding Lazy Loading

When retrieving a GORM entity and its associations by default single-ended associations will only retrieve the association id, whilst associations to many objects will not retrieve the association at all until it is accessed. This is called lazy loading.

For example given the following domain model:

class League {
    String name
    static hasMany = [clubs:Club]
}
class Club {
    String name
    static belongsTo = [league:League]
    static hasMany = [teams: Team ]
}
class Team  {
    String name
    static belongsTo = [club:Club]
}

When you retrieve the Club by name:

def club = Club.findByName("Manchester United")

You will get the following Cypher query:

MATCH (n:Club) WHERE ( n.__id__={1} )
OPTIONAL MATCH(n)-[:LEAGUE]->(leagueNode)
RETURN n as data, collect(DISTINCT leagueNode.__id__) as leagueIds

As you can see the teams association is not loaded in the query, and only the ID of the league association is retrieved. If you then iterate over the teams you will get a second query to obtain the teams:

for(team in club.teams) {
    println team.name
}

The query generated will be:

MATCH (from:Club)<-[:CLUB]-(to:Team) WHERE from.__id__ = {id} RETURN to as data

If you wish to avoid this secondary query to retrieve the data you can do so using an eager query:

// using a dynamic finder
def club = Club.findByName("Manchester United", [fetch:[teams:'join']])

// using a where queries
def query = Club.where { name == "Manchester United" }
                .join('teams')
def club = query.find()

// using criteria
def query = Club.createCriteria()
def club = query.get {
    eq 'name', "Manchester United"
    join 'teams'
}

This will instead generate the following query:

MATCH (n:Club) WHERE ( n.name={1} )
OPTIONAL MATCH(n)<-[:CLUB]-(teamsNode)
OPTIONAL MATCH(n)-[:LEAGUE]->(leagueNode)
RETURN n as data, collect(DISTINCT leagueNode.__id__) as leagueIds, collect(DISTINCT teamsNode) as teamsNodes

As you can see the associated team nodes are loaded by the query. If you prefer this to happen for every query, then this can also be configured in the mapping:

class Club {
    ...

    static mapping = {
       teams fetch:"eager"
    }
}

You can also configure the collection ids to be eagerly loaded, but the instances themselves to be lazy loaded via proxies:

class Club {
    ...

    static mapping = {
       teams fetch:"eager", lazy:true
    }
}

Querying with Cypher

To query with raw Cypher queries you can use the built in find and findAll methods:

def club = Club.find("MATCH n where n.name = {1} RETURN n", 'FC Bayern Muenchen')
def clubs = Club.findAll("MATCH n where n.name = {1} RETURN n", 'FC Bayern Muenchen')

Note that the first returned item should be the node itself. To execute cypher queries and work with the raw results use cypherStatic:

StatementResult result = Club.cypherStatic("MATCH n where n.name = {1} RETURN n", ['FC Bayern Muenchen'])

When working with raw results, you can convert any org.neo4j.driver.v1.types.Node into a domain instance using the as keyword:

Node myNode = ...
 Club club = myNode as Club

You can also convert any org.neo4j.driver.v1.StatementResult instance to a list of domain classes:

StatementResult result = ...
List<Club> clubs = result.toList(Club)

Defining the Query Index

To define which properties of your domain class should be indexed for querying you can do so in the mapping:

class Club {
    String name

    ...
    static mapping = {
        name index:true
    }
}

On startup GORM will use Cypher to create indexes as follows:

CREATE INDEX ON :Club(name)

To define a unique index use unique instead:

class Club {
    String name

    ...
    static mapping = {
        name unique:true
    }
}

Multiple Data Sources

GORM for Neo4j supports the notion of multiple data sources where multiple individual Bolt Driver instances can be configured and switched between.

Configuring Multiple Bolt Drivers

To configure multiple Bolt Driver connections you need to use the grails.neo4j.connections setting. For example in application.yml:

grails-app/conf/application.yml
grails:
    neo4j:
        url: bolt://localhost:7687
        connections:
            moreBooks:
                url: bolt://localhost:7688
            evenMoreBooks:
                url: bolt://localhost:7689

You can configure individual settings for each Bolt driver. If a setting is not specified by default the setting is inherited from the default Neo4j driver.

Mapping Domain Classes to Bolt Drivers

If a domain class has no specified Neo4j driver connection configuration then the default is used.

You can set the connection method in the mapping block to configure an alternate Neo4j Driver.

For example, if you want to use the ZipCode domain to use a Neo4j Driver connection called 'lookup', configure it like this:

class ZipCode {

   String code

   static mapping = {
      connection 'lookup'
   }
}

A domain class can also use two or more configured Neo4j Driver connections by using the connections method with a list of names to configure more than one, for example:

class ZipCode {

   String code

   static mapping = {
      connections(['lookup', 'auditing'])
   }
}

If a domain class uses the default connection and one or more others, you can use the ConnectionSource.DEFAULT constant to indicate that:

import org.grails.datastore.mapping.core.connections.*

class ZipCode {

   String code

   static mapping = {
      connections(['lookup', ConnectionSource.DEFAULT])
   }
}

If a domain class uses all configured DataSource instances use the value ALL:

import org.grails.datastore.mapping.core.connections.*

class ZipCode {

   String code

   static mapping = {
      connection ConnectionSource.ALL
   }
}

Switching between Bolt Drivers

You can switch to a different connection at runtime with the withConnection method:

Book.withConnection("moreBooks") {
    Book.list()
}

Any logic executed within the body of the closure will use the alternate connection. Once the close finishes execution GORM will switch back to the default connection automatically.

Multi-Tenancy

GORM for Neo4j supports the following multi-tenancy modes:

  • DATABASE - A separate database with a separate connection pool is used to store each tenants data.

  • DISCRIMINATOR - The same database is used with a discriminator used to partition and isolate data.

Configuring Multi Tenancy

You can configure Multi-Tenancy the same way described in the GORM for Hibernate documenation, simply specify a multi tenancy mode and resolver:

grails:
    gorm:
        multiTenancy:
            mode: DATABASE
            tenantResolverClass: org.grails.datastore.mapping.multitenancy.web.SubDomainTenantResolver

Note that if you are using Neo4j and Hibernate together the above configuration will configure both Neo4j and Hibernate to use a multi-tenancy mode of DATABASE.

If you only want to enable multi-tenancy for Neo4j only you can use the following configuration instead:

grails:
    neo4j:
        multiTenancy:
            mode: DATABASE
            tenantResolverClass: org.grails.datastore.mapping.multitenancy.web.SubDomainTenantResolver

Multi Tenancy Modes

As mentioned previously, GORM for Neo4j supports the DATABASE and DISCRIMINATOR however there are some considerations to keep in mind.

Database Per Tenant

When using the DATABASE mode, only GORM methods calls are dispatched to the correct tenant. This means the following will use the tenant id:

// switches to the correct client based on the tenant id
Book.list()

However, going directly through the Driver will not work:

@Autowired Driver boltDriver

// uses the default connection and doesn't resolve the tenant it
boltDriver.session().run("..")

If you are working directly with the Driver instance you need to make sure you obtain the correct instance. For example:

import grails.gorm.multitenancy.*

@Autowired Neo4jDatastore neo4jDatastore
...
Driver boltDriver =
        neo4jDatastore.getDatastoreForTenantId(Tenants.currentId())
                      .getBoltDriver()

Partitioned Multi-Tenancy

When using the DISCRIMINATOR approach, GORM for Neo4j will store a tenantId attribute in each Neo4j node and attempt to partition the data.

Once again this works only when using GORM methods and even then there are cases where it will not work if you use native Neo4j interfaces.

For example the following works fine:

// correctly includes the `tenantId` in the query
Book.list()

As does this:

// works automatically if you include the tenantId in the query
Book.find("MATCH (p:Book) WHERE p.title={title} AND p.publisher={tenantId} RETURN p", [name:"The Stand"]")

But this query with throw an exception due to a missing tenant id:

Book.find("MATCH (p:Book) WHERE p.title={title} RETURN p", [name:"The Stand"])

Also if you obtain the driver directly the the tenant id will not be included in the query:

@Autowired Driver boltDriver

// uses the default connection and doesn't resolve the tenant it
boltDriver.session()
          .run("MATCH (p:Book) WHERE p.title={title} RETURN p", [name:"The Stand"]")

Since you are operating directly on the Driver cannot know when you perform a query that should be multi-tenant aware.

In this case you will have to ensure to include the tenantId manually:

boltDriver.session()
          .run("MATCH (p:Book) WHERE p.title={title} AND p.publisher={tenantId} RETURN p",
                [name:"The Stand", tenantId: Tenants.currentId() ])

And the same is true of write operations such as inserts that are done with the native API.

Enhancements to Neo4j Java Driver API

GORM for Neo4j contains some enhancements to the Neo4j Bolt Driver API.

Getting Properties from Nodes

The dot operator can be used to obtain properties from a node:

Node node = ...
def value = node.myProperty

// or

def value = node['myProperty']

Cast a Node to a Map

Nodes can be cast to maps:

Node node = ...
Map myMap = node as Map

Reference

Additional Gorm Methods

cypher

Purpose

Execute a cypher query.

Example
setup:
def person = new Person(firstName: "Bob", lastName: "Builder")
def petType = new PetType(name: "snake")
def pet = new Pet(name: "Fred", type: petType, owner: person)
person.addToPets(pet)
person.save(flush: true)
session.clear()

when:
def result = person.cypher("start n=node({this}) match n-[:pets]->m return m")

then:
result.iterator().size() == 1
Description

cypher is invoked on any domain instance and returns a org.neo4j.driver.v1.StatementResult

The parameters passed are:

  • cypher query string. The query string might use a implicit this parameter pointing to the instance’s node

  • a optional map of cypher parameters

cypherStatic

Purpose

Execute a cypher query.

Example
setup:
new Person(lastName:'person1').save()
new Person(lastName:'person2').save()
session.flush()
session.clear()

when:
def result = Person.cypherStatic("start n=node({this}) match n-[:INSTANCE]->m where m.lastName='person1' return m")

then:
result.iterator().size()==1
Description

cypherStatic is invoked on any domain class and returns a org.neo4j.driver.v1.StatementResult

The parameters passed are:

  • cypher query string. The query string might use a implicit this parameter pointing to the domain class’s (aka subreference) node

  • a optional map of cypher parameters

Schemaless Attributes

Purpose

For domain classes mapped by Neo4j you can put and get arbitrary attributes on a instances by using the dot operator or map semantics on the domain instance.

Example

A simple domain class:

class Person implements Serializable {
    String firstName
    String lastName
    Integer age = 0
}
Using Map Semantics
when:
def person = new Person(lastName:'person1').save()
person['notDeclaredProperty'] = 'someValue'   // n.b. the 'dot' notation is not valid for undeclared properties
person['emptyArray'] = []
person['someIntArray'] = [1,2,3]
person['someStringArray'] = ['a', 'b', 'c']
person['someDoubleArray'] = [0.9, 1.0, 1.1]
session.flush()
session.clear()
person = Person.get(person.id)

then:
person['notDeclaredProperty'] == 'someValue'
person['lastName'] == 'person1'  // declared properties are also available via map semantics
person['someIntArray'] == [1,2,3]
person['someStringArray'] == ['a', 'b', 'c']
person['someDoubleArray'] == [0.9, 1.0, 1.1]
Using Dot Operator
when:
def person = new Person(lastName:'person1').save(flush:true)
session.clear()
person = Person.load(person.id)
person.notDeclaredProperty = 'someValue'   // n.b. the 'dot' notation is not valid for undeclared properties
person.emptyArray = []
person.someIntArray = [1,2,3]
person.someStringArray = ['a', 'b', 'c']
person.someDoubleArray= [0.9, 1.0, 1.1]
session.flush()
session.clear()
person = Person.get(person.id)

then:
person.notDeclaredProperty == 'someValue'
person.lastName == 'person1'  // declared properties are also available via map semantics
person.someIntArray == [1,2,3]
person.someStringArray == ['a', 'b', 'c']
person.emptyArray == []
person.someDoubleArray == [0.9, 1.0, 1.1]
Description

The non declared attribtes are stored a regular properties on the domain instance’s node. The values of the schemaless attributes must be a valid type for Neo4j property (String, primitives and arrays of the former two).