1. py2neo.types – Graph Data Types

Py2neo provides a set of core graph data types that are completely compatible with Neo4j but that can also be used independently of it. These types include the fundamental entities Node and Relationship as well as classes that represent collections of these entities.

These types have been carefully designed to work together using standard operations, most notably set operations. Details of these operations are covered in the sections on Subgraphs and Walkable Types.

1.1. Nodes & Relationships

The two essential building blocks of the property graph model used by Neo4j are the Node and the Relationship. A node is the fundamental unit of data storage within a graph. It can contain a set of key-value pairs (properties) and can optionally be adorned with one or more textual labels. A relationship is a typed, directed connection between a pair of nodes (or alternatively a loop on a single node). Like nodes, relationships may also contain a set of properties.

The code below shows how to create a couple of nodes and a relationship joining them. Each node has a single property, name, and is labelled as a Person. The relationship ab describes a KNOWS connection from the first node a to the second node b.

>>> from py2neo import Node, Relationship
>>> a = Node("Person", name="Alice")
>>> b = Node("Person", name="Bob")
>>> ab = Relationship(a, "KNOWS", b)
>>> ab
(alice)-[:KNOWS]->(bob)
class Node(*labels, **properties)

Construct a new node object with the labels and properties specified. In its initial state, a node is unbound. This means that it exists only on the client and does not reference a corresponding server node. A node is typically bound by creating it in a Neo4j database.

node == other

Return True if node and other are equal. Node equality is based solely on the ID of the remote node it represents; neither properties nor labels factor into equality. This means that if bound, a node object can only be considered equal to another node object that is bound to the same remote node. If a node is unbound, thereby having no corresponding node ID, it can only ever be equal to itself.

node != other

Return True if the nodes are unequal.

hash(node)

Return a hash of node based on its object ID, if unbound, or the ID of the remote node it represents, if bound.

node[key]

Return the property value of node with key key or None if the key is missing.

node[key] = value

Set the property value of node with key key to value or remove the property if value is None.

del node[key]

Remove the property with key key from node, raising a KeyError if such a property does not exist.

len(node)

Return the number of properties in node.

dict(node)

Return a dictionary of all the properties in node.

walk(node)

Yield node as the only item in a walk().

labels()

Return the full set of labels associated with the node.

has_label(label)

Return True if the node has the label label.

add_label(label)

Add the label label to the node.

remove_label(label)

Remove the label label from the node if it exists.

clear_labels()

Remove all labels from the node.

update_labels(labels)

Add multiple labels to the node from the iterable labels.

class Relationship(start_node, type, end_node, **properties)
class Relationship(start_node, end_node, **properties)
class Relationship(node, type, **properties)
class Relationship(node, **properties)

Construct a relationship between a pair of nodes (or between a node and itself) of type type. If the type is not specified, it will default to TO. This default can be overridden by extending the Relationship class:

>>> c = Node("Person", name="Carol")
>>> class WorksWith(Relationship): pass
>>> ac = WorksWith(a, c)
>>> ac.type()
'WORKS_WITH'
relationship == other

Return True if relationship and other are equal. Relationship equality is based on equality of the start node, the end node and the relationship type (node equality is described above). This means that any two relationships of the same type between the same nodes are always considered equal. Note that this behaviour differs slightly from Neo4j itself which permits multiple relationships of the same type between the same nodes.

relationship != other

Return True if the relationships are unequal.

hash(relationship)

Return a hash of relationship based on its start node, end node and type.

relationship[key]

Return the property value of relationship with key key or None if the key is missing.

relationship[key] = value

Set the property value of relationship with key key to value or remove the property if value is None.

del relationship[key]

Remove the property with key key from relationship, raising a KeyError if such a property does not exist.

len(relationship)

Return the number of properties in relationship.

dict(relationship)

Return a dictionary of all the properties in relationship.

walk(relationship)

Perform a walk() of this relationship, yielding its start node, the relationship itself and its end node in turn.

type()

Return the type of this relationship.

1.1.1. Properties

Both Node and Relationship extend the PropertyDict class which itself extends Python’s built-in dictionary. This means that nodes and relationships are both mapping types that can contain property values, indexed by key.

As with Neo4j itself, property values may not be None. A missing property (i.e. no key present) is the idiomatic way to model absence of value.

The PropertyDict class is described in more detail below.

class PropertyDict(iterable, **kwargs)

The PropertyDict extends Python’s built-in dict type. All operations and methods are identical to those of the base class except for those described below.

properties == other

Return True if properties is equal to other after all None values have been removed from other.

properties != other

Return True if properties is unequal to other after all None values have been removed from other.

properties[key]

Return the value of properties with key key or None if the key is missing.

properties[key] = value

Set the value of properties with key key to value or remove the property if value is None.

setdefault(key, default=None)

If key is in the PropertyDict, return its value. If not, insert key with a value of default and return default unless default is None, in which case do nothing. The value of default defaults to None.

update(iterable=None, **kwargs)

Update the PropertyDict with the key-value pairs from iterable followed by the keyword arguments from kwargs. Individual properties already in the PropertyDict will be overwritten by those in iterable and subsequently by those in kwargs if the keys match. Any value of None will effectively delete the property with that key, should it exist.

1.2. Subgraphs

A Subgraph is a collection of nodes and relationships. The simplest way to construct a subgraph is by combining nodes and relationships using standard set operations. For example:

>>> s = ab | ac
>>> s
{(alice:Person {name:"Alice"}),
 (bob:Person {name:"Bob"}),
 (carol:Person {name:"Carol"}),
 (alice)-[:KNOWS]->(bob),
 (alice)-[:WORKS_WITH]->(carol)}
>>> s.nodes()
frozenset({(alice:Person {name:"Alice"}),
           (bob:Person {name:"Bob"}),
           (carol:Person {name:"Carol"})})
>>> s.relationships()
frozenset({(alice)-[:KNOWS]->(bob),
           (alice)-[:WORKS_WITH]->(carol)})
class Subgraph(nodes, relationships)

A Subgraph is an immutable set of nodes and relationships that can be provided as an argument to many graph database functions. It is also used as a base class for Node, Relationship and Walkable, allowing instances of those classes to be combined using set operations.

subgraph | other | ...

Union. Return a new subgraph containing all nodes and relationships from subgraph as well as all those from other. Any entities common to both will only be included once.

subgraph & other & ...

Intersection. Return a new subgraph containing all nodes and relationships common to both subgraph and other.

subgraph - other - ...

Difference. Return a new subgraph containing all nodes and relationships that exist in subgraph but do not exist in other, as well as all nodes that are connected by the relationships in subgraph regardless of whether or not they exist in other.

subgraph ^ other ^ ...

Symmetric difference. Return a new subgraph containing all nodes and relationships that exist in subgraph or other, but not in both, as well as all nodes that are connected by those relationships regardless of whether or not they are common to subgraph and other.

subgraph.keys()

Return the set of all property keys used by the nodes and relationships in this subgraph.

subgraph.labels()

Return the set of all node labels in this subgraph.

subgraph.nodes()

Return the set of all nodes in this subgraph.

subgraph.relationships()

Return the set of all relationships in this subgraph.

subgraph.types()

Return the set of all relationship types in this subgraph.

order(subgraph)

Return the number of nodes in subgraph. This argument can be an instance of Subgraph or of any derived class, such as Path.

size(subgraph)

Return the number of relationships in subgraph. This argument can be an instance of Subgraph or of any derived class, such as Path.

1.3. Walkable Types

A Walkable is a Subgraph with added traversal information. The simplest way to construct a walkable is by concatenating other graph objects:

>>> w = ab + Relationship(b, "LIKES", c) + ac
>>> w
(alice)-[:KNOWS]->(bob)-[:LIKES]->(carol)<-[:WORKS_WITH]-(alice)

The traversal of a walkable object is achieved by using the walk() function, which yields alternating nodes and relationships and always starts and ends with a node. Any node or relationship may be traversed one or more times in any direction.

class Walkable(iterable)

A Walkable is a Subgraph with added traversal information.

walkable + other + ...

Concatenation. Return a new Walkable that represents a walk() of walkable followed by a walk() of other. This is only possible if the end node of walkable is the same as either the start node or the end node of other; in the latter case, other will be walked in reverse.

Nodes that overlap from one operand onto another are not duplicated in the returned Walkable.

walk(walkable)

Perform a walk() of walkable, yielding alternating nodes and relationships.

start_node()

Return the first node encountered on a walk() of this object.

end_node()

Return the last node encountered on a walk() of this object.

nodes()

Return a tuple of all nodes traversed on a walk() of this Walkable, listed in the order in which they were first encountered.

relationships()

Return a tuple of all relationships traversed on a walk() of this Walkable, listed in the order in which they were first encountered.

class Path(*entities)

A Path is a type of Walkable returned by some Cypher queries.

walk(*walkables)

Traverse over the arguments supplied, in order, yielding alternating nodes and relationships.