Skip to main content

An object mapper for the neo4j graph database.

Project description

An object mapper for the neo4j graph database.

  • Structured node definitions with type checking
  • Lazy category node creation
  • Automatic indexing
  • Relationship traversal
  • Soft cardinality restrictions
  • pre and post save / delete hooks (and django signals!)

Supports: neo4j 1.8+ (1.9 recommended), python 2.6, 2.7


Install the module via git:

pip install -e



export NEO4J_REST_URL=http://localhost:7474/db/data/

Or with authentication:

export NEO4J_REST_URL=http://user:password@localhost:7474/db/data/

Node definitions:

from neomodel import StructuredNode, StringProperty, IntegerProperty, RelationshipTo, RelationshipFrom
class Country(StructuredNode):
    code = StringProperty(unique_index=True, required=True)

    # traverse incoming IS_FROM relation, inflate to Person objects
    inhabitant = RelationshipFrom('Person', 'IS_FROM')

class Person(StructuredNode):
    name = StringProperty(unique_index=True)
    age = IntegerProperty(index=True, default=0)

    # traverse outgoing IS_FROM relations, inflate to Country objects
    country = RelationshipTo('Country', 'IS_FROM')

In the above example, there is one type of relationship present IS_FROM, we are defining two different methods for traversing it one accessible via Person objects and one via Country objects.


CReate Update Delete:

jim = Person(name='Jim', age=3).save()
jim.age = 4 # validation happens here

Batch create (atomic) which also validates and indexes:

people = Person.create(
    {'name': 'Tim', 'age': 83},
    {'name': 'Bob', 'age': 23},
    {'name': 'Jill', 'age': 34},

Hooks and Signals

You may define the following hook methods on your nodes:

pre_save, post_save, pre_delete, post_delete, post_create

Signals are also supported if django is available:

from django.db.models import signals
signals.post_save.connect(your_func, sender=Person)


Access related nodes through your defined relations:

germany = Country(code='DE').save()

    print("Jim's from Germany")

for p in germany.inhabitant.all()
    print( # Jim

len(germany.inhabitant) # 1

Search related nodes through your defined relations. This example starts at the germany node and traverses incoming ‘IS_FROM’ relations and returns the nodes with the property name that is equal to ‘Jim’:'Jim')

If you don’t care about the direction of the relationship:

class Person(StructuredNode):
    friends = Relationship('Friend', 'FRIEND')

You may also reference classes from another module:

class Person(StructuredNode):
    car = RelationshipTo('transport.models.Car', 'CAR')


It’s possible to enforce cardinality restrictions on your relationships. Remember this needs to be declared on both sides of the relationship for it to work:

class Person(StructuredNode):
    car = RelationshipTo('Car', 'CAR', cardinality=One)

class Car(StructuredNode):
    owner = RelationshipFrom('Person', cardinality=One)

The following cardinality classes are available:

ZeroOMore (default), OneOrMore, ZeroOrOne, One

If cardinality is broken by existing data a CardinalityViolation exception is raised. On attempting to break a cardinality restriction a AttemptedCardinalityViolation is raised.

Custom cypher queries

You may handle more complex queries via cypher. Each node provides an ‘inflate’ class method, this inflates py2neo nodes to neomodel node objects:

class Person(StructuredNode):
    def friends(self):
        results = self.cypher("START a=node({self}) MATCH a-[:FRIEND]->(b) RETURN b");
        return [self.__class__.inflate(row[0]) for row in results]

The self query parameter is prepopulated with the current node id. It’s possible to pass in your own query parameters to the cypher method.

Relating to different node types

You can define relations of a single relation type to different StructuredNode classes.:

class Humanbeing(StructuredNode):
    name = StringProperty()
    has_a = RelationshipTo(['Location', 'Nationality'], 'HAS_A')

class Location(StructuredNode):
    name = StringProperty()

class Nationality(StructuredNode):
    name = StringProperty()

Remember that when traversing the has_a relation you will retrieve objects of different types.

Category nodes

Access your instances via the category node:

country_category = Country.category()
for c in country_category.instance.all()

Note that connect and disconnect are not available through the instance relation. As these actions are handled for your via the save() and delete() methods.

Read-only nodes

If you have existing nodes you want to protect use the read-only base class:

from neomodel.core import ReadOnlyNode, ReadOnlyError

class ImmortalBeing(ReadOnlyNode):
    name = StringProperty()

Now all write operations below raise a ReadOnlyError:



Make use of indexes:

jim = Person.index.get(name='Jim')
for p in

germany = Country(code='DE').save()

Use advanced Lucene queries with the lucene-querybuilder module:

from lucenequerybuilder import Q

Human(name='sarah', age=3).save()
Human(name='jim', age=4).save()
Human(name='bob', age=5).save()
Human(name='tim', age=2).save()

for h in'age', inrange=[3, 5])):

# prints: sarah, jim, bob

If you have an existing node index you can change the default name of your index. This can be useful for integrating with neo4django schemas:

class Human(StructuredNode):
    _index_name = 'myHumans'
    name = StringProperty(indexed=True) # myHumans


The following basic properties are available:

StringProperty, IntegerProperty, FloatProperty, BooleanProperty

Additionally there is also:

DateProperty, DateTimeProperty, AliasProperty

The DateTimeProperty accepts datetime.datetime objects of any timezone and stores them as a UTC epoch value.

These epoch values are inflated to datetime.datetime objects with the UTC timezone set.

The DateProperty accepts objects which are stored as a string property ‘YYYY-MM-DD’.

Default values you may provide a default value to any property, this can also be a function or any callable:

def uid_generator():
    # your algorithm here

name = StringProperty(unique_index=True, default=uid_generator)

The AliasProperty a special property for aliasing other properties and providing ‘magic’ behaviour:

class Person(StructuredNode):
    full_name = StringProperty(index=True)
    name = AliasProperty(to='full_name')'Jim') # just works

Custom properties can provide a setup method which will get invoked on class definition.

Project details

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
neomodel-0.2.7.tar.gz (19.6 kB) Copy SHA256 hash SHA256 Source None Feb 22, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page