1. py2neo.data – Data Types

Note

For convenience, the members of py2neo.data can also be imported directly from py2neo.

Py2neo provides a rich set of data types for working with both graph and record-based data. The graph types are completely compatible with Neo4j but can also be used independently. They include the fundamental entities Node and Relationship as well as classes that represent collections of these entities.

Graph data classes have been designed to work together using standard operations, most notably set operations. Details of these operations are covered in the sections on Subgraph objects and Path objects and other Walkable types.

1.1. Node and Relationship objects

The two essential building blocks of the labelled property graph model used by Neo4j are the Node and the Relationship. The 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.data import Node, Relationship
>>> a = Node("Person", name="Alice")
>>> b = Node("Person", name="Bob")
>>> ab = Relationship(a, "KNOWS", b)
>>> ab
(Alice)-[:KNOWS]->(Bob)
class py2neo.data.Node(*labels, **properties)[source]

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().

node.labels

Return the full set of labels associated with node.

label in node.labels

Return True if node has the label label.

node.labels.add(label)

Add the label label to node.

node.labels.discard(label)

Remove the label label from node, if it exists.

node.labels.remove(label)

Remove the label label from node, raising a ValueError if it does not exist.

node.labels.clear()

Remove all labels from node.

node.labels.update(labels)

Add multiple labels to node from the iterable labels.

class py2neo.data.Relationship(start_node, type, end_node, **properties)[source]
class py2neo.data.Relationship(start_node, end_node, **properties)
class py2neo.data.Relationship(node, type, **properties)
class py2neo.data.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)
>>> type(ac)
'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(relationship)

Return the type of this relationship.

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 py2neo.data.PropertyDict(iterable, **kwargs)[source]

The PropertyDict extends Python’s built-in dict type. All operations and methods are identical to those of its 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)[source]

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)[source]

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. Subgraph objects

A Subgraph is an arbitrary collection of nodes and relationships. By definition, a Subgraph must contain at least one node; null subgraphs should be represented by None. To test for emptiness the built-in bool() function can be used.

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 py2neo.data.Subgraph(nodes, relationships)[source]

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 the 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.

1.3. Path objects and other Walkable types

A Walkable is a Subgraph with added traversal information The simplest way to construct a walkable is to concatenate 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 py2neo.data.Walkable(iterable)[source]

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 py2neo.data.Path(*entities)[source]

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

py2neo.data.walk(*walkables)[source]

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

1.4. Record objects

class py2neo.data.Record(iterable=())[source]

A Record object holds an ordered, keyed collection of values. It is in many ways similar to a namedtuple but allows field access only through bracketed syntax and provides more functionality. Record extends both tuple and Mapping.

record[index]
record[key]

Return the value of record with the specified key or index.

len(record)

Return the number of fields in record.

dict(record)

Return a dict representation of record.

data(*keys)[source]

Return the keys and values of this record as a dictionary, optionally including only certain values by index or key. Keys provided that do not exist within the record will be included but with a value of None; indexes provided that are out of bounds will trigger an IndexError.

Parameters:keys – indexes or keys of the items to include; if none are provided, all values will be included
Returns:dictionary of values, keyed by field name
Raises:IndexError if an out-of-bounds index is specified
get(key, default=None)[source]

Obtain a single value from the record by index or key. If the specified item does not exist, the default value is returned.

Parameters:
  • key – index or key
  • default – default value to be returned if key does not exist
Returns:

selected value

index(key)[source]

Return the index of the given item.

items(*keys)[source]

Return the fields of the record as a list of key and value tuples

Parameters:keys – indexes or keys of the items to include; if none are provided, all values will be included
Returns:list of (key, value) tuples
keys()[source]

Return the keys of the record.

Returns:list of key names
to_subgraph()[source]

Return a Subgraph containing the union of all the graph structures within this Record.

Returns:Subgraph object
values(*keys)[source]

Return the values of the record, optionally filtering to include only certain values by index or key.

Parameters:keys – indexes or keys of the items to include; if none are provided, all values will be included
Returns:list of values

1.5. Table objects

class py2neo.data.Table(records, keys=None)[source]

A Table holds a list of Record objects, typically received as the result of a Cypher query. It provides a convenient container for working with a result in its entirety and provides methods for conversion into various output formats. Table extends list.

repr(table)

Return a string containing an ASCII art representation of this table. Internally, this method calls write() with header=True, writing the output into an io.StringIO instance.

_repr_html_()[source]

Return a string containing an HTML representation of this table. This method is used by Jupyter notebooks to display the table natively within a browser. Internally, this method calls write_html() with header=True, writing the output into an io.StringIO instance.

keys()[source]

Return a list of field names for this table.

field(key)[source]

Return a dictionary of metadata for a given field. The metadata includes the following values:

type
Single class or tuple of classes representing the field values.
numeric
True if all field values are of a numeric type, False otherwise.
optional
True if any field values are None, False otherwise.
write(file=None, header=None, skip=None, limit=None, auto_align=True, padding=1, separator='|', newline='\r\n')[source]

Write data to a human-readable ASCII art table.

Parameters:
  • file – file-like object capable of receiving output
  • header – boolean flag for addition of column headers
  • skip – number of records to skip before beginning output
  • limit – maximum number of records to include in output
  • auto_align – if True, right-justify numeric values
  • padding – number of spaces to include between column separator and value
  • separator – column separator character
  • newline – newline character sequence
Returns:

the number of records included in output

write_html(file=None, header=None, skip=None, limit=None, auto_align=True)[source]

Write data to an HTML table.

Parameters:
  • file – file-like object capable of receiving output
  • header – boolean flag for addition of column headers
  • skip – number of records to skip before beginning output
  • limit – maximum number of records to include in output
  • auto_align – if True, right-justify numeric values
Returns:

the number of records included in output

write_separated_values(separator, file=None, header=None, skip=None, limit=None, newline='\r\n', quote='"')[source]

Write data to a delimiter-separated file.

Parameters:
  • separator – field separator character
  • file – file-like object capable of receiving output
  • header – boolean flag (or dictionary of click.secho styles) for addition of column headers
  • skip – number of records to skip before beginning output
  • limit – maximum number of records to include in output
  • newline – newline character sequence
  • quote – quote character
Returns:

the number of records included in output

write_csv(file=None, header=None, skip=None, limit=None)[source]

Write the data as RFC4180-compatible comma-separated values. This is a customised call to write_separated_values().

write_tsv(file=None, header=None, skip=None, limit=None)[source]

Write the data as tab-separated values. This is a customised call to write_separated_values().