Model Objects

Warning

This is the first iteration of the interface for model objects. The function/class signatures might change in the next releases.

Basic Usage

Creating NodeSet and RelationshipSet classes with string is error prone.

Graphio offers a simple object graph model system:

from graphio import ModelNode, ModelRelationship

class Person(ModelNode):
    name = MergeKey()

class Food(ModelNode):
    type = MergeKey()

class PersonLikes(ModelRelationship):
    source = Person
    target = Food
    type = 'LIKES'

You can use these classes to create NodeSet and RelationshipSet:

person_nodeset = Person.dataset()
food_nodeset = Food.dataset()

person_likes_food = PersonLikes.dataset()

When adding data to the RelationshipSet you can use the MergeKey properties of the ModelNode classes to avoid typing the properties as strings:

for name, food in [('Susan', 'Pizza'), ('Ann', 'Sushi')]:
    person_likes_food.add_relationship(
        {Person.name: name}, {Food.type: food}
    )

You can set one or multiple Label and MergeKey properties on the ModelNode:

class Person(ModelNode):
    first_name = MergeKey()
    last_name = MergeKey()

    Person = Label()
    Human = Label()

You can override the actual values of the Label and MergeKey:

class Person(ModelNode):
    first_name = MergeKey('first_name')
    last_name = MergeKey('surname')

    Person = Label('Individual')
    Human = Label('HomoSapiens')

Add data with model instances

You can create instances of the model objects to create individual nodes and relationships:

from graphio import ModelNode, ModelRelationship
from py2neo import Graph

graph = Graph()

class Person(ModelNode):
    name = MergeKey()

class Food(ModelNode):
    type = MergeKey()

class PersonLikes(ModelRelationship):
    source = Person
    target = Food
    type = 'LIKES'

alice = Person(name='Alice')
sushi = Food(type='Sushi')

alice.merge(graph)
sushi.merge(graph)

alice_likes_sushi = PersonLikes(alice, sushi)
alice_likes_sushi.merge(graph)

You can also link nodes without creating ModelRelationship instances:

alice.link(graph, PersonLikes, sushi, since='always')

ModelNode

class graphio.ModelNode(*args, **kwargs)

Baseclass for model objects.

property additional_props: dict

Return all properties except the merge properties.

Returns

Dictionary with all properties except the merge properties.

Return type

dict

bind(graph)

Make sure the node is bound to the graph.

Parameters

graph – py2neo.Graph

classmethod dataset() graphio.objects.nodeset.NodeSet
Returns

Return a NodeSet instance for this ModelNode.

exists(graph: py2neo.database.Graph) Union[bool, py2neo.data.Node]

Check if node exists in the graph. If yes: return the Node. If no: return false.

Raise a TypeError if there is more than one Node found with these properties. Node definition only makes sense if working with unique nodes.

Parameters

graph – py2neo.Graph instance

Returns

The node or False.

classmethod factory(labels: List[str], merge_keys: Optional[List[str]] = None, name: Optional[str] = None) type

Create a class with given labels and merge_keys. The merge_keys are optional but some functions do not work without them.

Parameters
  • labels – Labels for this ModelNode class.

  • merge_keys – MergeKeys for this ModelNode class.

Returns

The ModelNode class.

Link the node to another node.

Input is either a combination of a ModelRelationship and ModelNode or a combination of a string for the reltype and a NodeDescriptor instance to describe the target node.

Parameters
  • graph – py2neo.Graph instance.

  • reltype – Either a ModelRelationship instance or a string for the relationship type.

  • target – Either a ModelNode instance or a NodeDescriptor instance.

  • properties – Proeprties for the relationships.

merge(graph: py2neo.database.Graph) None

MERGE the node in the graph.

Parameters

graph – A py2neo.Graph instance.

property merge_props: dict

Return the merge properties for this node.

Returns

Dictionary with the merge properties for this node.

Return type

dict

ModelRelationship

class graphio.ModelRelationship(source: graphio.model.ModelNode, target: graphio.model.ModelNode, **kwargs)

Base class for model relationships.

Knows about the class of source node and target node (instances of ModelNode) and the relationship type:

class Person(ModelNode):
    name = MergeKey()

class Food(ModelNode):
    name = MergeKey()

class PersonLikesToEat(ModelRelationship):
    source = Person
    target = Food
    type = 'LIKES'
classmethod dataset() graphio.objects.relationshipset.RelationshipSet
Returns

Return a RelationshipSet instance for this ModelRelationship.

exists(graph: py2neo.database.Graph) bool

Check if the relationship exists.

Parameters

graph – A py2neo.Graph instance.

Returns

True/False

merge(graph: py2neo.database.Graph)

MERGE the relationship in the graph.

Parameters

graph – A py2neo.Graph instance.

Helper Classes

class graphio.NodeDescriptor(labels: List[str], properties: dict, merge_keys: Optional[List[str]] = None)

Unified interface to describe nodes with labels and properties.

NodeDescriptor instances are passed into functions when no ModelNode classes or instances are available.

Setting merge_keys is optional. If they are not set all property keys will be used as merge_keys.

Parameters
  • labels – Labels for this node.

  • properties – Properties for this node.

  • merge_keys – Optional.