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.

To run the suite against other servers, set GRAPHIO_TEST_TARGETS to a JSON array of targets. It replaces the default targets; name is used as the pytest parameter id. The suite wipes each target database before every test.

GRAPHIO_TEST_TARGETS='[
  {"name": "lts", "uri": "bolt://127.0.0.1:17687", "user": "neo4j", "password": "kwela-harness"},
  {"name": "cal", "uri": "bolt://127.0.0.1:27687", "user": "neo4j", "password": "kwela-harness"}
]' uv run pytest

Feedback

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

Metadata

Release files for graphio 0.23

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.23
File	Size	Uploaded
graphio-0.23.tar.gz	99.2 kB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for graphio 0.23
File	Interpreter	ABI	Platform	Reset
graphio-0.23-py3-none-any.whl 27.7 kB Oct 13, 2026	Python 3	none	any	Details

Total release size: 126.9 kB

Release files / graphio-0.23.tar.gz

Download URL	graphio-0.23.tar.gz
Size	99.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`ef2ddceddb2dba4816fabe0701f18f2e7a8b688678bbe045d3456365ed529007`
BLAKE2b-256 checksum How to use checksums	`917d41ee0759ef2c472f1c3167725331f23ef68b12c47b95961b478b576fcee2`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.17`

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

Download URL	graphio-0.23-py3-none-any.whl
Size	27.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`aa72445df71c0b7cc828d7dd7e6e3d659c7104f274cd7f3236f3a573187343f2`
BLAKE2b-256 checksum How to use checksums	`30267a8ae42e06a738ceef799d44e87253e4417d0750004002b1fe98b306bf6d`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.17`