API Documentation¶

GraphDatabase¶

Driver Construction¶

The neo4j.Driver construction is via a classmethod on the neo4j.GraphDatabase class.

class neo4j.GraphDatabase¶

Accessor for neo4j.Driver construction.

classmethod driver(uri, *, auth=None, **config)¶

Create a driver.

Parameters

uri – the connection URI for the driver, see URI for available URIs.
auth – the authentication details, see Auth for available authentication details.
config – driver configuration key-word arguments, see Driver Configuration for available key-word arguments.

Returns

Neo4jDriver or BoltDriver

Example, driver creation:

from neo4j import GraphDatabase

uri = "neo4j://example.com:7687"
driver = GraphDatabase.driver(uri, auth=("neo4j", "password"), max_connection_lifetime=1000)

driver.close()  # close the driver object

For basic auth, this can be a simple tuple, for example:

auth = ("neo4j", "password")

This will implicitly create a neo4j.Auth with a scheme="basic"

Example, with block context:

from neo4j import GraphDatabase

uri = "neo4j://example.com:7687"
with GraphDatabase.driver(uri, auth=("neo4j", "password")) as driver:
    # use the driver

URI¶

On construction, the scheme of the URI determines the type of neo4j.Driver object created.

Available valid URIs:

bolt://host[:port]
bolt+ssc://host[:port]
bolt+s://host[:port]
neo4j://host[:port][?routing_context]
neo4j+ssc://host[:port][?routing_context]
neo4j+s://host[:port][?routing_context]

uri = "bolt://example.com:7687"

uri = "neo4j://example.com:7687"

Each supported scheme maps to a particular neo4j.Driver subclass that implements a specific behaviour.

URI Scheme	Driver Object and Setting
bolt	BoltDriver with no encryption.
bolt+ssc	BoltDriver with encryption (accepts self signed certificates).
bolt+s	BoltDriver with encryption (accepts only certificates signed by a certificate authority), full certificate checks.
neo4j	Neo4jDriver with no encryption.
neo4j+ssc	Neo4jDriver with encryption (accepts self signed certificates).
neo4j+s	Neo4jDriver with encryption (accepts only certificates signed by a certificate authority), full certificate checks.

Note

See https://neo4j.com/docs/operations-manual/current/configuration/ports/ for Neo4j ports.

Auth¶

To authenticate with Neo4j the authentication details are supplied at driver creation.

The auth token is an object of the class neo4j.Auth containing the details.

class neo4j.Auth(scheme, principal, credentials, realm=None, **parameters)¶

Container for auth details.

Parameters

scheme (str) – specifies the type of authentication, examples: “basic”, “kerberos”
principal (str) – specifies who is being authenticated
credentials (str) – authenticates the principal
realm (str) – specifies the authentication provider
parameters (str) – extra key word parameters passed along to the authentication provider

Example:

import neo4j

auth = neo4j.Auth(scheme="basic", principal="neo4j", credentials="password")

Auth Token Helper Functions¶

Alternatively, one of the auth token helper functions can be used.

neo4j.basic_auth(user, password, realm=None)¶

Generate a basic auth token for a given user and password.

This will set the scheme to “basic” for the auth token.

Parameters

user – user name, this will set the principal
password – current password, this will set the credentials
realm – specifies the authentication provider

Returns

auth token for use with GraphDatabase.driver()

Return type

neo4j.Auth

neo4j.kerberos_auth(base64_encoded_ticket)¶

Generate a kerberos auth token with the base64 encoded ticket

This will set the scheme to “kerberos” for the auth token.

Parameters: base64_encoded_ticket – a base64 encoded service ticket, this will set the credentials
Returns: auth token for use with GraphDatabase.driver()
Return type: neo4j.Auth

neo4j.custom_auth(principal, credentials, realm, scheme, **parameters)¶

Generate a custom auth token.

Parameters

principal – specifies who is being authenticated
credentials – authenticates the principal
realm – specifies the authentication provider
scheme – specifies the type of authentication
parameters – extra key word parameters passed along to the authentication provider

Returns

auth token for use with GraphDatabase.driver()

Return type

neo4j.Auth

Driver¶

Every Neo4j-backed application will require a neo4j.Driver object.

This object holds the details required to establish connections with a Neo4j database, including server URIs, credentials and other configuration. neo4j.Driver objects hold a connection pool from which neo4j.Session objects can borrow connections. Closing a driver will immediately shut down all connections in the pool.

class neo4j.Driver¶

Base class for all types of neo4j.Driver, instances of which are used as the primary access point to Neo4j.

session(**config)¶

Create a session, see Session Construction

Parameters: config – session configuration key-word arguments, see Session Configuration for available key-word arguments.
Returns: new neo4j.Session object

close()¶: Shut down, closing any open connections in the pool.

Driver Configuration¶

Additional configuration can be provided via the neo4j.Driver constructor.

connection_acquisition_timeout
connection_timeout
encrypted
keep_alive
max_connection_lifetime
max_connection_pool_size
max_transaction_retry_time
resolver
trust
user_agent

`connection_acquisition_timeout`¶

The maximum amount of time in seconds a session will wait when requesting a connection from the connection pool. Since the process of acquiring a connection may involve creating a new connection, ensure that the value of this configuration is higher than the configured connection_timeout.

Type: float
Default: 60.0

`connection_timeout`¶

The maximum amount of time in seconds to wait for a TCP connection to be established.

Type: float
Default: 30.0

`encrypted`¶

Specify whether to use an encrypted connection between the driver and server.

Type: bool
Default: False

`keep_alive`¶

Specify whether TCP keep-alive should be enabled.

Type: bool
Default: True

This is experimental. (See Filter Warnings)

`max_connection_lifetime`¶

The maximum duration in seconds that the driver will keep a connection for before being removed from the pool.

Type: float
Default: 3600

`max_connection_pool_size`¶

The maximum total number of connections allowed, per host (i.e. cluster nodes), to be managed by the connection pool.

Type: int
Default: 100

`max_transaction_retry_time`¶

The maximum amount of time in seconds that a managed transaction will retry before failing.

Type: float
Default: 30.0

`resolver`¶

A custom resolver function to resolve host and port values ahead of DNS resolution. This function is called with a 2-tuple of (host, port) and should return an iterable of 2-tuples (host, port).

If no custom resolver function is supplied, the internal resolver moves straight to regular DNS resolution.

For example:

from neo4j import GraphDatabase

def custom_resolver(socket_address):
    if socket_address == ("example.com", 9999):
        yield "::1", 7687
        yield "127.0.0.1", 7687
    else:
        from socket import gaierror
        raise gaierror("Unexpected socket address %r" % socket_address)

driver = GraphDatabase.driver("neo4j://example.com:9999",
             auth=("neo4j", "password"),
             resolver=custom_resolver)

Default: None

`trust`¶

Specify how to determine the authenticity of encryption certificates provided by the Neo4j instance on connection.

This setting does not have any effect if encrypted is set to False.

Type: neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES, neo4j.TRUST_ALL_CERTIFICATES

neo4j.TRUST_ALL_CERTIFICATES¶: Trust any server certificate (default). This ensures that communication is encrypted but does not verify the server certificate against a certificate authority. This option is primarily intended for use with the default auto-generated server certificate.

neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES¶: Trust server certificates that can be verified against the system certificate authority. This option is primarily intended for use with full certificates.

Default: neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES.

`user_agent`¶

Specify the client agent name.

Type: str
Default: The Python Driver will generate a user agent name.

Driver Object Lifetime¶

For general applications, it is recommended to create one top-level neo4j.Driver object that lives for the lifetime of the application.

For example:

from neo4j import GraphDatabase

class Application:

    def __init__(self, uri, user, password)
        self.driver = GraphDatabase.driver(uri, auth=(user, password))

    def close(self):
        self.driver.close()

Connection details held by the neo4j.Driver are immutable. Therefore if, for example, a password is changed, a replacement neo4j.Driver object must be created. More than one Driver may be required if connections to multiple databases, or connections as multiple users, are required.

neo4j.Driver objects are thread-safe but cannot be shared across processes. Therefore, multithreading should generally be preferred over multiprocessing for parallel database access. If using multiprocessing however, each process will require its own neo4j.Driver object.

BoltDriver¶

URI schemes:: bolt, bolt+ssc, bolt+s
Driver subclass:: neo4j.BoltDriver

Neo4jDriver¶

URI schemes:: neo4j, neo4j+ssc, neo4j+s
Driver subclass:: neo4j.Neo4jDriver

Sessions & Transactions¶

All database activity is co-ordinated through two mechanisms: the neo4j.Session and the neo4j.Transaction.

A neo4j.Session is a logical container for any number of causally-related transactional units of work. Sessions automatically provide guarantees of causal consistency within a clustered environment but multiple sessions can also be causally chained if required. Sessions provide the top-level of containment for database activity. Session creation is a lightweight operation and sessions are not thread safe.

Connections are drawn from the neo4j.Driver connection pool as required.

A neo4j.Transaction is a unit of work that is either committed in its entirety or is rolled back on failure.

Session Construction¶

To construct a neo4j.Session use the neo4j.Driver.session() method.

from neo4j import GraphDatabase

driver = GraphDatabase(uri, auth=(user, password))
session = driver.session()
result = session.run("MATCH (a:Person) RETURN a.name AS name")
names = [record["name"] for record in result]
session.close()
driver.close()

Sessions will often be created and destroyed using a with block context.

with driver.session() as session:
    result = session.run("MATCH (a:Person) RETURN a.name AS name")
    # do something with the result...

Sessions will often be created with some configuration settings, see Session Configuration.

with driver.session(database="example_database", fetch_size=100) as session:
    result = session.run("MATCH (a:Person) RETURN a.name AS name")
    # do something with the result...

Session¶

class neo4j.Session¶

A Session is a logical context for transactional units of work. Connections are drawn from the Driver connection pool as required.

Session creation is a lightweight operation and sessions are not thread safe. Therefore a session should generally be short-lived, and not span multiple threads.

In general, sessions will be created and destroyed within a with context. For example:

with driver.session() as session:
    result = session.run("MATCH (n:Person) RETURN n.name AS name")
    # do something with the result...

Parameters

pool – connection pool instance
config – session config instance

close()¶: Close the session. This will release any borrowed resources, such as connections, and will roll back any outstanding transactions.

run(query, parameters=None, **kwparameters)¶

Run a Cypher query within an auto-commit transaction.

The query is sent and the result header received immediately but the neo4j.Result content is fetched lazily as consumed by the client application.

If a query is executed before a previous neo4j.Result in the same Session has been fully consumed, the first result will be fully fetched and buffered. Note therefore that the generally recommended pattern of usage is to fully consume one result before executing a subsequent query. If two results need to be consumed in parallel, multiple Session objects can be used as an alternative to result buffering.

For more usage details, see Transaction.run().

Parameters

query (str, neo4j.Query) – cypher query
parameters (dict) – dictionary of parameters
kwparameters – additional keyword parameters

Returns

a new neo4j.Result object

Return type

neo4j.Result

last_bookmark()¶

Return the bookmark received following the last completed transaction. Note: For auto-transaction (Session.run) this will trigger an consume for the current result.

Returns: neo4j.Bookmark object

begin_transaction(metadata=None, timeout=None)¶

Begin a new unmanaged transaction. Creates a new Transaction within this session.

At most one transaction may exist in a session at any point in time. To maintain multiple concurrent transactions, use multiple concurrent sessions.

Note: For auto-transaction (Session.run) this will trigger an consume for the current result.

Parameters

metadata (dict) – a dictionary with metadata. Specified metadata will be attached to the executing transaction and visible in the output of dbms.listQueries and dbms.listTransactions procedures. It will also get logged to the query.log. This functionality makes it easier to tag transactions and is equivalent to dbms.setTXMetaData procedure, see https://neo4j.com/docs/operations-manual/current/reference/procedures/ for procedure reference.
timeout (int) – the transaction timeout in seconds. Transactions that execute longer than the configured timeout will be terminated by the database. This functionality allows to limit query/transaction execution time. Specified timeout overrides the default timeout configured in the database using dbms.transaction.timeout setting. Value should not represent a duration of zero or negative duration.

Returns

A new transaction instance.

Return type

neo4j.Transaction

Raises

TransactionError – neo4j.exceptions.TransactionError if a transaction is already open.

read_transaction(transaction_function, *args, **kwargs)¶

Execute a unit of work in a managed read transaction. This transaction will automatically be committed unless an exception is thrown during query execution or by the user code. Note, that this function perform retries and that the supplied transaction_function might get invoked more than once.

Managed transactions should not generally be explicitly committed (via tx.commit()).

Example:

def do_cypher_tx(tx, cypher):
    result = tx.run(cypher)
    values = []
    for record in result:
        values.append(record.values())
    return values

with driver.session() as session:
    values = session.read_transaction(do_cypher_tx, "RETURN 1 AS x")

Example:

def get_two_tx(tx):
    result = tx.run("UNWIND [1,2,3,4] AS x RETURN x")
    values = []
    for ix, record in enumerate(result):
        if x > 1:
            break
        values.append(record.values())
    info = result.consume()  # discard the remaining records if there are any
    # use the info for logging etc.
    return values

with driver.session() as session:
    values = session.read_transaction(get_two_tx)

Parameters

transaction_function – a function that takes a transaction as an argument and does work with the transaction. tx_function(tx, *args, **kwargs)
args – arguments for the transaction_function
kwargs – key word arguments for the transaction_function

Returns

a result as returned by the given unit of work

write_transaction(transaction_function, *args, **kwargs)¶

Execute a unit of work in a managed write transaction. This transaction will automatically be committed unless an exception is thrown during query execution or by the user code. Note, that this function perform retries and that the supplied transaction_function might get invoked more than once.

Managed transactions should not generally be explicitly committed (via tx.commit()).

Example:

def create_node_tx(tx, name):
    result = tx.run("CREATE (n:NodeExample { name: $name }) RETURN id(n) AS node_id", name=name)
    record = result.single()
    return record["node_id"]

with driver.session() as session:
    node_id = session.write_transaction(create_node_tx, "example")

Parameters

transaction_function – a function that takes a transaction as an argument and does work with the transaction. tx_function(tx, *args, **kwargs)
args – key word arguments for the transaction_function
kwargs – key word arguments for the transaction_function

Returns

a result as returned by the given unit of work

Query¶

class neo4j.Query(text, metadata=None, timeout=None)¶

Create a new query.

Parameters

text (str) – The query text.
metadata (dict) – metadata attached to the query.
timeout (int) – seconds.

Session Configuration¶

To construct a neo4j.Session use the neo4j.Driver.session() method. This section describes the session configuration key-word arguments.

bookmarks
database
default_access_mode
fetch_size

`bookmarks`¶

An iterable containing neo4j.Bookmark

Default: ()

`database`¶

Name of the database to query.

Type: str, neo4j.DEFAULT_DATABASE

neo4j.DEFAULT_DATABASE: This will use the default database on the Neo4j instance.

Note

The default database can be set on the Neo4j instance settings.

from neo4j import GraphDatabase
driver = GraphDatabase.driver(uri, auth=(user, password))
session = driver.session(database="system")

Default: neo4j.DEFAULT_DATABASE

`default_access_mode`¶

The default access mode.

A session can be given a default access mode on construction.

This applies only in clustered environments and determines whether transactions carried out within that session should be routed to a read or write server by default.

Transactions (see Managed Transactions (transaction functions)) within a session can override the access mode passed to that session on construction.

Note

The driver does not parse Cypher queries and cannot determine whether the access mode should be neo4j.ACCESS_WRITE or neo4j.ACCESS_READ. Since the access mode is not passed to the server, this can allow a neo4j.ACCESS_WRITE statement to be executed for a neo4j.ACCESS_READ call on a single instance. Clustered environments are not susceptible to this loophole as cluster roles prevent it. This behaviour should not be relied upon as the loophole may be closed in a future release.

Type: neo4j.WRITE_ACCESS, neo4j.READ_ACCESS
Default: neo4j.WRITE_ACCESS

`fetch_size`¶

The fetch size used for requesting messages from Neo4j.

Type: int
Default: 1000

Transaction¶

Neo4j supports three kinds of transaction:

Auto-commit Transactions
Explicit Transactions
Managed Transactions (transaction functions)

Each has pros and cons but if in doubt, use a managed transaction with a transaction function.

Auto-commit Transactions¶

Auto-commit transactions are the simplest form of transaction, available via neo4j.Session.run().

These are easy to use but support only one statement per transaction and are not automatically retried on failure. Auto-commit transactions are also the only way to run PERIODIC COMMIT statements, since this Cypher clause manages its own transactions internally.

Example:

import neo4j

def create_person(driver, name):
    with driver.session(default_access_mode=neo4j.WRITE_ACCESS) as session:
        result = session.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
        record = result.single()
        return record["node_id"]

Example:

import neo4j

def get_numbers(driver):
    numbers = []
    with driver.session(default_access_mode=neo4j.READ_ACCESS) as session:
        result = session.run("UNWIND [1, 2, 3] AS x RETURN x")
        for record in result:
            numbers.append(record["x"])
    return numbers

Explicit Transactions¶

Explicit transactions support multiple statements and must be created with an explicit neo4j.Session.begin_transaction() call.

This creates a new neo4j.Transaction object that can be used to run Cypher.

It also gives applications the ability to directly control commit and rollback activity.

class neo4j.Transaction¶

Container for multiple Cypher queries to be executed within a single context. Transactions can be used within a with block where the transaction is committed or rolled back on based on whether or not an exception is raised:

with session.begin_transaction() as tx:
    pass

run(query, parameters=None, **kwparameters)¶

Run a Cypher query within the context of this transaction.

Cypher is typically expressed as a query template plus a set of named parameters. In Python, parameters may be expressed through a dictionary of parameters, through individual parameter arguments, or as a mixture of both. For example, the run queries below are all equivalent:

>>> query = "CREATE (a:Person { name: $name, age: $age })"
>>> result = tx.run(query, {"name": "Alice", "age": 33})
>>> result = tx.run(query, {"name": "Alice"}, age=33)
>>> result = tx.run(query, name="Alice", age=33)

Parameter values can be of any type supported by the Neo4j type system. In Python, this includes bool, int, str, list and dict. Note however that list properties must be homogenous.

Parameters

query (str) – cypher query
parameters (dict) – dictionary of parameters
kwparameters – additional keyword parameters

Returns

a new neo4j.Result object

Return type

neo4j.Result

Raises

TransactionError – if the transaction is already closed

close()¶

Close this transaction, triggering a ROLLBACK if not closed.

Raises: TransactionError – if the transaction could not perform a ROLLBACK.

closed()¶

Indicator to show whether the transaction has been closed.

Returns: True if closed, False otherwise.
Return type: bool

commit()¶

Mark this transaction as successful and close in order to trigger a COMMIT.

Raises: TransactionError – if the transaction is already closed

rollback()¶

Mark this transaction as unsuccessful and close in order to trigger a ROLLBACK.

Raises: TransactionError – if the transaction is already closed

Closing an explicit transaction can either happen automatically at the end of a with block, or can be explicitly controlled through the neo4j.Transaction.commit(), neo4j.Transaction.rollback() or neo4j.Transaction.close() methods.

Explicit transactions are most useful for applications that need to distribute Cypher execution across multiple functions for the same transaction.

Example:

import neo4j

def create_person(driver, name):
    with driver.session(default_access_mode=neo4j.WRITE_ACCESS) as session:
        tx = session.begin_transaction()
        node_id = create_person_node(tx)
        set_person_name(tx, node_id, name)
        tx.commit()
        tx.close()

def create_person_node(tx):
    name = "default_name"
    result = tx.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
    record = result.single()
    return record["node_id"]

def set_person_name(tx, node_id, name):
    result = tx.run("MATCH (a:Person) WHERE id(a) = $id SET a.name = $name", id=node_id, name=name)
    info = result.consume()
    # use the info for logging etc.

Managed Transactions (transaction functions)¶

Transaction functions are the most powerful form of transaction, providing access mode override and retry capabilities.

neo4j.Session.write_transaction()
neo4j.Session.read_transaction()

These allow a function object representing the transactional unit of work to be passed as a parameter. This function is called one or more times, within a configurable time limit, until it succeeds. Results should be fully consumed within the function and only aggregate or status values should be returned. Returning a live result object would prevent the driver from correctly managing connections and would break retry guarantees.

Example:

def create_person(driver, name)
    with driver.session() as session:
        node_id = session.write_transaction(create_person_tx, name)

def create_person_tx(tx, name):
    result = tx.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
    record = result.single()
    return record["node_id"]

To exert more control over how a transaction function is carried out, the neo4j.unit_of_work() decorator can be used.

neo4j.unit_of_work(metadata=None, timeout=None)¶

This function is a decorator for transaction functions that allows extra control over how the transaction is carried out.

For example, a timeout may be applied:

@unit_of_work(timeout=100)
def count_people_tx(tx):
    result = tx.run("MATCH (a:Person) RETURN count(a) AS persons")
    record = result.single()
    return record["persons"]

Parameters

metadata (dict) – a dictionary with metadata. Specified metadata will be attached to the executing transaction and visible in the output of dbms.listQueries and dbms.listTransactions procedures. It will also get logged to the query.log. This functionality makes it easier to tag transactions and is equivalent to dbms.setTXMetaData procedure, see https://neo4j.com/docs/operations-manual/current/reference/procedures/ for procedure reference.
timeout (int) – the transaction timeout in seconds. Transactions that execute longer than the configured timeout will be terminated by the database. This functionality allows to limit query/transaction execution time. Specified timeout overrides the default timeout configured in the database using dbms.transaction.timeout setting. Value should not represent a duration of zero or negative duration.

Result¶

Every time a query is executed, a neo4j.Result is returned.

This provides a handle to the result of the query, giving access to the records within it as well as the result metadata.

Results also contain a buffer that automatically stores unconsumed records when results are consumed out of order.

A neo4j.Result is attached to an active connection, through a neo4j.Session, until all its content has been buffered or consumed.

class neo4j.Result¶

A handler for the result of Cypher query execution. Instances of this class are typically constructed and returned by Session.run() and Transaction.run().

iter(result)

keys()¶

The keys for the records in this result.

Returns: tuple of key names
Return type: tuple

consume()¶

Consume the remainder of this result and return a neo4j.ResultSummary.

Example:

def create_node_tx(tx, name):
    result = tx.run("CREATE (n:ExampleNode { name: $name }) RETURN n", name=name)
    record = result.single()
    value = record.value()
    info = result.consume()
    return value, info

with driver.session() as session:
    node_id, info = session.write_transaction(create_node_tx, "example")

Example:

def get_two_tx(tx):
    result = tx.run("UNWIND [1,2,3,4] AS x RETURN x")
    values = []
    for ix, record in enumerate(result):
        if x > 1:
            break
        values.append(record.values())
    info = result.consume()  # discard the remaining records if there are any
    # use the info for logging etc.
    return values, info

with driver.session() as session:
    values, info = session.read_transaction(get_two_tx)

Returns: The neo4j.ResultSummary for this result

single()¶

Obtain the next and only remaining record from this result if available else return None. Calling this method always exhausts the result.

A warning is generated if more than one record is available but the first of these is still returned.

Returns: the next neo4j.Record or None if none remain
Warns: if more than one record is available

peek()¶

Obtain the next record from this result without consuming it. This leaves the record in the buffer for further processing.

Returns: the next Record or None if none remain

graph()¶

Return a neo4j.graph.Graph instance containing all the graph objects in the result. After calling this method, the result becomes detached, buffering all remaining records.

Returns: a result graph
Return type: neo4j.graph.Graph

This is experimental. (See Filter Warnings)

value(key=0, default=None)¶

Helper function that return the remainder of the result as a list of values.

See neo4j.Record.value

Parameters

key – field to return for each remaining record. Obtain a single value from the record by index or key.
default – default value, used if the index of key is unavailable

Returns

list of individual values

Return type

list

values(*keys)¶

Helper function that return the remainder of the result as a list of values lists.

See neo4j.Record.values

Parameters: keys – fields to return for each remaining record. Optionally filtering to include only certain values by index or key.
Returns: list of values lists
Return type: list

data(*keys)¶

Helper function that return the remainder of the result as a list of dictionaries.

See neo4j.Record.data

Parameters: keys – fields to return for each remaining record. Optionally filtering to include only certain values by index or key.
Returns: list of dictionaries
Return type: list

See https://neo4j.com/docs/driver-manual/current/cypher-workflow/#driver-type-mapping for more about type mapping.

Graph¶

class neo4j.graph.Graph¶

Local, self-contained graph object that acts as a container for Node and Relationship instances.

A local, self-contained graph object that acts as a container for Node and neo4j.Relationship instances. This is typically obtained via the neo4j.Result.graph() method.

nodes¶: Access a set view of the nodes in this graph.

relationships¶: Access a set view of the relationships in this graph.

relationship_type(name)¶: Obtain a Relationship subclass for a given relationship type name.

This is experimental. (See Filter Warnings)

Record¶

class neo4j.Record¶

A Record is an immutable ordered collection of key-value pairs. It is generally closer to a namedtuple than to a OrderedDict inasmuch as iteration of the collection will yield values rather than keys.

A neo4j.Record is an immutable ordered collection of key-value pairs. It is generally closer to a namedtuple than to an OrderedDict inasmuch as iteration of the collection will yield values rather than keys.

Record(iterable): Create a new record based on an dictionary-like iterable. This can be a dictionary itself, or may be a sequence of key-value pairs, each represented by a tuple.

record == other: Compare a record for equality with another value. The other value may be any Sequence or Mapping, or both. If comparing with a Sequence, the values are compared in order. If comparing with a Mapping, the values are compared based on their keys. If comparing with a value that exhibits both traits, both comparisons must be true for the values to be considered equal.

record != other: Compare a record for inequality with another value. See above for comparison rules.

hash(record): Create a hash for this record. This will raise a TypeError if any values within the record are unhashable.

record[index]: Obtain a value from the record by index. This will raise an IndexError if the specified index is out of range.

record[i:j]: Derive a sub-record based on a start and end index. All keys and values within those bounds will be copied across in the same order as in the original record.

keys()¶

Return the keys of the record.

Returns: list of key names

record[key]: Obtain a value from the record by key. This will raise a KeyError if the specified key does not exist.

get(key, default=None)¶

Obtain a value from the record by key, returning a default value if the key does not exist.

Parameters

key – a key
default – default value

Returns

a value

index(key)¶

Return the index of the given item.

Parameters: key – a key
Returns: index
Return type: int

items(*keys)¶

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

Returns: a list of value tuples
Return type: list

value(key=0, default=None)¶

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

Parameters

key – an index or key
default – default value

Returns

a single value

values(*keys)¶

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
Return type: list

data(*keys)¶

Return the keys and values of this record as a dictionary, optionally including only certain values by index or key. Keys provided in the items that are not in the record will be inserted 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

ResultSummary¶

class neo4j.ResultSummary¶

A summary of execution returned with a Result object.

server = None¶: A neo4j.ServerInfo instance. Provides some basic information of the server where the result is obtained from.

database = None¶: The database name where this summary is obtained from.

query = None¶: The query that was executed to produce this result.

parameters = None¶: Dictionary of parameters passed with the statement.

query_type = None¶: A string that describes the type of query ('r' = read-only, 'rw' = read/write).

plan = None¶: Dictionary that describes how the database will execute the query.

profile = None¶: Dictionary that describes how the database executed the query.

notifications = None¶: A list of Dictionaries containing notification information. Notifications provide extra information for a user executing a statement. They can be warnings about problematic queries or other valuable information that can be presented in a client. Unlike failures or errors, notifications do not affect the execution of a statement.

counters = None¶: A neo4j.SummaryCounters instance. Counters for operations the query triggered.

result_available_after = None¶: The time it took for the server to have the result available. (milliseconds)

result_consumed_after = None¶: The time it took for the server to consume the result. (milliseconds)

SummaryCounters¶

class neo4j.SummaryCounters¶

Contains counters for various operations that a query triggered.

nodes_created = 0¶

nodes_deleted = 0¶

relationships_created = 0¶

relationships_deleted = 0¶

properties_set = 0¶

labels_added = 0¶

labels_removed = 0¶

indexes_added = 0¶

indexes_removed = 0¶

constraints_added = 0¶

constraints_removed = 0¶

system_updates = 0¶

property contains_updates¶: True if any of the counters except for system_updates, are greater than 0. Otherwise False.

property contains_system_updates¶: True if the system database was updated, otherwise False.

ServerInfo¶

class neo4j.ServerInfo¶

property agent¶

The server agent string the server responded with.

Returns: Server agent string
Return type: str

version_info()¶

Return the server version if available.

Returns: Server Version or None
Return type: tuple

Core Data Types¶

Cypher supports a set of core data types that all map to built-in types in Python.

These include the common Boolean, Integer, Float and String types as well as List and Map that can hold heterogenous collections of any other type.

The core types with their general mappings are listed below:

Cypher Type	Python Type
Null	`None`
Boolean	`bool`
Integer	`int`
Float	`float`
String	`str`
Bytes ^[1]	`bytearray`
List	`list`
Map	`dict`

Note

Bytes is not an actual Cypher type but is transparently passed through when used in parameters or query results.

In reality, the actual conversions and coercions that occur as values are passed through the system are more complex than just a simple mapping. The diagram below illustrates the actual mappings between the various layers, from driver to data store, for the core types.

Graph Data Types¶

Cypher queries can return entire graph structures as well as individual property values.

The graph data types detailed here model graph data returned from a Cypher query. Graph values cannot be passed in as parameters as it would be unclear whether the entity was intended to be passed by reference or by value. The identity or properties of that entity should be passed explicitly instead.

The driver contains a corresponding class for each of the graph types that can be returned.

Cypher Type	Python Type
Node	`neo4j.graph.Node`
Relationship	`neo4j.graph.Relationship`
Path	`neo4j.graph.Path`

Node¶

class neo4j.graph.Node¶

Self-contained graph node.

node == other: Compares nodes for equality.

node != other: Compares nodes for inequality.

hash(node): Computes the hash of a node.

len(node): Returns the number of properties on a node.

iter(node): Iterates through all properties on a node.

node[key]: Returns a node property by key. Raises KeyError if the key does not exist.

key in node: Checks whether a property key exists for a given node.

graph¶: The Graph to which this entity belongs.

id¶: The identity of this entity in its container Graph.

labels¶: The set of labels attached to this node.

get(name, default=None)¶: Get a property value by name, optionally with a default.

keys()¶: Return an iterable of all property names.

values()¶: Return an iterable of all property values.

items()¶: Return an iterable of all property name-value pairs.

Relationship¶

class neo4j.graph.Relationship¶

Self-contained graph relationship.

relationship == other: Compares relationships for equality.

relationship != other: Compares relationships for inequality.

hash(relationship): Computes the hash of a relationship.

len(relationship): Returns the number of properties on a relationship.

iter(relationship): Iterates through all properties on a relationship.

relationship[key]: Returns a relationship property by key. Raises KeyError if the key does not exist.

key in relationship: Checks whether a property key exists for a given relationship.

type(relationship): Returns the type (class) of a relationship. Relationship objects belong to a custom subtype based on the type name in the underlying database.

graph¶: The Graph to which this entity belongs.

id¶: The identity of this entity in its container Graph.

nodes¶: The pair of nodes which this relationship connects.

start_node¶: The start node of this relationship.

end_node¶: The end node of this relationship.

type¶: The type name of this relationship. This is functionally equivalent to type(relationship).__name__.

get(name, default=None)¶: Get a property value by name, optionally with a default.

keys()¶: Return an iterable of all property names.

values()¶: Return an iterable of all property values.

items()¶: Return an iterable of all property name-value pairs.

Path¶

class neo4j.graph.Path¶

Self-contained graph path.

path == other: Compares paths for equality.

path != other: Compares paths for inequality.

hash(path): Computes the hash of a path.

len(path): Returns the number of relationships in a path.

iter(path): Iterates through all the relationships in a path.

graph¶: The Graph to which this path belongs.

nodes¶: The sequence of Node objects in this path.

start_node¶: The first Node in this path.

end_node¶: The last Node in this path.

relationships¶: The sequence of Relationship objects in this path.

Spatial Data Types¶

Cypher has built-in support for handling spatial values (points), and the underlying database supports storing these point values as properties on nodes and relationships.

https://neo4j.com/docs/cypher-manual/current/syntax/spatial/

Cypher Type	Python Type
Point	`neo4j.spatial.Point`
Point (Cartesian)	`neo4j.spatial.CartesianPoint`
Point (WGS-84)	`neo4j.spatial.WGS84Point`

Point¶

class neo4j.spatial.Point(iterable)¶

A point within a geometric space. This type is generally used via its subclasses and should not be instantiated directly unless there is no subclass defined for the required SRID.

srid = None¶

CartesianPoint¶

class neo4j.spatial.CartesianPoint(iterable)¶

Bases: neo4j.spatial.Point

property srid¶

property x¶

property y¶

property z¶

count(value, /)¶: Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

point=CartesianPoint((1.23, 4.56)

print(point.x, point.y)

point=CartesianPoint((1.23, 4.56, 7.89)

print(point.x, point.y, point.z)

WGS84Point¶

class neo4j.spatial.WGS84Point(iterable)¶

Bases: neo4j.spatial.Point

property srid¶

property x¶

property y¶

property z¶

property longitude¶

property latitude¶

property height¶

count(value, /)¶: Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

point=WGS84Point((1.23, 4.56))
print(point.longitude, point.latitude)

point=WGS84Point((1.23, 4.56, 7.89))
print(point.longitude, point.latitude, point.height)

Temporal Data Types¶

Cypher has built-in support for handling temporal values, and the underlying database supports storing these temporal values as properties on nodes and relationships.

https://neo4j.com/docs/cypher-manual/current/syntax/temporal/

Temporal data types are implemented by the neo4j.time

These provide a set of types compliant with ISO-8601 and Cypher, which are similar to those found in the built-in datetime module. Sub-second values are measured to nanosecond precision and the types are compatible with pytz.

The table below shows the general mappings between Cypher and the temporal types provided by the driver. In addition, the built-in temporal types can be passed as parameters and will be mapped appropriately.

Cypher	Python driver type	Python built-in type	`tzinfo`
Date	`neo4j.time.Date`	`datetime.date`
Time	`neo4j.time.Time`	`datetime.time`	`not None`
LocalTime	`neo4j.time.Time`	`datetime.time`	`None`
DateTime	`neo4j.time.DateTime`	`datetime.datetime`	`not None`
LocalDateTime	`neo4j.time.DateTime`	`datetime.datetime`	`None`
Duration	`neo4j.time.Duration`	`datetime.timedelta`

See topic Temporal Data Types for more details.

Errors¶

Neo4j Errors¶

Neo4j Execution Errors

neo4j.exceptions.Neo4jError

class neo4j.exceptions.Neo4jError¶

Raised when the Cypher engine returns an error to the client.

There are many Neo4j status codes, see status code.

class neo4j.exceptions.ClientError¶

Bases: neo4j.exceptions.Neo4jError

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

class neo4j.exceptions.CypherSyntaxError¶: Bases: neo4j.exceptions.ClientError

class neo4j.exceptions.CypherTypeError¶: Bases: neo4j.exceptions.ClientError

class neo4j.exceptions.ConstraintError¶: Bases: neo4j.exceptions.ClientError

class neo4j.exceptions.AuthError¶

Bases: neo4j.exceptions.ClientError

Raised when authentication failure occurs.

class neo4j.exceptions.Forbidden¶: Bases: neo4j.exceptions.ClientError

class neo4j.exceptions.ForbiddenOnReadOnlyDatabase¶: Bases: neo4j.exceptions.TransientError

class neo4j.exceptions.NotALeader¶: Bases: neo4j.exceptions.TransientError

class neo4j.exceptions.DatabaseError¶

Bases: neo4j.exceptions.Neo4jError

The database failed to service the request.

class neo4j.exceptions.TransientError¶

Bases: neo4j.exceptions.Neo4jError

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

class neo4j.exceptions.DatabaseUnavailable¶: Bases: neo4j.exceptions.TransientError

Driver Errors¶

Connectivity Errors

neo4j.exceptions.DriverError

class neo4j.exceptions.DriverError¶: Raised when the Driver raises an error.

class neo4j.exceptions.TransactionError(transaction, *args, **kwargs)¶

Bases: neo4j.exceptions.DriverError

Raised when an error occurs while using a transaction.

class neo4j.exceptions.TransactionNestingError(transaction, *args, **kwargs)¶

Bases: neo4j.exceptions.DriverError

Raised when transactions are nested incorrectly.

class neo4j.exceptions.SessionExpired(session, *args, **kwargs)¶

Bases: neo4j.exceptions.DriverError

Raised when no a session is no longer able to fulfil the purpose described by its original parameters.

class neo4j.exceptions.ServiceUnavailable¶

Bases: neo4j.exceptions.DriverError

Raised when no database service is available.

Raised when a database server or service is not available. This may be due to incorrect configuration or could indicate a runtime failure of a database service that the driver is unable to route around.

class neo4j.exceptions.RoutingServiceUnavailable¶

Bases: neo4j.exceptions.ServiceUnavailable

Raised when no routing service is available.

class neo4j.exceptions.WriteServiceUnavailable¶

Bases: neo4j.exceptions.ServiceUnavailable

Raised when no write service is available.

class neo4j.exceptions.ReadServiceUnavailable¶

Bases: neo4j.exceptions.ServiceUnavailable

Raised when no read service is available.

class neo4j.exceptions.ConfigurationError¶

Bases: neo4j.exceptions.DriverError

Raised when there is an error concerning a configuration.

class neo4j.exceptions.AuthConfigurationError¶

Bases: neo4j.exceptions.ConfigurationError

Raised when there is an error with the authentication configuration.

class neo4j.exceptions.CertificateConfigurationError¶

Bases: neo4j.exceptions.ConfigurationError

Raised when there is an error with the authentication configuration.

class neo4j.exceptions.ResultConsumedError¶

Bases: neo4j.exceptions.DriverError

Raised when trying to access records after the records have been consumed.

Internal Driver Errors¶

If an internal error (BoltError), in particular a protocol error (BoltProtocolError) is surfaced please open an issue on github.

https://github.com/neo4j/neo4j-python-driver/issues

Please provide details about your running environment,

Operating System:
Python Version:
Python Driver Version:
Neo4j Version:
The code block with a description that produced the error:
The error message:

Warnings¶

The Python Driver uses the built-in DeprecationWarning class to warn about deprecations.

The Python Driver uses the neo4j.ExperimentalWarning class to warn about experimental features.

class neo4j.ExperimentalWarning¶: Base class for warnings about experimental features.

Filter Warnings¶

This example shows how to suppress the neo4j.ExperimentalWarning using the warnings.filterwarnings() function.

import warnings
from neo4j import ExperimentalWarning

warnings.filterwarnings("ignore", category=ExperimentalWarning)

API Documentation¶

GraphDatabase¶

Driver Construction¶

URI¶

Auth¶

Auth Token Helper Functions¶

Driver¶

Driver Configuration¶

connection_acquisition_timeout¶

connection_timeout¶

encrypted¶

keep_alive¶

max_connection_lifetime¶

max_connection_pool_size¶

max_transaction_retry_time¶

resolver¶

trust¶

user_agent¶

Driver Object Lifetime¶

BoltDriver¶

Neo4jDriver¶

Sessions & Transactions¶

Session Construction¶

Session¶

Query¶

Session Configuration¶

bookmarks¶

database¶

default_access_mode¶

fetch_size¶

Transaction¶

Auto-commit Transactions¶

Explicit Transactions¶

Managed Transactions (transaction functions)¶

Result¶

Graph¶

Record¶

ResultSummary¶

SummaryCounters¶

ServerInfo¶

Core Data Types¶

Graph Data Types¶

Node¶

Relationship¶

Path¶

Spatial Data Types¶

Point¶

CartesianPoint¶

WGS84Point¶

Temporal Data Types¶

Errors¶

Neo4j Errors¶

Driver Errors¶

Internal Driver Errors¶

Warnings¶

Filter Warnings¶

Bookmark¶

`connection_acquisition_timeout`¶

`connection_timeout`¶

`encrypted`¶

`keep_alive`¶

`max_connection_lifetime`¶

`max_connection_pool_size`¶

`max_transaction_retry_time`¶

`resolver`¶

`trust`¶

`user_agent`¶

`bookmarks`¶

`database`¶

`default_access_mode`¶

`fetch_size`¶