Grafeo

0.5.41 verified Fri May 01 auth: no python

A high-performance, embeddable graph database with Python bindings. Current version 0.5.41, released 2026-04-24. Rapid release cadence, often multiple releases per week. Supports multiple query languages (GQL, Cypher, SPARQL, GraphQL, SQL/PGQ, Gremlin), hybrid graph+vector+text search, encryption at rest, and role-based access control.

pip install grafeo

Common errors

error ModuleNotFoundError: No module named 'grafeodb' ↓

cause Wrong import; package name is 'grafeo' not 'grafeodb'.

fix

Install 'grafeo' and import as 'from grafeo import GrafeoDB'.

error AttributeError: 'QueryResult' object has no attribute 'rows' ↓

cause Attribute .rows is private since v0.5.35.

fix

Use .rows() or .into_rows() instead.

error ValueError: unsupported type for parameter ↓

cause QueryBuilder.param() rejects unsupported types since v0.5.38.

fix

Pass only str, int, float, bool, None, or bytes.

error grafeo.exceptions.StorageError: database format is too old ↓

cause Database created with pre-0.5.35 version.

fix

Re-create database from scratch or migrate via export/import.

Warnings

breaking Starting from v0.5.35, QueryResult.rows is private; use rows() or into_rows() instead. ↓

fix Replace .rows with .rows() or .into_rows().

breaking On-disk storage format changed in v0.5.35 from bincode blobs to block-based sections. Databases created with 0.5.34 or earlier must be re-created. ↓

fix Export data from old database and import into new database.

breaking QueryBuilder.param() now raises ValueError on unsupported types instead of silently dropping them (since v0.5.38). ↓

fix Ensure all parameter types are supported (strings, numbers, etc.).

deprecated Feature profiles 'embedded', 'browser', 'server', 'full' are deprecated in v0.5.35; use persona-based profiles: 'lpg', 'rdf', 'analytics', 'ai', 'edge', 'enterprise'. ↓

fix Switch to persona-based profiles when installing or building from source.

gotcha When using encryption at rest (AES-256-GCM), the password or key must be provided at database creation time and cannot be changed later without re-encryption. ↓

fix Pass encryption config on first open; if re-creating, use compact() on the original first.

gotcha HLC timestamps (Hybrid Logical Clock) introduced in v0.5.32 are mandatory for causal consistency. Sessions may fail if clocks are skewed beyond accepted drift. ↓

fix Ensure system clock is synchronized (e.g., NTP).

gotcha Vector search requires the 'ai' or 'analytics' profile. Plain 'lpg' or 'rdf' profiles may not include vector indexes. ↓

fix Install with correct profile: pip install grafeo[ai] or similar.

Imports

GrafeoDB

wrong

from grafeodb import GrafeoDB

correct

from grafeo import GrafeoDB

The package is 'grafeo', not 'grafeodb'.

GrafeoSession
```
from grafeo import GrafeoSession
```
QueryResult
```
from grafeo import QueryResult
```

Quickstart

Creates an embedded graph database, opens a session, runs a Cypher query, prints results.

from grafeo import GrafeoDB

db = GrafeoDB("mygraph.grafeo")
session = db.session()
result = session.execute("CREATE (a:Person {name: 'Alice'}) RETURN a")
print(result.rows())
db.close()