py2neo.ogm – Object-Graph Mapping

The py2neo.ogm package contains a set of facilities for binding Python objects to an underlying set of graph data. Class definitions extend Model and include Property and Label definitions as well as details of Related objects.

A simple example, based on the movie graph data set:

class Movie(Model):
    __primarykey__ = "title"

    title = Property()
    tag_line = Property("tagline")
    released = Property()

    actors = RelatedFrom("Person", "ACTED_IN")
    directors = RelatedFrom("Person", "DIRECTED")
    producers = RelatedFrom("Person", "PRODUCED")


class Person(Model):
    __primarykey__ = "name"

    name = Property()
    born = Property()

    acted_in = RelatedTo(Movie)
    directed = RelatedTo(Movie)
    produced = RelatedTo(Movie)

Repositories

class py2neo.ogm.Repository(profile=None, name=None, **settings)

Storage container for Model instances.

The constructor for this class has an identical signature to that for the Graph class. For example:

>>> from py2neo.ogm import Repository
>>> from py2neo.ogm.models.movies import Movie
>>> repo = Repository("bolt://neo4j@localhost:7687", password="password")
>>> repo.match(Movie, "The Matrix").first()
<Movie title='The Matrix'>

New in version 2020.0. In earlier versions, a :class:`.Graph` was required to co-ordinate all reads and writes to the remote database. This class completely replaces that, removing the need to import from any other packages when using OGM.

delete(obj)

Delete the object in the remote graph.

exists(obj)

Check whether the object exists in the remote graph.

get(model, primary_value=None)

Match and return a single object from the remote graph.

Parameters:

• model – the Model subclass to match

• primary_value – value of the primary property (optional)

Return type:

Model

match(model, primary_value=None)

Select one or more objects from the remote graph.

Parameters:

• model – the Model subclass to match

• primary_value – value of the primary property (optional)

Return type:

ModelMatch

reload(obj)

Reload data from the remote graph into the local object.

save(*objects)

Save data from the local object into the remote graph.

Each object in objects can be a Model object or an iterable of such objects.

Parameters:

objects – Model objects to save.

classmethod wrap(graph)

Wrap an existing Graph object as a Repository.

Models

At the heart of the py2neo OGM framework is the Model. This is a base class for all classes that are to be mapped onto the graph database. Each Model wraps a node as well as a set of pointers to RelatedObjects and the relationship details that connect them.

A Model instance may be constructed just like any other Python object but can also be matched from the database. Each instance may contain attributes that represent labels, nodes or related objects.

class py2neo.ogm.Model(*values, **properties)

Base class for all OGM object classes.

This class provides a default constructor, allowing initial property values to be provided. Positional arguments are mapped, in order, to primary key fields; keywords arguments are mapped directly by name.

Changed in 2020.0: this used to be called GraphObject, but was renamed to avoid ambiguity. The old name is still available as an alias.

Changed in 2021.2: added default constructor.

__primarylabel__

The primary node label used for Cypher MATCH and MERGE operations. By default the name of the class is used.

This value can also be a tuple, in which case a composite primary label is implied.

__primarykey__

The primary property key used for Cypher MATCH and MERGE operations. If undefined, the special value of "__id__" is used to hinge uniqueness on the internal node ID instead of a property. Note that this alters the behaviour of operations such as Graph.create() and Graph.merge() on Model instances.

This value can also be a tuple, in which case a composite primary key is implied.

__primaryvalue__

The value of the property identified by __primarykey__. If the key is "__id__" then this value returns the internal node ID. If the primary key is a tuple, then a corresponding tuple of property values is returned.

__node__

The Node wrapped by this Model.

classmethod wrap(node)

Convert a Node into a Model.

Parameters:

node –

Returns:

classmethod match(repository, primary_value=None)

Select one or more nodes from the database, wrapped as instances of this class.

Parameters:

• repository – the Repository in which to match

• primary_value – value of the primary property (optional)

Return type:

ModelMatch

Properties

A Property defined on a Model provides an accessor to a property of the underlying node.

class py2neo.ogm.Property(key=None, default=None)

Property definition for a Model.

key

The name of the node property within the database.

default

The default value for the property, if it would otherwise be None.

>>> class Person(Model):
...     name = Property()
...
>>> alice = Person()
>>> alice.name = "Alice Smith"
>>> alice.name
"Alice Smith"

Labels

A Label defined on a Model provides an accessor to a label of the underlying central node. It is exposed as a boolean value, the setting of which allows the label to be toggled on or off.

Labels are exposed in the API in an identical way to boolean properties. The difference between these is in how the value translates into the graph database. A label should generally be used if matches are regularly carried out on that value. Secondary or supporting information could be stored in a boolean property.

class py2neo.ogm.Label(name=None)

Label definition for a Model.

Labels are toggleable tags applied to an object that can be used as type information or other forms of classification.

>>> class Food(Model):
...     hot = Label()
...
>>> pizza = Food()
>>> pizza.hot
False
>>> pizza.hot = True
>>> pizza.hot
True

Related Objects

Related objects are Model instances connected to a central Model in a particular way. For example, if a (:Person)-[:LIKES]->(:Person) relationship is used within the graph database to model a friendship, this might be modelled within the OGM layer as:

class Person(Model):
    __primarykey__ = "name"

    name = Property()

    likes = RelatedTo("Person")

This defines a likes attribute using RelatedTo, which describes an outgoing relationship. RelatedFrom can be used for an incoming relationship and Related for a relationship where direction is unimportant.

When a Person is created, its set of friends can be queried and modified through its person.likes attribute which is itself a RelatedObjects instance. Therefore to print a list of all friends:

for friend in person.likes:
    print(friend.name)

Note

It is not possible to constrain the set to contain only one item.

class py2neo.ogm.Related(related_class, relationship_type=None)

Descriptor for a set of related objects in a Model.

related_class

The class of object to which these relationships connect. This class is used to coerce nodes to and from Model instances.

relationship_type

The underlying relationship type for these relationships. Note that the relationship type should be unique for each class of related object as the related_class is only used for object coercion and not as part of the underlying database query.

class py2neo.ogm.RelatedTo(related_class, relationship_type=None)

Descriptor for a set of related objects for a Model that are connected by outgoing relationships.

class py2neo.ogm.RelatedFrom(related_class, relationship_type=None)

Descriptor for a set of related objects for a Model that are connected by incoming relationships.

class py2neo.ogm.RelatedObjects(subject, node, direction, relationship_type, related_class)

A set of similarly-typed and similarly-related objects, relative to a central node.

add(obj, properties=None, **kwproperties)

Add or update a related object.

This method returns the number of new related objects that were added: 0 if an existing object was updated, or 1 if a new object was added.

Parameters:

• obj – Model to relate.

• properties – Dictionary of properties to attach to the relationship (optional).

• kwproperties – Additional keyword properties (optional).

Returns:

Number of new related objects that were added.

clear()

Remove all related objects from this set.

get(obj, key, default=None)

Return a relationship property associated with a specific related object.

Parameters:

• obj – related object

• key – relationship property key

• default – default value, in case the key is not found

Returns:

property value

remove(obj)

Remove a related object.

Parameters:

obj – the Model to separate

triples()

Iterate through the related objects, yielding for each a triple of (subject, (type, properties), object). This is the easiest way to see the full details of the underlying relationships.

>>> from py2neo.ogm import *
>>> from py2neo.ogm.models.movies import *
>>> repo = Repository()
>>> keanu = repo.match(Person).where(name="Keanu Reeves").first()
>>> list(keanu.acted_in.triples())
[(<Person name='Keanu Reeves'>, ('ACTED_IN', {'roles': ['Julian Mercer']}), <Movie title="Something's Gotta Give">),
 (<Person name='Keanu Reeves'>, ('ACTED_IN', {'roles': ['Shane Falco']}), <Movie title='The Replacements'>),
 (<Person name='Keanu Reeves'>, ('ACTED_IN', {'roles': ['Johnny Mnemonic']}), <Movie title='Johnny Mnemonic'>),
 (<Person name='Keanu Reeves'>, ('ACTED_IN', {'roles': ['Kevin Lomax']}), <Movie title="The Devil's Advocate">),
 (<Person name='Keanu Reeves'>, ('ACTED_IN', {'roles': ['Neo']}), <Movie title='The Matrix Revolutions'>),
 (<Person name='Keanu Reeves'>, ('ACTED_IN', {'roles': ['Neo']}), <Movie title='The Matrix Reloaded'>),
 (<Person name='Keanu Reeves'>, ('ACTED_IN', {'roles': ['Neo']}), <Movie title='The Matrix'>)]

update(**kwargs)

Add or update a related object.

Parameters:

• obj – the Model to relate

• properties – dictionary of properties to attach to the relationship (optional)

• kwproperties – additional keyword properties (optional)

Object Matching

One or more Model instances can be selected from the database by using the match method of the relevant subclass.

To select a single instance using the primary label and primary key:

>>> Person.match(graph, "Keanu Reeves").first()
<Person name='Keanu Reeves'>

To select all instances that match certain criteria, you can simply iterate through the Match object. Note the use of the underscore in the Cypher WHERE clause to refer to the underlying node:

>>> list(Person.match(graph).where("_.name =~ 'K.*'"))
[<Person name='Keanu Reeves'>,
 <Person name='Kevin Bacon'>,
 <Person name='Kiefer Sutherland'>,
 <Person name='Kevin Pollak'>,
 <Person name='Kelly McGillis'>,
 <Person name='Kelly Preston'>]

class py2neo.ogm.ModelMatch(graph, labels=frozenset({}), predicates=(), order_by=(), skip=None, limit=None)

A selection of Model instances that match a given set of criteria.

__iter__()

Iterate through items drawn from the underlying repository that match the given criteria.

first()

Return the first item that matches the given criteria.