first commit

martinohanlon · martinohanlon · commit 1a391eab6233 · 2025-06-17T14:13:50.000+01:00
diff --git a/.devcontainer/SETUP.md b/.devcontainer/SETUP.md
@@ -0,0 +1,11 @@
+# Neo4j Python Examples - Devcontainer
+
+A .devcontainer configuration is included, and when opened, such as in a GitHub codespace, all the required software and packages will be installed.
+
+You will need to:
+
+1. Create a new [`.env`](.env) file and copy the contents of the [`.env.example`](.env.example) file into it
+2. Update the environment values in the [`.env`](.env) file with the values in your Aura Credentials file which you downloaded when creating your instance.
+3. Run the [`test_environment.py`](./llm-knowledge-graph/test_environment.py) program to check the environment is set up correctly.
+
+You can explore the [`examples`](../examples/) to see how you can use the Neo4j Python driver with Aura.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -0,0 +1,28 @@
+{
+	"name": "Neo4j Python Examples",
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+	"postCreateCommand": "bash .devcontainer/post_create.sh",
+	"customizations": {
+		"codespaces": {
+			"openFiles": [
+				".devcontainer/SETUP.md",
+				".env.example",
+				"test_environment.py",
+				"examples/connect.py"
+				]
+		},
+		"vscode": {
+			"settings": {
+				"python.createEnvironment.trigger": "off",
+				"workbench.editorAssociations": {
+					"*.md": "vscode.markdown.preview.editor"
+				}
+			},
+			"extensions": [
+				"ms-python.python",
+				"ms-python.debugpy",
+				"neo4j-extensions.neo4j-for-vscode"
+				]
+		}
+	}
+}
diff --git a/.devcontainer/post_create.sh b/.devcontainer/post_create.sh
@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+pip3 install -r requirements.txt
diff --git a/.env.example b/.env.example
@@ -0,0 +1,4 @@
+NEO4J_URI="neo4j+s://"
+NEO4J_USERNAME="neo4j"
+NEO4J_PASSWORD="password"
+NEO4J_DATABASE=neo4j
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+* text=auto
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,31 @@
+.vscode
+.env
+.venv
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
diff --git a/README.md b/README.md
@@ -0,0 +1,37 @@
+# Neo4j Python Examples
+
+This repository contains code examples to use Python with Neo4j Aura.
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new/martinohanlon/neo4j-py-example)
+
+> [!IMPORTANT]  
+> To use GitHub Codespaces you will need to login with a GitHub account. 
+> You can use the [GitHub Codespaces free monthly usage](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts) to view these examples.
+
+## Install
+
+Install the [`neo4j` Python pakage](https://neo4j.com/docs/python-manual/current/).
+
+```bash
+pip install neo4j
+```
+
+## Examples
+
+- [`connect.py` - Connect to a Neo4j Graph Database](examples/connect.py)
+- [`run_cypher.py` - Run a Cypher statement](examples/run_cypher.py)
+- [`create_data.py` - Read data from a CSV file and create nodes and relationships](examples/create.py)
+- [`transaction.py` - Execute cypher in a transaction](examples/transaction.py)
+- [`export_to_dataframe.py` - Export data to a Pandas DataFrame ](examples/export_to_dataframe.py)
+
+## Run
+
+To run the examples on your environment, you will need to:
+
+1. Install the required packages including the [`neo4j` Python driver](https://neo4j.com/docs/python-manual/current/).:
+    ```bash
+    pip install -r requirements.txt
+    ```
+1. Create a new [`.env`](.env) file and copy the contents of the [`.env.example`](.env.example) file into it
+1. Update the environment values in the [`.env`](.env) file with the values in your Aura Credentials file which you downloaded when creating your instance.
+1. Run the [`test_environment.py`](./llm-knowledge-graph/test_environment.py) program to check the environment is set up correctly.
diff --git a/examples/connect.py b/examples/connect.py
@@ -0,0 +1,37 @@
+# This example demonstrates how to connect to a Neo4j database using the Neo4j
+# Python driver.
+# 
+# It connects to the database, verifies the connection, runs a simple Cypher 
+# query to count the nodes, and prints the result.
+
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+from neo4j import GraphDatabase
+
+# Initialize the Neo4j driver
+driver = GraphDatabase.driver(
+    os.getenv('NEO4J_URI'),
+    auth=(
+        os.getenv('NEO4J_USERNAME'), 
+        os.getenv('NEO4J_PASSWORD')
+    )
+)
+
+# Verify the connection
+driver.verify_connectivity()
+
+# Run a simple query to count nodes in the database
+records, summary, keys = driver.execute_query(
+    "RETURN COUNT {()} AS count"
+)
+
+# Get the first record
+first = records[0]
+
+# Print the count entry
+print(first["count"])   # (3)
+
+# Close the driver
+driver.close()
diff --git a/examples/create_data.py b/examples/create_data.py
@@ -0,0 +1,72 @@
+# This example reads CSV data from examples/data/employees.csv
+# and creates nodes and relationships in the Neo4j database.
+# 
+# It creates a graph with 3 node labels, `Person`, `Company`, 
+# and `Location`, connected by `WORKS_AT` and `LIVES_IN` relationships.
+#
+# +-----------+         WORKS_AT         +-----------+
+# |  Person   |------------------------->|  Company  |
+# +-----------+                          +-----------+
+#       |
+#       |
+#       | LIVES_IN
+#       v
+# +-----------+
+# | Location  |
+# +-----------+
+
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+import csv
+from neo4j import GraphDatabase
+
+FILE_PATH = os.path.join('examples','data','employees.csv')
+
+# Initialize the Neo4j driver
+driver = GraphDatabase.driver(
+    os.getenv('NEO4J_URI'),
+    auth=(
+        os.getenv('NEO4J_USERNAME'), 
+        os.getenv('NEO4J_PASSWORD')
+    )
+)
+
+# Verify the connection
+# driver.verify_connectivity()
+
+# Cypher query to create the data
+cypher_query = """
+MERGE (p:Person {id: toInteger($id), name: $name, governmentId: $gov_id})
+MERGE (l:Location {name: $location})
+MERGE (c:Company {name: $company})
+MERGE (p)-[:LIVES_IN]->(l)
+MERGE (p)-[:WORKS_AT {position: $position}]->(c)
+"""
+
+# Load the CSV file
+with open(FILE_PATH, newline='') as csvfile:
+    reader = csv.DictReader(csvfile)
+    for row in reader:
+        
+        # Execute the query with parameters
+        records, summary, keys = driver.execute_query(
+            cypher_query,
+            id=row['id'],
+            name=row['name'],
+            gov_id=row['gov_id'],
+            location=row['location'],
+            company=row['company'],
+            position=row['position']
+        )
+
+        # Alternatively, you can pass the row as parameters
+        # records, summary, keys = driver.execute_query(
+        #     cypher_query,
+        #     parameters_= row
+        # )
+
+        print(summary.counters)
+
+driver.close()
diff --git a/examples/data/employees.csv b/examples/data/employees.csv
@@ -0,0 +1,11 @@
+id,name,company,position,location,gov_id
+1,"John Doe","TechCorp","Engineer","Delhi",123456789
+2,"Jane Smith","TechCorp","Manager","Sydney",987654321
+3,"Rajesh Kumar","FinanceLLC","Analyst","London",456789123
+4,"Alice Brown","MarketSolutions","Director","London",321654987
+5,"Anjali Sharma","TechCorp","Developer","San Francisco",654321987
+6,"Emily Green","MarketSolutions","Designer","New York",789123456
+7,"David Black","FinanceLLC","CTO","New York",159753456
+8,"Susan Blue","TechCorp","HR","Sydney",753159852
+9,"Michael Red","MarketSolutions","Sales","San Francisco",951753456
+10,"Sunita Patel","FinanceLLC","Sales","Delhi",852456963
diff --git a/examples/export_to_dataframe.py b/examples/export_to_dataframe.py
@@ -0,0 +1,47 @@
+# This example demonstrates how to run a Cypher query and export the results to a 
+# Pandas DataFrame.
+# 
+# You can add the expected data to the database using the `examples/create_data.py` 
+# example.
+
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+from neo4j import GraphDatabase, Result
+
+# Initialize the Neo4j driver
+driver = GraphDatabase.driver(
+    os.getenv('NEO4J_URI'),
+    auth=(
+        os.getenv('NEO4J_USERNAME'), 
+        os.getenv('NEO4J_PASSWORD')
+    )
+)
+
+# Verify the connection
+driver.verify_connectivity()
+
+# Define the query
+cypher_query = """
+MATCH (p:Person)-[:LIVES_IN]->(l:Location)
+MATCH (p)-[w:WORKS_AT]->(c:Company)
+RETURN 
+    p.name as name, 
+    c.name as company, 
+    w.position as position, 
+    l.name as location
+"""
+
+# Execute the query using the Result transformer 
+df = driver.execute_query(
+    cypher_query,
+    result_transformer_=Result.to_df,
+    location='London'
+)
+
+# Print the DataFrame
+print(df)
+
+# Close the driver
+driver.close()
diff --git a/examples/run_cypher.py b/examples/run_cypher.py
@@ -0,0 +1,54 @@
+# This example demonstrates how to run a Cypher query using the Neo4j Python driver.
+# Query parameters are used to run the query, and the result is printed.
+# 
+# You can add the expected data to the database using the `examples/create_data.py` 
+# example.
+
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+from neo4j import GraphDatabase
+
+# Initialize the Neo4j driver
+driver = GraphDatabase.driver(
+    os.getenv('NEO4J_URI'),
+    auth=(
+        os.getenv('NEO4J_USERNAME'), 
+        os.getenv('NEO4J_PASSWORD')
+    )
+)
+
+# Verify the connection
+driver.verify_connectivity()
+
+# Define the query
+cypher_query = """
+MATCH (p:Person)-[:LIVES_IN]->(l:Location)
+MATCH (p)-[w:WORKS_AT]->(c:Company)
+WHERE l.name = $location
+RETURN p.name as name, c.name as company, w.position as position
+"""
+
+# Execute the query with a parameter
+records, summary, keys = driver.execute_query(
+    cypher_query,
+    location='London'
+)
+
+# When only reading data, you can optimize performance by setting the 
+# routing_ parameter to READ mode.
+
+# records, summary, keys = driver.execute_query(
+#     cypher_query,
+#     routing_='r',
+#     location='London'
+# )
+
+# Parse the result
+for record in records:
+    # Print the return values
+    print(f"Name: {record['name']}, Company: {record['company']}, Position: {record['position']}")
+
+# Close the driver
+driver.close()
diff --git a/examples/transaction.py b/examples/transaction.py
@@ -0,0 +1,37 @@
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+from neo4j import GraphDatabase
+
+# Initialize the Neo4j driver
+driver = GraphDatabase.driver(
+    os.getenv('NEO4J_URI'),
+    auth=(
+        os.getenv('NEO4J_USERNAME'), 
+        os.getenv('NEO4J_PASSWORD')
+    )
+)
+
+# Verify the connection
+driver.verify_connectivity()
+
+# Create a session to run a transaction
+with driver.session() as session:
+
+    # Create a work unit for the transaction
+    def create_person(tx, name, age):
+        result = tx.run("""
+        CREATE (p:Person {name: $name, age: $age})
+        RETURN p
+        """, name=name, age=age)
+
+        return result.consume()
+
+    # Execute transaction function
+    summary = session.execute_write(create_person, name='Alice', age=30)
+
+    print(summary.counters.nodes_created, 'node(s) created.')
+
+# Close the driver
+driver.close()
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,3 @@
+python-dotenv==1.0.1
+neo4j
+pandas
diff --git a/test_environment.py b/test_environment.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+#!/usr/bin/env bash`
	`2`	`+pip3 install -r requirements.txt`