Excel to Neo4j Knowledge Graph

English | Simplified Chinese

Excel-to-Neo4j examples for building knowledge graphs: a legacy py2neo v3 path for the original educational project, plus a modern Neo4j GraphRAG/vector-search path for current applications.

Legacy repository slug: neo4j-python-pandas-py2neo-v3.

Maintenance Status

This project is maintained again as of 2026-06. The current goal is to keep the original py2neo v3 / Neo4j 3.x example usable for learners, notebooks, and legacy projects while adding a current Neo4j driver, vector index, and GraphRAG example.

This repository is intentionally maintained as a legacy educational example. Modern Python, pandas, Neo4j, and py2neo versions may require code changes; modernization work is tracked separately so the legacy baseline remains clear.

What This Project Does

• Reads invoice-style Excel data with pandas.
• Extracts node data and relationship data from the spreadsheet.
• Creates Neo4j nodes and relationships through py2neo v3.
• Converts Neo4j graph data into matrices for downstream machine learning experiments.

Modern Neo4j Example

The repository now includes a modern, additive example at examples/modern_invoice_graphrag/.

It keeps the original invoice dataset concept but uses the current Neo4j application stack:

• official neo4j Python driver
• Neo4j 5+/2026 vector indexes
• GraphRAG-style semantic retrieval
• optional neo4j-graphrag production embeddings
• local deterministic embeddings for keyless demos and CI

Start with:

python -m examples.modern_invoice_graphrag.app \
  --input examples/modern_invoice_graphrag/sample_invoice_rows.csv \
  --limit 2 \
  dry-run

Open Source Skill

The repository also includes an open-source Codex/agent skill at skills/neo4j-knowledge-graph/.

Use it when an AI coding agent needs to design a Neo4j knowledge graph from CSV/Excel data, generate safe Cypher, choose between legacy py2neo and the official Neo4j driver, or add GraphRAG/vector-search behavior. The skill includes a reusable profile_table.py script for inspecting tabular data before graph modeling.

Compatibility

The original working environment was:

• Python 3.6.5
• Windows 10
• Neo4j 3.x
• py2neo 3

The pinned dependencies in requirements.txt are intentionally legacy. Dependency and security modernization is tracked in issue #23.

Quick Start

Install dependencies:

pip install -r requirements.txt

The repository includes Invoice_data_Demo.xls as sample data.

Before running invoice_neo4j.py, update the local path and Neo4j connection settings:

• Replace os.chdir('xxxx') with this repository path, or run the script from the repository root.
• Replace the placeholder Graph(...) connection in dataToNeo4jClass/DataToNeo4jClass.py with your Neo4j server URL and credentials.

Project Structure

• invoice_neo4j.py: reads the Excel file, extracts node and relationship data, and writes to Neo4j.
• dataToNeo4jClass/DataToNeo4jClass.py: wraps Neo4j node and relationship creation.
• neo4j_matrix.py: extracts Neo4j relationship data and converts it into matrix form.
• Invoice_data_Demo.xls: demo Excel data for local testing and learning.
• requirements.txt: legacy dependency pins for the original py2neo v3 environment.
• .github/ISSUE_TEMPLATE/: issue templates for bugs, compatibility questions, and sample-data requests.

Neo4j Knowledge Graph Construction

1. Running Environment

For package dependencies, refer to requirements.txt.

2. Extracting Excel Data With Pandas

The Excel data structure is as follows:

The data_extraction and relation_extraction functions extract the node data and relationship data required for building the knowledge graph.

invoice_neo4j.py

3. Creating Nodes And Edges

DataToNeo4jClass.py

neo4j_matrix.py extracts knowledge graph data and converts it into matrices for machine learning models.

Roadmap

v0.2.x - Restore Maintenance

• Triage historical issues and close resolved sample-data questions.
• Document the known working legacy environment.
• Add clearer setup notes for Windows, local paths, Neo4j credentials, and sample data.
• Publish maintenance restart releases.

v0.3.x - Reproducible Examples

• Ship a modern Neo4j GraphRAG/vector-search invoice example.
• Replace hard-coded local paths with configurable arguments.
• Add smoke tests for Excel extraction and relationship DataFrame generation.
• Improve issue templates based on new bug reports.

v0.4.x - Modern Compatibility

• Evaluate support for newer Python and pandas versions.
• Document the migration path from py2neo v3 to newer Neo4j Python tooling.
• Add CI checks for the supported legacy environment where practical.

Issue Triage

New and historical issues are being reviewed in batches. When opening an issue, please include:

• Python version
• Neo4j version
• py2neo version
• operating system
• the command you ran
• the full error message or screenshot

For sample data questions, use the included Invoice_data_Demo.xls file first.

Project Governance

• License: MIT
• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Support policy: SUPPORT.md
• Code of conduct: CODE_OF_CONDUCT.md
• Pull request template: .github/PULL_REQUEST_TEMPLATE.md

Repository maintenance is tracked publicly through issues and releases.