2. py2neo.database – Graph Databases

The py2neo.database package contains classes and functions required to interact with a Neo4j server. The most important of these 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, 10) AS n RETURN n, n * n as n_sq").dump()
 n   n_sq
----------
  1     1
  2     4
  3     9
  4    16
  5    25
  6    36
  7    49
  8    64
  9    81
 10   100

Note

The previous version of py2neo allowed Cypher execution through Graph.cypher.execute(). This facility is now instead accessible via Graph.run() and returns a lazily-evaluated Cursor rather than an eagerly-evaluated RecordList.

2.1. The Graph

class py2neo.database.Graph(*uris, **settings)

The Graph class represents a Neo4j graph database. Connection details are provided using URIs and/or individual settings. For any given Graph, the following protocol combinations are supported:

• HTTP
• HTTPS
• Bolt + HTTP
• Bolt/TLS + HTTPS

Note that either HTTP or HTTPS must be enabled to allow for discovery and for some legacy features to be supported.

The full set of settings supported are:

Keyword	Description	Type(s)	Default
bolt	Use Bolt* protocol (None means autodetect)	bool, None	None
secure	Use a secure connection (Bolt/TLS + HTTPS)	bool	False
host	Database server host name	str	'localhost'
http_port	Port for HTTP traffic	int	7474
https_port	Port for HTTPS traffic	int	7473
bolt_port	Port for Bolt traffic	int	7687
user	User to authenticate as	str	'neo4j'
password	Password to use for authentication	str	no default

* The new Bolt binary protocol is the successor to HTTP and available in Neo4j 3.0 and above.

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

>>> from py2neo import Graph
>>> graph_1 = Graph()
>>> graph_2 = Graph(host="localhost")
>>> graph_3 = Graph("http://localhost:7474/db/data/")

Once obtained, the Graph instance provides direct or indirect access to most of the functionality available within py2neo. If Bolt is available (Neo4j 3.0 and above) and Bolt auto-detection is enabled, this will be used for Cypher queries instead of HTTP.

begin(autocommit=False)

Begin a new Transaction.

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

create(subgraph)

Run a Transaction.create() operation within an autocommit Transaction.

Parameters:subgraph – a Node, Relationship or other Subgraph

data(statement, parameters=None, **kwparameters)

Run a Transaction.run() operation within an autocommit Transaction and extract the data as a list of dictionaries.

For example:

>>> from py2neo import Graph
>>> graph = Graph(password="excalibur")
>>> graph.data("MATCH (a:Person) RETURN a.name, a.born LIMIT 4")
[{'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'}]

The extracted data can then be easily passed into an external data handler such as a pandas.DataFrame for subsequent processing:

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

See also

Cursor.data()

Parameters:

• statement – Cypher statement
• parameters – dictionary of parameters
• kwparameters – additional keyword parameters

Returns:

the full query result

Return type:

list of dict

dbms

The database management system to which this Graph instance belongs.

degree(subgraph)

Run a Transaction.degree() operation within an autocommit Transaction.

Parameters:subgraph – a Node, Relationship or other Subgraph object Returns:the total degree of all nodes in the subgraph

delete(subgraph)

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

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

delete_all()

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(statement, parameters=None, **kwparameters)

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

Parameters:

• statement – Cypher statement
• parameters – dictionary of parameters

Returns:

first value from the first record returned or None.

exists(subgraph)

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

Parameters:subgraph – a Node, Relationship or other Subgraph object Returns:

find(**kwargs)

Yield all nodes with a given label, optionally filtering by property key and value.

Parameters:

• label – node label to match
• property_key – property key to match
• property_value – property value to match; if a tuple or set is provided, any of these values may be matched
• limit – maximum number of nodes to match

find_one(**kwargs)

Find a single node by label and optional property. This method is intended to be used with a unique constraint and does not fail if more than one matching node is found.

Parameters:

• label – node label to match
• property_key – property key to match
• property_value – property value to match; if a tuple or set is provided, any of these values may be matched

match(start_node=None, rel_type=None, end_node=None, bidirectional=False, limit=None)

Match and return all relationships with specific criteria.

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

for rel in graph.match(start_node=alice, rel_type="FRIEND"):
    print(rel.end_node()["name"])

Parameters:

• start_node – start node of relationships to match (None means any node)
• rel_type – type of relationships to match (None means any type)
• end_node – end node of relationships to match (None means any node)
• bidirectional – True if reversed relationships should also be included
• limit – maximum number of relationships to match (None means unlimited)

match_one(start_node=None, rel_type=None, end_node=None, bidirectional=False)

Match and return one relationship with specific criteria.

Parameters:

• start_node – start node of relationships to match (None means any node)
• rel_type – type of relationships to match (None means any type)
• end_node – end node of relationships to match (None means any node)
• bidirectional – True if reversed relationships should also be included

merge(subgraph, label=None, *property_keys)

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

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

node(id_)

Fetch a node by ID. This method creates an object representing the remote node with the ID specified but fetches no data from the server. For this reason, there is no guarantee that the entity returned actually exists.

Parameters:id –

node_labels

The set of node labels currently defined within the graph.

open_browser()

Open a page in the default system web browser pointing at the Neo4j browser application for this graph.

pull(subgraph)

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

Parameters:subgraph – the collection of nodes and relationships to pull

push(subgraph)

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

Parameters:subgraph – the collection of nodes and relationships to push

relationship(id_)

Fetch a relationship by ID.

Parameters:id –

relationship_types

The set of relationship types currently defined within the graph.

run(statement, parameters=None, **kwparameters)

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

Parameters:

• statement – Cypher statement
• parameters – dictionary of parameters

Returns:

schema

The schema resource for this graph.

Return type:Schema

separate(subgraph)

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

Parameters:subgraph – a Node, Relationship or other Subgraph

class py2neo.database.Schema(uri)

The schema resource attached to a Graph instance.

create_index(label, property_key)

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

create_uniqueness_constraint(label, property_key)

Create a uniqueness constraint for a label.

drop_index(label, property_key)

Remove label index for a given property key.

drop_uniqueness_constraint(label, property_key)

Remove the uniqueness constraint for a given property key.

get_indexes(label)

Fetch a list of indexed property keys for a label.

get_uniqueness_constraints(label)

Fetch a list of unique constraints for a label.

2.2. Transactions

class py2neo.database.Transaction(autocommit=False)

A transaction is a transient resource that allows multiple Cypher statements to be executed within a single server transaction.

commit()

Commit the transaction.

create(subgraph)

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

degree(subgraph)

Return the total number of relationships attached to all nodes in a subgraph.

Parameters:subgraph – a Node, Relationship or other Subgraph Returns:the total number of distinct relationships

delete(subgraph)

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(statement, parameters=None, **kwparameters)

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

Parameters:

• statement – Cypher statement
• parameters – dictionary of parameters

Returns:

single return value or None

exists(subgraph)

Determine whether one or more graph entities all exist within the database. 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()

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

merge(subgraph, primary_label=None, primary_key=None)

Merge nodes and relationships from a local subgraph into the database. Each node and relationship 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 label and property value. If no remote match is found, a new node is created. The label and property to use for comparison are determined by primary_label and primary_key but may be overridden for individual nodes by the presence of __primarylabel__ and __primarykey__ attributes on the node itself. Note that multiple property keys may be specified by using a tuple.

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.

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

process()

Send all pending statements to the server for processing.

rollback()

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

run(statement, parameters=None, **kwparameters)

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

Parameters:

• statement – Cypher statement
• parameters – dictionary of parameters

Returns:

Cursor object

separate(subgraph)

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.3. Cursors

class py2neo.database.Cursor(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 next:

print(cursor.next()["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()

Close this cursor and free up all associated resources.

current()

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

data()

Consume and extract the entire result as a list of dictionaries. This method generates a self-contained set of result data using only Python-native data types.

>>> from py2neo import Graph
>>> graph = Graph(password="excalibur")
>>> 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'}]

The extracted data can then be easily passed into an external data handler such as a pandas.DataFrame for subsequent processing:

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

Similarly, to output the result data as a JSON-formatted string:

>>> import json
>>> json.dumps(graph.run("UNWIND range(1, 3) AS n RETURN n").data())
'[{"n": 1}, {"n": 2}, {"n": 3}]'

Returns:the full query result Return type:list of dict

dump(out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Consume all records from this cursor and write in tabular form to the console.

Parameters:out – the channel to which output should be dumped

evaluate(field=0)

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)

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

Return the field names for the records in the stream.

next()

Returns the next record in the stream, or raises StopIteration if no more records are available.

cursor.current if cursor.forward() else None

stats()

Return the query statistics.

class py2neo.database.Record

A Record holds a collection of result values that are both indexed by position and keyed by name. A Record instance can therefore be seen as a combination of a tuple and a 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()

Return a dict representation of the contained keys and values.

items()

Return a list of key-value pairs contained within 2-tuples.

keys()

Return a tuple of names by which the contained values are keyed.

subgraph()

Convert to a Subgraph by collecting all nodes and relationships contained within. If there are none, None is returned.

values()

Return a tuple of the contained values.

2.4. The DBMS

class py2neo.database.DBMS

Accessor for the entire database management system belonging to a Neo4j server installation. This corresponds to the root URI in the HTTP API.

An explicit URI can be passed to the constructor:

>>> from py2neo import DBMS
>>> my_dbms = DBMS("http://myserver:7474/")

Alternatively, the default value of http://localhost:7474/ is used:

>>> default_dbms = DBMS()
>>> default_dbms
<DBMS uri='http://localhost:7474/'>

config

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

database_name

Return the name of the active Neo4j database.

graph

The default graph database exposed by this database management system.

Return type:Graph

kernel_start_time

Return the time from which this Neo4j instance was in operational mode.

kernel_version

Return the version of Neo4j.

primitive_counts

Return a dictionary of estimates of the numbers of different kinds of Neo4j primitives.

store_creation_time

Return the time when this Neo4j graph store was created.

store_directory

Return the location of the Neo4j store.

store_file_sizes

Return a dictionary of file sizes for each file in the Neo4j graph store.

store_id

Return an identifier that, together with store creation time, uniquely identifies this Neo4j graph store.

supports_auth

Returns True if auth is supported by this version of Neo4j, False otherwise.

supports_bolt

Returns True if Bolt is supported by this version of Neo4j, False otherwise.

supports_detach_delete

Returns True if Cypher DETACH DELETE is supported by this version of Neo4j, False otherwise.

2.5. Security

class py2neo.database.auth.ServerAddress(*uris, **settings)

A DBMS or graph database address.

py2neo.database.auth.authenticate(host_port, user, password)

Set HTTP basic authentication values for specified host_port for use with both Neo4j 2.2 built-in authentication as well as if a database server is behind (for example) an Apache proxy. The code below shows a simple example:

from py2neo import authenticate, Graph

# set up authentication parameters
authenticate("camelot:7474", "arthur", "excalibur")

# connect to authenticated graph database
graph = Graph("http://camelot:7474/db/data/")

Note: a host_port can be either a server name or a server name and port number but must match exactly that used within the Graph URI.

Parameters:

• host_port – the host and optional port requiring authentication (e.g. “bigserver”, “camelot:7474”)
• user – the user name to authenticate as
• password – the password

py2neo.database.auth.keyring = {}

Authentication dictionary mapping server addresses to auth details

py2neo.database.auth.register_server(*uris, **settings)

Register server address details and return a ServerAddress instance.

Parameters:

• uris –
• settings –

Returns:

2.6. Cypher Utilities

class py2neo.database.selection.NodeSelector(graph)

A NodeSelector can be used to locate nodes that fulfil a specific set of criteria. Typically, a single node can be identified passing a specific label and property key-value pair. However, any number of labels and any condition supported by the Cypher WHERE clause is allowed.

For a simple selection by label and property:

>>> from py2neo import Graph, NodeSelector
>>> graph = Graph()
>>> selector = NodeSelector(graph)
>>> selected = selector.select("Person", name="Keanu Reeves")
>>> list(selected)
[(f9726ea:Person {born:1964,name:"Keanu Reeves"})]

For a more comprehensive selection using Cypher expressions, the NodeSelection.where() method can be used for further refinement. Here, the underscore character can be used to refer to the node being filtered:

>>> selected = selector.select("Person").where("_.name =~ 'J.*'", "1960 <= _.born < 1970")
>>> list(selected)
[(a03f6eb:Person {born:1967,name:"James Marshall"}),
 (e59993d:Person {born:1966,name:"John Cusack"}),
 (c44901e:Person {born:1960,name:"John Goodman"}),
 (b141775:Person {born:1965,name:"John C. Reilly"}),
 (e40244b:Person {born:1967,name:"Julia Roberts"})]

The underlying query is only evaluated when the selection undergoes iteration or when a specific evaluation method is called (such as NodeSelection.first()). This means that a NodeSelection instance may be reused before and after a data changes for different results.

select(*labels, **properties)

Describe a basic node selection using labels and property equality.

Parameters:

• labels – node labels to match
• properties – set of property keys and values to match

Returns:

NodeSelection instance

class py2neo.database.selection.NodeSelection(graph, labels=frozenset(), conditions=(), order_by=(), skip=None, limit=None)

An immutable set of node selection criteria.

first()

Evaluate the selection and return the first Node selected or None if no matching nodes are found.

Returns:a single matching Node or None

limit(amount)

Limit the selection to at most amount nodes.

Parameters:amount – maximum number of nodes to select Returns:refined selection object

order_by(*fields)

Order by the fields or field expressions specified.

To refer to the current node within a field or field expression, use the underscore character _. For example:

selection.order_by("_.name", "max(_.a, _.b)")

Parameters:fields – fields or field expressions to order by Returns:refined selection object

skip(amount)

Skip the first amount nodes in the result.

Parameters:amount – number of nodes to skip Returns:refined selection object

where(*conditions, **properties)

Create a new selection based on this selection. The criteria specified for refining the selection consist of conditions and properties. Conditions are individual Cypher expressions that would be found in a WHERE clause; properties are used as exact matches for property values.

To refer to the current node within a condition expression, use the underscore character _. For example:

selection.where("_.name =~ 'J.*")

Simple property equalities can also be specified:

selection.where(born=1976)

Parameters:

• conditions – Cypher expressions to add to the selection WHERE clause
• properties – exact property match keys and values

Returns:

refined selection object

py2neo.database.cypher.cypher_escape(identifier)

Escape a Cypher identifier in backticks.

>>> cypher_escape("this is a `label`")
'`this is a ``label```'

Parameters:identifier –

py2neo.database.cypher.cypher_repr(obj)

Generate the Cypher representation of an object.

Parameters:obj –

2.7. Debugging

py2neo.watch(logger, level=None, out=None)

Dump log messages to standard output.

To watch Bolt traffic:

>>> from py2neo import watch
>>> watch("neo4j.bolt")

To watch HTTP traffic:

>>> from py2neo import watch
>>> watch("neo4j.http")

Parameters:

• logger – logger name
• level – logging level (default INFO)
• out – output channel (default stdout)

2.8. Errors & Warnings

exception py2neo.database.status.ClientError(*args, **kwargs)

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

exception py2neo.database.status.ConstraintError(*args, **kwargs)

exception py2neo.database.status.CypherSyntaxError(*args, **kwargs)

exception py2neo.database.status.CypherTypeError(*args, **kwargs)

exception py2neo.database.status.DatabaseError(*args, **kwargs)

The database failed to service the request.

exception py2neo.database.status.Forbidden(*args, **kwargs)

exception py2neo.database.status.GraphError(*args, **kwargs)

exception py2neo.database.status.TransientError(*args, **kwargs)

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

exception py2neo.database.status.Unauthorized(*args, **kwargs)