neo4j-python-pandas-py2neo-v3: an Excel-to-graph teaching repo with two drivers in one tree
Excel-to-Neo4j knowledge graph examples: legacy py2neo v3 plus modern Neo4j GraphRAG/vector search.
At a glance
- What is it?
- The repository keeps a py2neo v3 invoice example alive for learners and pairs it with a modern official-driver GraphRAG path. The split is deliberate, and the maintenance burden lands on whoever picks the legacy half.
- Who is it for?
- Adopt it if you want a small, readable reference for turning spreadsheet rows into Neo4j nodes and edges, or if you need to keep a py2neo v3 script running on Neo4j 3.x while you plan a migration. Do not adopt the legacy half for a new build: the pinned requirements are intentionally old and the README says modernization is tracked in issue #23, not in the code.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 14 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The spreadsheet-to-graph gap this repository fills
Most teams that want a knowledge graph already have the data in a spreadsheet. Invoice rows, supplier lists, line items, and the columns that tie them together are sitting in an .xls file, and the graph database is empty. The work between those two states is unglamorous: read the sheet with pandas, decide which columns become nodes, decide which columns become relationships, and write both without producing duplicate nodes on the second run. This repository is a worked example of exactly that pipeline. The README states it reads invoice-style Excel data with pandas, extracts node data and relationship data, creates Neo4j nodes and relationships through py2neo v3, and then converts graph data into matrices for downstream machine learning experiments. That last step, neo4j_matrix.py, is the part most tutorials skip. The audience is narrow and identifiable: learners who want a complete small example rather than an API reference, and maintainers of older Python projects where py2neo 3 is already a dependency and cannot be removed this week. The repository slug neo4j-python-pandas-py2neo-v3 is itself a statement of scope, and the README calls the legacy repository slug out explicitly.
Two pipelines in one tree: py2neo v3 and the official driver
The repository does not have one architecture. It has two, sharing a dataset concept. The legacy path runs through invoice_neo4j.py, which the README describes as reading the Excel file, extracting node and relationship data, and writing to Neo4j. The write itself is wrapped: dataToNeo4jClass/DataToNeo4jClass.py wraps Neo4j node and relationship creation, so the extraction logic and the database logic are separated. That separation is the reason the example is still readable eight years after the screenshot dates in the README. The modern path is additive and lives at examples/modern_invoice_graphrag/. According to the README it uses the official neo4j Python driver, Neo4j 5+/2026 vector indexes, GraphRAG-style semantic retrieval, optional neo4j-graphrag production embeddings, and local deterministic embeddings for keyless demos and CI. The phrase keyless demos matters: it means the example can run without an embedding provider API key, which is the difference between an example that gets tried and one that gets skipped. The two paths do not share a driver, so a fix in one does not propagate to the other. That is a real cost of the dual-track design, and the README acknowledges it by describing the modern example as additive rather than as a replacement.
Running the legacy invoice script without hard-coded paths
The legacy setup is documented as two manual edits before the first run. Install with pip install -r requirements.txt, then open invoice_neo4j.py and replace os.chdir('xxxx') with the repository path, or run the script from the repository root so the relative path resolves. The second edit is in dataToNeo4jClass/DataToNeo4jClass.py: replace the placeholder Graph(...) connection with your Neo4j server URL and credentials. The sample data is Invoice_data_Demo.xls, included in the repository. The documented working environment is Python 3.6.5, Windows 10, Neo4j 3.x, and py2neo 3. Nothing in the material suggests a test suite for this path; the roadmap lists smoke tests for Excel extraction and relationship DataFrame generation under v0.3.x, so treat the legacy script as something you verify by running against your own server. If your Neo4j is version 5 or later, the legacy script is the wrong entry point. Use the modern example instead, which the README starts with python -m examples.modern_invoice_graphrag.app followed by --input examples/modern_invoice_graphrag/sample_invoice_rows.csv, --limit 2, and dry-run. The dry-run flag is worth noting because it lets you inspect the extraction output before anything is written to the database.
What the pinned requirements cost you
The README is direct about this: the pinned dependencies in requirements.txt are intentionally legacy, and dependency and security modernization is tracked in issue #23. Intentionally legacy is a defensible choice for a teaching repository, because an example that breaks when pandas changes is worse than an example that is old. But it shifts cost onto the adopter. If you install requirements.txt into a modern environment, you are installing packages chosen for Python 3.6.5 compatibility. The README states plainly that modern Python, pandas, Neo4j, and py2neo versions may require code changes. That sentence is the migration estimate. There is no compatibility matrix in the supplied material, no list of which pandas version breaks which function, and no CI result for the legacy environment; the roadmap places CI checks for the supported legacy environment under v0.4.x with the qualifier where practical. So the maintenance cost is not the repository's upkeep, it is your own: either you freeze your environment to match the documented one, or you port the extraction functions to the official driver yourself. The modern example is the reference for that port, but the README does not claim it is a drop-in replacement for the legacy scripts.
The Codex skill and the profile_table.py inspection step
The repository ships an open-source Codex/agent skill at skills/neo4j-knowledge-graph/. The README describes the intended use: when an AI coding agent needs to design a Neo4j knowledge graph from CSV or Excel data, generate safe Cypher, choose between legacy py2neo and the official Neo4j driver, or add GraphRAG/vector-search behavior. The concrete artifact inside it is profile_table.py, a reusable script for inspecting tabular data before graph modeling. That ordering is the useful part of the skill. Profiling columns before writing Cypher is the step that prevents a graph model built on a misread column. A skill that encodes inspect-then-model is more valuable than one that jumps to Cypher generation, because the failure mode of generated Cypher is usually a wrong assumption about the data, not a syntax error. The limitation is that this is agent tooling, and the material does not describe how the skill is loaded, which agent runtimes it targets beyond the Codex naming, or how its output is validated. Treat it as a prompt and script bundle to read, not as a verified component.
Where the example stops being useful
The extraction functions are written against one spreadsheet shape, the invoice demo. The README points to Invoice_data_Demo.xls and tells people asking sample data questions to use that file first, which implies the functions assume its columns. Point them at a different workbook and you are editing data_extraction and relation_extraction, not configuring them. The legacy path also assumes a single Neo4j 3.x server reached through a placeholder Graph connection; there is no mention of batching, transaction sizing, or idempotent writes, so re-running the script against a populated database is an open question the material does not answer. The matrix conversion in neo4j_matrix.py is described as extracting relationship data and converting it into matrix form for machine learning models, but the README does not specify the matrix format, the library, or the downstream model. If your goal is a production ingestion pipeline with retries and schema management, this repository is the wrong tool. It is a reference implementation, and the README's own framing (legacy educational example) sets that expectation. The modern example raises the ceiling but is scoped to a sample CSV with a --limit flag, not to bulk loads.
py2neo v3 against the official Neo4j driver
The real alternative is not another repository. It is the official neo4j Python driver, and this repository contains both so the difference is visible in one place. py2neo 3 offers an object-oriented layer: the legacy code wraps node and relationship creation in DataToNeo4jClass, which reads as graph objects being constructed and saved. The official driver works closer to the wire, with sessions and Cypher statements, which is why the modern example pairs it with vector indexes and GraphRAG-style retrieval rather than with object mapping. The trade-off is legibility against longevity. The py2neo path is easier to read for someone learning graph modeling, and it is tied to a server generation that predates vector search. The official driver path is where Neo4j 5+/2026 vector indexes and neo4j-graphrag embeddings live, and it is the path that will keep receiving upstream fixes. If you are starting today and your server is Neo4j 5 or later, the legacy half is a reading exercise, not a starting point. If you are maintaining a py2neo 3 script, the modern example shows the shape of the migration without pretending it is mechanical.
Licence, governance, and what to check before you clone
The project is MIT licensed, which permits reuse and modification with the licence and copyright notice retained; that is a summary of the identifier, not legal advice. The repository also carries CONTRIBUTING.md, SECURITY.md, SUPPORT.md, CODE_OF_CONDUCT.md, and a pull request template, and the README states that maintenance is tracked publicly through issues and releases. The release history in the supplied material shows v0.3.0, v0.3.1, and v0.4.0 all dated 2026-06-01, which is consistent with the README's statement that the project is maintained again as of 2026-06. Three releases on one day is a burst, not a cadence, so do not read the version numbers as a stability signal. The roadmap's v0.4.x items (evaluating newer Python and pandas, documenting the py2neo v3 migration path, adding CI where practical) are listed as plans. Before cloning, check the README's compatibility section against your own interpreter and server versions, decide which of the two pipelines you actually need, and open invoice_neo4j.py and DataToNeo4jClass.py to confirm the two placeholder edits are where the README says they are. If your environment is Python 3.6.5 with Neo4j 3.x, the legacy path is the one that matches. Anything newer, start at examples/modern_invoice_graphrag/.
Editorial conclusion
Adopt it if you want a small, readable reference for turning spreadsheet rows into Neo4j nodes and edges, or if you need to keep a py2neo v3 script running on Neo4j 3.x while you plan a migration. Do not adopt the legacy half for a new build: the pinned requirements are intentionally old and the README says modernization is tracked in issue #23, not in the code. Before cloning, verify your Neo4j server version, confirm whether you need the py2neo path or the official driver path, and check that the sample Invoice_data_Demo.xls columns match the extraction functions you intend to reuse.
Community notes