Database: Neo4j

Purpose:

This module provides a Graph class for interacting with a Neo4j graph database.

Platform:

Linux/Windows | Python 3.11+

Developer:

J Berendt

Email:

development@s3dev.uk

Comments:

n/a

Example:

Example showing how to generate a .env file for easy connection:

>>> from docp_dbi.databases import neo4j

>>> neo4j.create_dotenv_file(uri='neo4j://127.0.0.1:7687',
                             database='neo4j',
                             username='neo4j',
                             password='neo4j')

# Copy the .env file from your Desktop to the project's
# directory.

Example showing how to use the local .env file to connect to the database:

>>> from docp_dbi import Neo4jDB
>>> neodb = Neo4jDB()

# Verify the database is connected.
>>> neodb.connected
True

# Query the database.
>>> results = neodb.execute_query('match (n) return count(n)')

Example showing how to use the .env filepath to connect to the database:

>>> from docp_dbi import Neo4jDB
>>> neodb = Neo4jDB(auth='/path/to/.env')

# Verify the database is connected.
>>> neodb.connected
True

# Query the database.
>>> results = neodb.execute_query('match (n) return count(n)')

Example showing how to query a graph database, using the URI and credentials:

>>> from docp_dbi import Neo4jDB
>>> neodb = Neo4jDB(uri='neo4j://127.0.0.1:7687',
                    auth=('username', 'password'))

# Verify the database is connected.
>>> neodb.connected
True

# Query the database.
>>> results = neodb.execute_query('match (n) return count(n)')
class Neo4jDB(uri: str = None, *, auth: str | tuple = None, database: str = None, **config)[source]

Bases: object

Graph object class for interacting with a Neo4j graph database.

Parameters:

  • uri (str, optional) – Database connection URI. Defaults to None.

  • auth (str | tuple, optional) – Either a path to the .env file containing database credentials, or a tuple containing authentication credentials as (username, password). If None, this parameter’s value is altered to search the current directory for a .env file. Defaults to None.

  • database (str, optional) – Name of the database to be used. Can also be provided via the .env file using the key: NEO4J_DATABASE. Defaults to None.

  • **config – Pass-through configuration items provided to the driver.

Note

If values are not provided to the class constructor, an attempt is made to obtain the values from the .env file, either in the current directory, or from the path provided to the auth parameter.

property connected: bool

The database is connected.

Returns:

True if connected, otherwise False.

Return type:

bool

property database: str

Accessor to the database name.

The database name can be provided using the .env file with the key: NEO4J_DATABASE.

property driver: Neo4jDriver

Accessor to the database driver object.

close() → None[source]

Close the connection.

execute_query(query: str, parameters: dict = None, database: str = None, **kwargs) → EagerResult[source]

Execute a query on the database.

Parameters:

  • query (str) – Cypher query to be executed.

  • parameters (dict, optional) – Query parameters. Defaults to None.

  • database (str, optional) – Database to be used. This parameter can be used to override the class’ database attribute (database), if provided via the .env file. Defaults to None.

  • **kwargs – Pass-through keyword arguments.

Returns:

Query results object.

Return type:

EagerResult

load_from_csv(*, path_nodes: str = None, path_edges: str = None) → tuple[bool, list][source]

Load graph data from a CSV file.

This function is designed to load node and/or edge (relationship) data. The required format for each CSV type is as follows, where the property data is optional, whereas the id and label are required.

Node Data

  • Field Definitions

    • id: Unique (user-defined) node ID.

    • label: Node label. For example: Book, Character, etc.

    • Properties: The column heading for each property will be used as its key in the graph.

  • Format:

    id,label,prop1,...,propN

Edge Data

  • Field Definitions

    • source: The ID of the source node.

    • target: The ID of the target node.

    • type: edge type. For example: AUTHOR, APPEARS_IN, etc.

    • Properties: The column heading for each property will be used as its key in the graph.

  • Format:

    source,target,type,prop1,...,propN

Parameters:

  • path_nodes (str, optional) – Full path to the node input data. Defaults to None.

  • path_edges (str, optional) – Full path to the edge input data. Defaults to None.

Returns:

A tuple containing a success flag and a list of query result objects.

Return type:

tuple[bool, list]

create_dotenv_file(uri: str = 'neo4j://127.0.0.1:7687', database: str = 'neo4j', password: str = 'neo4j', username: str = 'neo4j', replace: bool = False) → None[source]

Generate a .env file from the provided credentials.

The resulting file will be placed on the user’s Desktop.

Parameters:

  • uri (str, optional) – Database location URI. Defaults to ‘neo4j://127.0.0.1:7687’.

  • database (str, optional) – Database name. Defaults to ‘neo4j’.

  • password (str, optional) – Authentication password. Defaults to ‘neo4j’.

  • username (str, optional) – Authentication username. Defaults to ‘neo4j’.

  • replace (bool, optional) – Force replace an existing .env file. Defaults to False.

Raises:

RuntimeError – Raised if a .env file already exists on the user’s Desktop and replace=False.