Introduction

Extras on top of the official Neo4j driver

If you search neo4j in PyPI, besides a ton of abandoned or irrelevant modules, you will find the neo4j module provided by the Neo4j company, and the full-fledged, community developed py2neo. The official module comes with a really bare-bones API. Here we only add a thin wrapper around it to make its usage a bit more convenient.

Documentation: https://saezlab.github.io/neo4j-utils/

Issues, feedback: https://github.com/saezlab/neo4j-utils/issues

Developed by the Saez Lab.

Reference

Extra utils for using Neo4j.

class neo4j_utils.Driver(driver: Driver | Driver | None = None, db_name: str | None = None, db_uri: str | None = None, db_user: str | None = None, db_passwd: str | None = None, config: Literal['neo4j.yaml', 'neo4j.yml'] | None = None, fetch_size: int = 1000, raise_errors: bool | None = None, wipe: bool = False, offline: bool = False, fallback_db: str | tuple[str] | None = None, fallback_on: str | set[str] | None = None, multi_db: bool | None = None, **kwargs)

Manage the connection to the Neo4j server.

property apoc_version: str | None

Version of the APOC plugin available in the current database.

property auth

Database server user and password (from config or built-in default).

close()

Closes the Neo4j driver if it exists and is open.

property constraints: list | None

List of constraints in the current database.

create_db(name: str | None = None)

Create a database if it does not already exist.

Parameters:

name (str) – Name of the database.

property current_db: str

Name of the current database.

All operations and queries are executed by default on this database.

Returns:

Name of a database.

db_connect()

Connect to the database server.

Creates a database connection manager (driver) based on the current configuration.

db_exists(name=None)

Tells if a database exists in the storage of the Neo4j server.

Parameters:

name (str) – Name of a database (graph).

Returns:

True if the database exists.

Return type:

(bool)

db_online(name: str | None = None)

Tells if a database is currently online (active).

Parameters:

name (str) – Name of a database (graph).

Returns:

True if the database is online.

Return type:

(bool)

db_status(name: str | None = None, field: str = 'currentStatus') → Literal['online', 'offline'] | str | dict | None

Tells the current status or other state info of a database.

Parameters:

  • name – Name of a database (graph).

  • field – The field to return.

Returns:

The status as a string, None if the database does not exist. If field is None a dictionary with all fields will be returned.

property default_db: str | None

Default database of the server.

drop_constraints()

Drops all constraints in the current database.

Requires the database to be empty.

drop_db(name: str | None = None)

Deletes a database if it exists.

Parameters:

name – Name of the database.

drop_indices()

Drops all indices in the current database.

Requires the database to be empty.

drop_indices_constraints()

Drops all indices and constraints in the current database.

Requires the database to be empty.

property edge_count: int | None

Number of edges in the database.

ensure_db()

Makes sure the database exists and is online.

If the database creation or startup is necessary but the user does not have the sufficient privileges, an exception will be raised.

explain(query, db=None, fetch_size=None, write=True, **kwargs)

Explain a query and pretty print the output.

CAVE: Only handles linear profiles (no branching) as of now. TODO include branching as in profile()

fallback(db: str | tuple[str] | None = None, on: str | set[str] | None = None)

Should running on the default database fail, try a fallback database.

A cotext that attempts to run queries against a fallback database if running against the default database fails.

Parameters:

  • db – Name of one or more fallback database(s).

  • on – Names of the errors when the fallback database should be used.

go_offline()

Switch to offline mode.

The connection will be destroyed and query execution or any contact to the server won’t be attempted any more.

go_online(db_name: str | None = None, db_uri: str | None = None, db_user: str | None = None, db_passwd: str | None = None, config: Literal['neo4j.yaml', 'neo4j.yml'] | None = None, fetch_size: int | None = None, raise_errors: bool | None = None, wipe: bool = False)

Switch to online mode.

In offline mode this object doesn’t do any interaction to the server, instead it serves more or less as a mock. Here we attempt to create a connection to the server based on the config contained in this object or passed as arguments to this method. If the connection is successful, the :attr:offline flag will be set to False and server interactions will be performed as normal.

Parameters:

  • db_name – Name of the database (Neo4j graph) to use.

  • db_uri – Protocol, host and port to access the Neo4j server.

  • db_user – Neo4j user name.

  • db_passwd – Password of the Neo4j user.

  • fetch_size – Optional; the fetch size to use in database transactions.

  • raise_errors – Raise the errors instead of turning them into log messages and returning None.

  • config – Path to a YAML config file which provides the URI, user name and password.

  • wipe – Wipe the database after connection, ensuring the data is loaded into an empty database.

property has_apoc: bool

Tells if APOC is available in the current database.

property home_db: str | None

Home database of the current user.

property indices: list | None

List of indices in the current database.

property label_counts

Count the nodes by labels.

property last_fail

The last failed query.

property last_query

The last succesful query.

static match_error(error: Exception | str, errors: set[Exception | str]) → bool

Tells if error is listed in errors.

Parameters:

  • error – An exception type or its name as string.

  • errors – One or more exception types or names.

Returns:

True if error is found to be a subclass of any of the classes listed in errors.

property node_count: int | None

Number of nodes in the database.

property node_labels: list[str]

Node labels defined in the database.

Presence of a label does not guarantee any instance of it exists in the database.

property offline: bool

Whether the driver is in offline mode.

property passwd: str | None

Password for the currently active connection.

Returns:

The name of the user, None if no connection or no unencrypted authentication data is available.

profile(query, db=None, fetch_size=None, write=True, **kwargs)

Profile a query and pretty print the output.

Parameters:

  • query (str) – a valid Cypher query (see query())

  • db (str) – the DB inside the Neo4j server that should be queried

  • fetch_size (int) – the Neo4j fetch size parameter

  • write (bool) – indicates whether to address write- or read- servers

  • explain (bool) – indicates whether to EXPLAIN the CYPHER query and return the ResultSummary

  • explain – indicates whether to PROFILE the CYPHER query and return the ResultSummary

  • **kwargs – optional objects used in CYPHER interactive mode, for instance for passing a parameter dictionary

Returns:

  • dict: the raw profile returned by the Neo4j bolt driver

  • list of str: a list of strings ready for printing

Return type:

2-tuple

property prop_keys

Property keys defined in the database.

query(query: str, db: str | None = None, fetch_size: int | None = None, write: bool = True, explain: bool = False, profile: bool = False, fallback_db: str | tuple[str] | None = None, fallback_on: str | set[str] | None = None, raise_errors: bool | None = None, **kwargs) → tuple[list[dict] | None, neo4j.work.summary.ResultSummary | None]

Run a CYPHER query.

Create a session with the wrapped driver, run a CYPHER query and return the response.

Parameters:

  • query – A valid CYPHER query, can include APOC if the APOC plugin is installed in the accessed database.

  • db – The DB inside the Neo4j server that should be queried fetch_size (int): the Neo4j fetch size parameter.

  • write – Indicates whether to address write- or read-servers.

  • explain – Indicates whether to EXPLAIN the CYPHER query and return the ResultSummary.

  • profile – Indicates whether to PROFILE the CYPHER query and return the ResultSummary.

  • fallback_db – If the query fails due to the database being unavailable, try to execute it against a fallback database. Typically the default database “neo4j” can be used as a fallback.

  • fallback_on – Run queries against the fallback databases in case of these errors.

  • raise_errors – Raise Neo4j errors instead of only printing them into the log and stdout.

  • **kwargs – Optional objects used in CYPHER interactive mode, for instance for passing a parameter dictionary.

Returns:

  • neo4j.Record.data: the Neo4j response to the query, consumed by the shorthand .data() method on the Result object

  • neo4j.ResultSummary: information about the result returned by the .consume() method on the Result object

Return type:

2-tuple

read_config(section: str | None = None)

Read the configuration from a YAML file.

Populates the instance configuration from one section of a YAML config file.

property rel_type_counts

Count the relationships by types.

property rel_types: list[str]

Relationship types defined in the database.

reload()

Reloads the object from the module level.

select_db(name: str)

Set the current database.

The Python driver is able to run only CYPHER statements, not Neo4j commands, hence we can’t simply do :use database;, but we create or re-use another Driver object.

session(**kwargs)

Context with a database connection session.

A context that creates a session and closes it at the end.

Parameters:

Kwargs – Passed to neo4j.Neo4jDriver.session.

start_db(name: str | None = None)

Starts a database (brings it online) if it is offline.

Parameters:

name – Name of the database.

property status: Literal['no driver', 'no connection', 'db offline', 'db online', 'offline']

State of this driver object and its current database.

stop_db(name: str | None = None)

Stops a database, making sure it’s offline.

Parameters:

name – Name of the database.

property uri

Database server URI (from config or built-in default).

use_db(name: str)

A context where the default database is set to name.

Parameters:

name – The name of the desired default database.

property user: str | None

User for the currently active connection.

Returns:

The name of the user, None if no connection or no unencrypted authentication data is available.

wipe_db()

Delete all contents of the current database.

Used in initialisation, deletes all nodes and edges and drops all indices and constraints.

write_config(path: str = 'neo4j.yaml')

Write the current config into file.

neo4j_utils.log()

Browse the log file.

neo4j_utils.logfile() → str

Path to the log file.