GraphIO

OGM and data loader for Neo4j with two main approaches:

OGM (Object Graph Mapper): Pydantic-based models with Neo4j integration for complex data models and applications
Datasets (NodeSet/RelationshipSet): Bulk data containers optimized for fast data loading and testing
Multi-Database Support: Full support for Neo4j Enterprise Edition multi-database feature

Documentation

Docs available at: https://graphio.readthedocs.io

Quick Start

Installation

Install graphio from PyPI:

pip install graphio

Install the latest version from GitHub:

pip install git+https://github.com/kaiserpreusse/graphio.git

Example

from graphio import NodeModel, Base
from neo4j import GraphDatabase

# Set up connection
driver = GraphDatabase.driver('neo4j://localhost:7687', auth=('neo4j', 'password'))
Base.set_driver(driver)
# Optional: Set target database (Enterprise Edition)
# Base.set_database('production')

# Define OGM model for structure and validation
class Person(NodeModel):
    _labels = ['Person']
    _merge_keys = ['email']
    name: str
    email: str

# Get bulk container directly from OGM model
people = Person.dataset()  # Automatically uses Person's labels and merge_keys

for person_data in large_dataset:
    # Create validated OGM instance and add directly
    person = Person(**person_data)  # Pydantic validation happens here
    people.add(person)  # Add validated instance to bulk dataset

people.create(driver)  # Bulk create with validation benefits

# Use OGM for application logic
alice = Person.match(Person.email == 'alice@example.com').first()

Development

Prerequisites

Python 3.10+
uv (recommended) or pip
Docker for running test databases

Setup

# Clone the repository
git clone https://github.com/kaiserpreusse/graphio.git
cd graphio

# Install dependencies
uv sync --extra dev

# Start Neo4j test databases
make localdb

Common Commands

# Run tests
make test

# Check code style  
make lint

# Format code
make format

# Fix linting issues and format
make fix

# Run all checks (lint + test)
make check

# Serve documentation locally
make docs

# See all available commands
make help

Testing

The test suite requires Docker containers running Neo4j. Start them with:

make localdb

Then run tests with:

make test
# or directly:
uv run pytest

All tests using the graph fixture will run against both Neo4j Community and Enterprise editions.

Feedback

Please provide feedback, ideas and bug reports through GitHub issues.

Release files for graphio 0.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for graphio 0.22
File	Size	Uploaded
graphio-0.22.tar.gz	97.5 kB	Aug 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for graphio 0.22
File	Interpreter	ABI	Platform	Reset
graphio-0.22-py3-none-any.whl 27.1 kB Aug 12, 2026	Python 3	none	any	Details

Total release size: 124.6 kB

Release files / graphio-0.22.tar.gz

Download URL	graphio-0.22.tar.gz
Size	97.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`6ed578ddfa4daaed368bf7c54a099ae2df2962fb0a3639251248d2f04f1a9bdf`
BLAKE2b-256 checksum How to use checksums	`bf7eea9127fa66a25348522b8d744dce62d455959596fe8dab5c86cf048c674c`
Upload date	Aug 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.15`

Release files / graphio-0.22-py3-none-any.whl

Download URL	graphio-0.22-py3-none-any.whl
Size	27.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`524e4606f1ef40575a53a8f7bc4d5e86bfc8ce20db64c95c37ebb06280c21f1e`
BLAKE2b-256 checksum How to use checksums	`c1ce6cec8bebe25ffbc576e3ac648531c6a7f96e65d30399ad5440cf145bd93b`
Upload date	Aug 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.15`