Skip to main content

An object mapper for the neo4j graph database.

Project description

neomodel

An Object Graph Mapper (OGM) for the neo4j graph database.

Don’t need an OGM? Try the awesome py2neo (which this library is built on).

Supports: neo4j 2.0+ python 2.7

https://secure.travis-ci.org/robinedwards/neomodel.png

The basics

Set the location of neo4j via an environment variable (default is http://localhost:7474/db/data/):

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

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

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')

We can use the Relationship class if we don’t want to specify a direction.

Create, save delete etc:

jim = Person(name='Jim', age=3).save()
jim.age = 4
jim.save() # validation happens here
jim.delete()
jim.refresh() # reload properties from neo

Using relationships:

germany = Country(code='DE').save()
jim.country.connect(germany)

if jim.country.is_connected(germany):
    print("Jim's from Germany")

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

len(germany.inhabitant) # 1

# Find people called 'Jim' in germany
germany.inhabitant.search(name='Jim')

jim.country.disconnect(germany)

Relationship models, define your relationship properties:

class FriendRel(StructuredRel):
    since = DateTimeProperty(default=lambda: datetime.now(pytz.utc))
    met = StringProperty()

class Person(StructuredNode):
    name = StringProperty()
    friends = RelationshipTo('Person', 'FRIEND', model=FriendRel)

rel = jim.friend.connect(bob)
rel.since # datetime object

You can specify the properties during connect:

rel = jim.friend.connect(bob, {'since': yesterday, 'met': 'Paris'})

print(rel.start_node().name) # jim
print(rel.end_node().name) # bob

rel.met = "Amsterdam"
rel.save()

You can retrieve relationships between to nodes using the ‘relationship’ method. This is only available for relationships with a defined structure:

rel = jim.friend.relationship(bob)

Directionless relationships:

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

When defining relationships, you may refer to classes in other modules. This helps avoid cyclic imports:

class Garage(StructuredNode):
    cars = RelationshipTo('transport.models.Car', 'CAR')
    vans = RelationshipTo('.models.Van', 'VAN')

When defining models that have custom __init__(self, …) function, don’t forget to call super(). Otherwise things start to fail:

class Person(StructuredNode):
    name = StringProperty(unique_index=True)

    def __init__(self, name, **args):
        self.name = name

        super(Person, self).__init__(self, **args)

Cardinality

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.

Matching

The new API for accessing and traversing many nodes at once:

class SupplierRel(StructuredRel):
    since = DateTimeProperty(default=datetime.now)


class Supplier(StructuredNode):
    name = StringProperty()
    delivery_cost = IntegerProperty()
    coffees = RelationshipTo('Coffee', 'SUPPLIES')


class Coffee(StructuredNode):
    name = StringProperty(unique_index=True)
    price = IntegerProperty()
    suppliers = RelationshipFrom(Supplier, 'SUPPLIES', model=SupplierRel)

Filter (chainable) and get:

# nodes with label Coffee whose price is greater than 2
Coffee.nodes.filter(price__gt=2)

try:
    java = Coffee.nodes.get(name='Java')
except Coffee.DoesNotExist:
    print "Couldn't find coffee 'Java'"

Checking for the existence of at least one relationship with has:

Coffee.nodes.has(suppliers=True)

Iteration, slicing, counting:

# Iterable
for coffee in Coffee.nodes:
    print coffee.name

# Sliceable
coffee = Coffee.nodes.filter(price__gt=2)[2:]

# Count
print len(Coffee.nodes.filter(price__gt=2))

Boolean:

if Coffee.nodes:
    print "We have coffee nodes!"

Filtering on relationship properties using match:

nescafe = Coffee.nodes.get(name="Nescafe")

for supplier in nescafe.suppliers.match(since_lt=january):
    print supplier.name

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, columns = self.cypher("START a=node({self}) MATCH a-[:FRIEND]->(b) RETURN b")
        return [self.__class__.inflate(row[0]) for row in results]

# for standalone queries
from neomodel import db
results, meta = db.cypher_query(query, params)
perople = [Person.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.

You may log queries by setting the environment variable NEOMODEL_CYPHER_DEBUG to true.

Batch create

Atomically create multiple nodes in a single operation:

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

This is useful for creating large sets of data. It’s worth experimenting with the size of batches to find the optimum performance. A suggestion is to use batch sizes of around 300 to 500 nodes.

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)

Transactions

transactions can be used via a function decorator or context manager:

with db.transaction:
    Person(name='Bob').save()

@db.transaction
def update_user_name(uid, name):
    user = Person.nodes.filter(uid=uid)[0]
    user.name = name
    user.save()

Indexing - DEPRECATED

Please use Object.nodes instead.

Make use of indexes:

jim = Person.index.get(name='Jim')
for p in Person.index.search(age=3):
    print(p.name)

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 Human.index.search(Q('age', inrange=[3, 5])):
    print(h.name)

# prints: sarah, jim, bob

Or use lucene query syntax directly:

Human.index.search("age:4")

Specify a custom index name for a class (inherited). Be very careful when sharing indexes between classes as this means nodes will be inflated to any class sharing the index. Properties of the same name on different classes may conflict.:

class Badger(StructuredNode):
    __index__ = 'MyBadgers'
    name = StringProperty(unique_index=True)

Properties

The following properties are available:

StringProperty, IntegerProperty, FloatProperty, BooleanProperty, ArrayProperty

DateProperty, DateTimeProperty, JSONProperty, 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. If you want neomodel to raise an exception on receiving a datetime without a timezone you set the env var NEOMODEL_FORCE_TIMEZONE=1.

The DateProperty accepts datetime.date 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:

from uuid import uuid4
my_id = StringProperty(unique_index=True, default=uuid4)

You may provide arguments using a wrapper function or lambda:

my_datetime = DateTimeProperty(default=lambda: datetime.now(pytz.utc))

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')

Person.index.search(name='Jim') # just works

Project details


Download files

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

Source Distribution

neomodel-1.0.0.tar.gz (30.7 kB view details)

Uploaded Source

Built Distribution

neomodel-1.0.0.macosx-10.4-x86_64.exe (111.0 kB view details)

Uploaded Source

File details

Details for the file neomodel-1.0.0.tar.gz.

File metadata

  • Download URL: neomodel-1.0.0.tar.gz
  • Upload date:
  • Size: 30.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for neomodel-1.0.0.tar.gz
Algorithm Hash digest
SHA256 9d669d65b08442f1003b4785479746938c40c2b5d5a99406a5c3097eaa23dcaf
MD5 cfd942b5663bc4bca82e20e7060acb35
BLAKE2b-256 5ffde1d2119b43542335b40d99b55ce316f470a0b83f3ac73965e5c092a26a08

See more details on using hashes here.

File details

Details for the file neomodel-1.0.0.macosx-10.4-x86_64.exe.

File metadata

File hashes

Hashes for neomodel-1.0.0.macosx-10.4-x86_64.exe
Algorithm Hash digest
SHA256 20e9ba9e7717aca051b859e44de1ff387de6d28f95a4656f80acba49759b1628
MD5 b65d7c079c9c98c5e9edabdf8264897a
BLAKE2b-256 c8df57b0eaa39b9bf5be5e2348ee38aeb271bc302c219accc6d7215c9285d48f

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page