3. 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 GraphObject 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(GraphObject):
    __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(GraphObject):
    __primarykey__ = "name"

    name = Property()
    born = Property()

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

3.1. Graph Objects

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

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

class py2neo.ogm.GraphObject
__primarylabel__

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

__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 GraphObject instances.

__primaryvalue__

The value of the property identified by __primarykey__. If the key is "__id__" then this value returns the internal node ID.

classmethod GraphObject.select(graph, primary_value=None)

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

Parameters:

  • graph – the Graph instance from which to select

  • primary_value – value of the primary property (optional)

Return type:

GraphObjectSelection

3.2. Properties

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

class py2neo.ogm.Property(key=None)[source]

A property definition for a GraphObject.

Note

There is currently no support for constraining property type.

3.3. Labels

A Label defined on a GraphObject 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.

class py2neo.ogm.Label(name=None)[source]

Describe a node label for a GraphObject.

3.5. Object Selection

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

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

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

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

>>> list(Person.select(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.GraphObjectSelection(graph, labels=frozenset({}), conditions=(), order_by=(), skip=None, limit=None)[source]

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

__iter__()[source]

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

first()[source]

Return the first item that matches the given criteria.

3.6. Object Operations

GraphObject instances can be pushed into and pulled from the database just like other py2neo objects. Unlike with other kinds of object though, a GraphObject can be pushed without having first created or merged it. For example:

 >>> alice = Person()
 >>> alice.name = "Alice Smith"
 >>> graph.push(alice)
 >>> alice.__ogm__.node
(cc3030a:Person {name:"Alice Smith"})
Graph.pull(graph_object)

Update a GraphObject and its associated RelatedObject instances with changes from the graph.

Graph.push(graph_object)

Update the graph with changes from a GraphObject and its associated RelatedObject instances. If a corresponding remote node does not exist, one will be created. If one does exist, it will be updated. The set of outgoing relationships will be adjusted to match those described by the RelatedObject instances.

Graph.create(graph_object)
Graph.merge(graph_object)

For a GraphObject, create and merge are an identical operation. This is because GraphObject instances have uniqueness defined by their primary label and primary key and so both operations can be considered a form of merge.

If a corresponding remote node does not exist, one will be created. Unlike push, however, no update will occur if a node already exists.

Graph.delete(graph_object)

Delete the remote node and relationships that correspond to the given GraphObject.