2. py2neo.database – Graph Databases

The py2neo.database package contains classes and functions required to interact with a Neo4j server. For convenience, many of these classes are also exposed through the top-level package, py2neo.

The most useful of the classes provided here is the Graph class which represents a Neo4j graph database instance and provides access to a large portion of the most commonly used py2neo API.

To run a query against a local database is straightforward:

>>> from py2neo import Graph
>>> graph = Graph(password="password")
>>> graph.run("UNWIND range(1, 3) AS n RETURN n, n * n as n_sq").to_table()
   n | n_sq
-----|------
   1 |    1
   2 |    4
   3 |    9

2.1. The GraphService

class py2neo.database.GraphService[source]

Accessor for an entire Neo4j graph database installation over Bolt or HTTP. Within the py2neo object hierarchy, a GraphService contains a Graph in which most activity occurs.

Note

In earlier versions, this class was known as Database.

An explicit URI can be passed to the constructor:

>>> from py2neo import GraphService
>>> gs = GraphService("bolt://camelot.example.com:7687")

Alternatively, the default value of bolt://localhost:7687 is used:

>>> default_gs = GraphService()
>>> default_gs
<GraphService uri='bolt://localhost:7687'>
property config

Return a dictionary of the configuration parameters used to configure Neo4j.

property default_graph

The default graph exposed by this graph service.

Return type

Graph

classmethod forget_all()[source]

Forget all cached GraphService details.

property kernel_version

Return the version of Neo4j.

property product

Return the product name.

property system_graph

The system graph exposed by this graph service.

Return type

SystemGraph

property uri

The URI to which this GraphService is connected.

2.2. The Graph

class py2neo.database.Graph(uri, name=None, **settings)[source]

The Graph class represents the graph data storage space within a Neo4j graph database. Connection details are provided using URIs and/or individual settings.

The name argument allows selection of a graph database by name. When working with Neo4j 4.0 and above, this can be any name defined in the system catalogue, a full list of which can be obtained through the Cypher SHOW DATABASES command. Passing None here will select the default database, as defined on the server. For earlier versions of Neo4j, the name must be set to None.

>>> from py2neo import Graph
>>> sales = Graph("bolt+s://g.example.com:7687", name="sales")
>>> sales.run("MATCH (c:Customer) RETURN c.name")
 c.name
---------------
 John Smith
 Amy Pond
 Rory Williams

The system graph, which is available in all 4.x+ product editions, can also be accessed via the SystemGraph class.

>>> from py2neo import SystemGraph
>>> sg = SystemGraph("bolt+s://g.example.com:7687")
>>> sg.call("dbms.security.listUsers")
 username | roles | flags
----------|-------|-------
 neo4j    |  null | []

Supported URI schemes are:

  • bolt - Bolt (unsecured)

  • bolt+s - Bolt (secured with full certificate checks)

  • bolt+ssc - Bolt (secured with no certificate checks)

  • http - HTTP (unsecured)

  • https - HTTP (secured with full certificate checks)

  • http+s - HTTP (secured with full certificate checks)

  • http+ssc - HTTP (secured with no certificate checks)

The full set of supported settings are:

Keyword

Description

Type

Default

scheme

Use a specific URI scheme

str

'bolt'

secure

Use a secure connection (TLS)

bool

False

verify

Verify the server certificate (if secure)

bool

True

host

Database server host name

str

'localhost'

port

Database server port

int

7687

address

Colon-separated host and port string

str

'localhost:7687'

user

User to authenticate as

str

'neo4j'

password

Password to use for authentication

str

'password'

auth

A 2-tuple of (user, password)

tuple

('neo4j', 'password')

user_agent

User agent to send for all connections

str

(depends on URI scheme)

max_connections

The maximum number of simultaneous connections permitted

int

40

Each setting can be provided as a keyword argument or as part of an URI. Therefore, the three examples below are all equivalent:

>>> from py2neo import Graph
>>> graph_1 = Graph()
>>> graph_2 = Graph(host="localhost")
>>> graph_3 = Graph("bolt://localhost:7687")

Once obtained, the Graph instance provides direct or indirect access to most of the functionality available within py2neo.

Note that py2neo does not support routing with a Neo4j causal cluster. For this functionality, please use the official Neo4j Driver for Python.

auto(readonly=False, after=None, metadata=None, timeout=None)[source]

Begin a new auto-commit GraphTransaction.

Parameters
  • readonly

  • after

  • metadata

  • timeout

begin(autocommit=False, readonly=False, after=None, metadata=None, timeout=None)[source]

Begin a new GraphTransaction.

Parameters
  • autocommit – if True, the transaction will automatically commit after the first operation

  • readonly

  • after

  • metadata

  • timeout

call(procedure, *args)[source]

Call a procedure by name.

For example:
>>> from py2neo import Graph
>>> g = Graph()
>>> g.call("dbms.components")
 name         | versions  | edition
--------------|-----------|-----------
 Neo4j Kernel | ['4.0.2'] | community
Parameters
  • procedure – fully qualified procedure name

  • args – positional arguments to pass to the procedure

Returns

Cursor object wrapping the result

create(subgraph)[source]

Run a GraphTransaction.create() operation within a GraphTransaction.

Parameters

subgraph – a Node, Relationship or other Subgraph

delete(subgraph)[source]

Run a GraphTransaction.delete() operation within an autocommit GraphTransaction. To delete only the relationships, use the separate() method.

Note that only entities which are bound to corresponding remote entities though the graph and identity attributes will trigger a deletion.

Parameters

subgraph – a Node, Relationship or other Subgraph object

delete_all()[source]

Delete all nodes and relationships from this Graph.

Warning

This method will permanently remove all nodes and relationships from the graph and cannot be undone.

evaluate(cypher, parameters=None, **kwparameters)[source]

Run a GraphTransaction.evaluate() operation within an autocommit GraphTransaction.

Parameters
  • cypher – Cypher statement

  • parameters – dictionary of parameters

Returns

first value from the first record returned or None.

exists(subgraph)[source]

Run a GraphTransaction.exists() operation within an autocommit GraphTransaction.

Parameters

subgraph – a Node, Relationship or other Subgraph object

Returns

match(nodes=None, r_type=None, limit=None)[source]

Match and return all relationships with specific criteria.

For example, to find all of Alice’s friends:

for rel in graph.match((alice, ), r_type="FRIEND"):
    print(rel.end_node["name"])
Parameters
  • nodes – Sequence or Set of start and end nodes (None means any node); a Set implies a match in any direction

  • r_type – type of relationships to match (None means any type)

  • limit – maximum number of relationships to match (None means unlimited)

match_one(nodes=None, r_type=None)[source]

Match and return one relationship with specific criteria.

Parameters
  • nodes – Sequence or Set of start and end nodes (None means any node); a Set implies a match in any direction

  • r_type – type of relationships to match (None means any type)

merge(subgraph, label=None, *property_keys)[source]

Run a GraphTransaction.merge() operation within an autocommit GraphTransaction.

The example code below shows a simple merge for a new relationship between two new nodes:

>>> from py2neo import Graph, Node, Relationship
>>> g = Graph()
>>> a = Node("Person", name="Alice", age=33)
>>> b = Node("Person", name="Bob", age=44)
>>> KNOWS = Relationship.type("KNOWS")
>>> g.merge(KNOWS(a, b), "Person", "name")

Following on, we then create a third node (of a different type) to which both the original nodes connect:

>>> c = Node("Company", name="ACME")
>>> c.__primarylabel__ = "Company"
>>> c.__primarykey__ = "name"
>>> WORKS_FOR = Relationship.type("WORKS_FOR")
>>> g.merge(WORKS_FOR(a, c) | WORKS_FOR(b, c))

For details of how the merge algorithm works, see the GraphTransaction.merge() method. Note that this is different to a Cypher MERGE.

Parameters
  • subgraph – a Node, Relationship or other Subgraph object

  • label – label on which to match any existing nodes

  • property_keys – property keys on which to match any existing nodes

property nodes

Obtain a NodeMatcher for this graph.

This can be used to find nodes that match given criteria:

>>> graph = Graph()
>>> graph.nodes[1234]
(_1234:Person {name: 'Alice'})
>>> graph.nodes.get(1234)
(_1234:Person {name: 'Alice'})
>>> graph.nodes.match("Person", name="Alice").first()
(_1234:Person {name: 'Alice'})

Nodes can also be efficiently counted using this attribute:

>>> len(graph.nodes)
55691
>>> len(graph.nodes.match("Person", age=33))
12
play(work, args=None, kwargs=None, after=None, metadata=None, timeout=None)[source]

Call a function representing a transactional unit of work.

The function must always accept a GraphTransaction object as its first argument. Additional arguments can be passed though the args and kwargs arguments of this method.

If the function has a readonly attribute, and this is set to a truthy value, then it will be executed in a read-only environment, if possible.

If the function has a timeout attribute, and no timeout argument is passed to this method call, then the value of the function attribute will be used instead for setting the timeout.

Parameters
  • work – function containing the unit of work

  • args – sequence of additional positional arguments to pass into the function

  • kwargs – mapping of additional keyword arguments to pass into the function

  • afterBookmark or tuple of Bookmark objects marking the point in transactional history after which this unit of work should be played

  • metadata – user metadata to attach to this transaction

  • timeout – timeout for transaction execution

pull(subgraph)[source]

Pull data to one or more entities from their remote counterparts.

Parameters

subgraph – the collection of nodes and relationships to pull

push(subgraph)[source]

Push data from one or more entities to their remote counterparts.

Parameters

subgraph – the collection of nodes and relationships to push

property relationships

Obtain a RelationshipMatcher for this graph.

This can be used to find relationships that match given criteria as well as efficiently count relationships.

run(cypher, parameters=None, **kwparameters)[source]

Run a GraphTransaction.run() operation within an autocommit GraphTransaction.

Parameters
  • cypher – Cypher statement

  • parameters – dictionary of parameters

  • kwparameters – extra keyword parameters

Returns

schema = None

The Schema resource for this Graph.

separate(subgraph)[source]

Run a GraphTransaction.separate() operation within an autocommit GraphTransaction.

Note that only relationships which are bound to corresponding remote relationships though the graph and identity attributes will trigger a deletion.

Parameters

subgraph – a Node, Relationship or other Subgraph

service = None

The GraphService to which this Graph belongs.

class py2neo.database.Schema(graph)[source]

The schema resource attached to a Graph instance.

create_index(label, *property_keys)[source]

Create a schema index for a label and property key combination.

create_uniqueness_constraint(label, property_key)[source]

Create a node uniqueness constraint for a given label and property key.

While indexes support the use of composite keys, unique constraints may only be tied to a single property key.

drop_index(label, *property_keys)[source]

Remove label index for a given property key.

drop_uniqueness_constraint(label, property_key)[source]

Remove the node uniqueness constraint for a given label and property key.

get_indexes(label)[source]

Fetch a list of indexed property keys for a label.

get_uniqueness_constraints(label)[source]

Fetch a list of unique constraints for a label. Each constraint is the name of a single property key.

property node_labels

The set of node labels currently defined within the graph.

property relationship_types

The set of relationship types currently defined within the graph.

2.2.1. The SystemGraph

class py2neo.database.SystemGraph(uri, **settings)[source]

A subclass of Graph that provides access to the system database for the remote DBMS. This is only available in Neo4j 4.0 and above.

2.3. Transactions

class py2neo.database.GraphTransaction(autocommit=False)[source]

A logical context for one or more graph operations.

commit()[source]

Commit the transaction.

create(subgraph)[source]

Create remote nodes and relationships that correspond to those in a local subgraph. Any entities in subgraph that are already bound to remote entities will remain unchanged, those which are not will become bound to their newly-created counterparts.

For example:

>>> from py2neo import Graph, Node, Relationship
>>> g = Graph()
>>> tx = g.begin()
>>> a = Node("Person", name="Alice")
>>> tx.create(a)
>>> b = Node("Person", name="Bob")
>>> ab = Relationship(a, "KNOWS", b)
>>> tx.create(ab)
>>> tx.commit()
>>> g.exists(ab)
True
Parameters

subgraph – a Node, Relationship or other creatable object

delete(subgraph)[source]

Delete the remote nodes and relationships that correspond to those in a local subgraph. To delete only the relationships, use the separate() method.

Parameters

subgraph – a Node, Relationship or other Subgraph

evaluate(cypher, parameters=None, **kwparameters)[source]

Execute a single Cypher statement and return the value from the first column of the first record.

Parameters
  • cypher – Cypher statement

  • parameters – dictionary of parameters

Returns

single return value or None

exists(subgraph)[source]

Determine whether one or more entities all exist within the graph. Note that if any nodes or relationships in subgraph are not bound to remote counterparts, this method will return False.

Parameters

subgraph – a Node, Relationship or other Subgraph

Returns

True if all entities exist remotely, False otherwise

finished()[source]

Indicates whether or not this transaction has been completed or is still open.

merge(subgraph, primary_label=None, primary_key=None)[source]

Create or update the nodes and relationships of a local subgraph in the remote database. Note that the functionality of this operation is not strictly identical to the Cypher MERGE clause, although there is some overlap.

Each node and relationship in the local subgraph is merged independently, with nodes merged first and relationships merged second.

For each node, the merge is carried out by comparing that node with a potential remote equivalent on the basis of a single label and property value. If no remote match is found, a new node is created; if a match is found, the labels and properties of the remote node are updated. The label and property used for comparison are determined by the primary_label and primary_key arguments but may be overridden for individual nodes by the of __primarylabel__ and __primarykey__ attributes on the node itself.

For each relationship, the merge is carried out by comparing that relationship with a potential remote equivalent on the basis of matching start and end nodes plus relationship type. If no remote match is found, a new relationship is created; if a match is found, the properties of the remote relationship are updated.

Parameters
  • subgraph – a Node, Relationship or other Subgraph object

  • primary_label – label on which to match any existing nodes

  • primary_key – property key(s) on which to match any existing nodes

pull(subgraph)[source]

Update local entities from their remote counterparts.

For any nodes and relationships that exist in both the local Subgraph and the remote Graph, pull properties and node labels into the local copies. This operation does not create or delete any entities.

Parameters

subgraph – a Node, Relationship or other Subgraph

push(subgraph)[source]

Update remote entities from their local counterparts.

For any nodes and relationships that exist in both the local Subgraph and the remote Graph, push properties and node labels into the remote copies. This operation does not create or delete any entities.

Parameters

subgraph – a Node, Relationship or other Subgraph

rollback()[source]

Roll back the current transaction, undoing all actions previously taken.

run(cypher, parameters=None, **kwparameters)[source]

Send a Cypher statement to the server for execution and return a Cursor for navigating its result.

Parameters
  • cypher – Cypher statement

  • parameters – dictionary of parameters

Returns

Cursor object

separate(subgraph)[source]

Delete the remote relationships that correspond to those in a local subgraph. This leaves any nodes untouched.

Parameters

subgraph – a Node, Relationship or other Subgraph

2.4. Cypher Results

class py2neo.database.Cursor(result, hydrant=None, entities=None)[source]

A Cursor is a navigator for a stream of records.

A cursor can be thought of as a window onto an underlying data stream. All cursors in py2neo are “forward-only”, meaning that navigation starts before the first record and may proceed only in a forward direction.

It is not generally necessary for application code to instantiate a cursor directly as one will be returned by any Cypher execution method. However, cursor creation requires only a DataSource object which contains the logic for how to access the source data that the cursor navigates.

Many simple cursor use cases require only the forward() method and the current attribute. To navigate through all available records, a while loop can be used:

while cursor.forward():
    print(cursor.current["name"])

If only the first record is of interest, a similar if structure will do the job:

if cursor.forward():
    print(cursor.current["name"])

To combine forward and current into a single step, use the built-in py:func:next function:

print(next(cursor)["name"])

Cursors are also iterable, so can be used in a loop:

for record in cursor:
    print(record["name"])

For queries that are expected to return only a single value within a single record, use the evaluate() method. This will return the first value from the next record or None if neither the field nor the record are present:

print(cursor.evaluate())
close()[source]

Close this cursor and free up all associated resources.

property current

Returns the current record or None if no record has yet been selected.

data()[source]

Consume and extract the entire result as a list of dictionaries.

>>> from py2neo import Graph
>>> graph = Graph()
>>> graph.run("MATCH (a:Person) RETURN a.name, a.born LIMIT 4").data()
[{'a.born': 1964, 'a.name': 'Keanu Reeves'},
 {'a.born': 1967, 'a.name': 'Carrie-Anne Moss'},
 {'a.born': 1961, 'a.name': 'Laurence Fishburne'},
 {'a.born': 1960, 'a.name': 'Hugo Weaving'}]
Returns

the full query result

Return type

list of dict

evaluate(field=0)[source]

Return the value of the first field from the next record (or the value of another field if explicitly specified).

This method attempts to move the cursor one step forward and, if successful, selects and returns an individual value from the new current record. By default, this value will be taken from the first value in that record but this can be overridden with the field argument, which can represent either a positional index or a textual key.

If the cursor cannot be moved forward or if the record contains no values, None will be returned instead.

This method is particularly useful when it is known that a Cypher query returns only a single value.

Parameters

field – field to select value from (optional)

Returns

value of the field or None

Example

>>> from py2neo import Graph
>>> g = Graph()
>>> g.run("MATCH (a) WHERE a.email=$x RETURN a.name", x="bob@acme.com").evaluate()
'Bob Robertson'
forward(amount=1)[source]

Attempt to move the cursor one position forward (or by another amount if explicitly specified). The cursor will move position by up to, but never more than, the amount specified. If not enough scope for movement remains, only that remainder will be consumed. The total amount moved is returned.

Parameters

amount – the amount to move the cursor

Returns

the amount that the cursor was able to move

keys()[source]

Return the field names for the records in the stream.

plan()[source]

Return the plan returned with this result, if any.

preview(limit=1)[source]

Construct a Table containing a preview of upcoming records, including no more than the given limit.

Parameters

limit – maximum number of records to include in the preview

Returns

Table containing the previewed records

stats()[source]

Return the query statistics.

This contains details of the activity undertaken by the database kernel for the query, such as the number of entities created or deleted. Specifically, this returns a CypherStats object.

>>> from py2neo import Graph
>>> g = Graph()
>>> g.run("CREATE (a:Person) SET a.name = 'Alice'").stats()
constraints_added: 0
constraints_removed: 0
contained_updates: True
indexes_added: 0
indexes_removed: 0
labels_added: 1
labels_removed: 0
nodes_created: 1
nodes_deleted: 0
properties_set: 1
relationships_created: 0
relationships_deleted: 0
summary()[source]

Return the result summary.

to_data_frame(index=None, columns=None, dtype=None)[source]

Consume and extract the entire result as a pandas.DataFrame.

>>> from py2neo import Graph
>>> graph = Graph()
>>> graph.run("MATCH (a:Person) RETURN a.name, a.born LIMIT 4").to_data_frame()
   a.born              a.name
0    1964        Keanu Reeves
1    1967    Carrie-Anne Moss
2    1961  Laurence Fishburne
3    1960        Hugo Weaving

Note

This method requires pandas to be installed.

Parameters
  • index – Index to use for resulting frame.

  • columns – Column labels to use for resulting frame.

  • dtype – Data type to force.

Warns

If pandas is not installed

Returns

DataFrame object.

to_matrix(mutable=False)[source]

Consume and extract the entire result as a sympy.Matrix.

Note

This method requires sympy to be installed.

Parameters

mutable

Returns

Matrix object.

to_ndarray(dtype=None, order='K')[source]

Consume and extract the entire result as a numpy.ndarray.

Note

This method requires numpy to be installed.

Parameters
  • dtype

  • order

Warns

If numpy is not installed

Returns

ndarray object.

to_series(field=0, index=None, dtype=None)[source]

Consume and extract one field of the entire result as a pandas.Series.

Note

This method requires pandas to be installed.

Parameters
  • field

  • index

  • dtype

Warns

If pandas is not installed

Returns

Series object.

to_subgraph()[source]

Consume and extract the entire result as a Subgraph containing the union of all the graph structures within.

Returns

Subgraph object

to_table()[source]

Consume and extract the entire result as a Table object.

Returns

the full query result

class py2neo.database.CypherStats(**stats)[source]

Container for a set of statistics drawn from Cypher query execution.

Each value can be accessed as either an attribute or via a string index. This class implements Mapping to allow it to be used as a dictionary.

constraints_added = 0

Number of constraints added.

constraints_removed = 0

Number of constraints removed.

contained_updates = False

Boolean flag to indicate whether or not the query contained an update.

indexes_added = 0

Number of indexes added.

indexes_removed = 0

Number of indexes removed.

keys()[source]

Full list of the key or attribute names of the statistics available.

labels_added = 0

Number of node labels added.

labels_removed = 0

Number of node labels removed.

nodes_created = 0

Number of nodes created.

nodes_deleted = 0

Number of nodes deleted.

properties_set = 0

Number of property values set.

relationships_created = 0

Number of relationships created.

relationships_deleted = 0

Number of relationships deleted.

2.5. Errors & Warnings

class py2neo.database.GraphError(*args, **kwargs)[source]
class py2neo.database.ClientError(*args, **kwargs)[source]

The Client sent a bad request - changing the request might yield a successful outcome.

class py2neo.database.DatabaseError(*args, **kwargs)[source]

The database failed to service the request.

class py2neo.database.TransientError(*args, **kwargs)[source]

The database cannot service the request right now, retrying later might yield a successful outcome.

class py2neo.database.GraphTransactionError(*args, **kwargs)[source]

Raised when actions are attempted against a GraphTransaction that is no longer available for use, or a transaction is otherwise invalid.