Performance Baselines¶

Measured performance characteristics showing what to expect from Grafeo.

Insert Performance¶

Node Insertion¶

Edge Insertion¶

Query Performance¶

Point Lookups¶

Pattern Matching¶

Tested on a social network graph with 1M nodes and 10M edges:

Aggregations¶

Tested on 1M nodes with age property:

Graph Algorithm Performance¶

All benchmarks on graphs with 1M nodes unless noted:

Scaling Behavior¶

PageRank on varying graph sizes:

Vector Search Performance¶

Using HNSW index with 128-dimensional vectors:

Recall vs Speed Tradeoff¶

Memory Usage¶

Per-Entity Overhead¶

Index Memory¶

Working Set Sizes¶

Approximate memory for graph operations:

Transaction Performance¶

Single-Threaded¶

Concurrent Transactions¶

4 threads, read-heavy workload (90% reads):

Block-STM (Batch Mode)¶

When processing batches of similar transactions:

Compression Effectiveness¶

On typical graph data:

Overall storage reduction: 40-60% compared to uncompressed.

Benchmark Comparisons (LDBC-Inspired)¶

Results from graph-bench (SF0.1), which includes workloads inspired by the LDBC Social Network Benchmark. Methodology: 3 warmup runs, 10 measured runs, median reported.

Embedded (in-process)¶

Server (over network)¶

Full results: embedded | server

Arrow Export Performance¶

The Arrow bulk export path (nodes_to_arrow(), edges_to_arrow() and their Polars/pandas variants) builds a single RecordBatch in Rust and serializes it as IPC bytes. Python receives the buffer in one call with no per-element PyO3 crossings.

The existing nodes_df()/edges_df() auto-detect pyarrow at runtime and use the Arrow fast path when available. Installing pyarrow speeds up all DataFrame exports without code changes.

Ring Index Performance¶

The Ring Index (ring-index feature) stores RDF triples in a wavelet-tree structure that supports all six triple-pattern access orders (SPO, SOP, PSO, POS, OSP, OPS) in a single compact index.

The SPARQL planner automatically selects Ring Index when available. Leapfrog worst-case optimal join (WCOJ) handles multi-way star joins without intermediate materialization. For patterns requiring LANG or DATATYPE columns (not stored in the ring), the planner falls back to hash join.

Optimizing Performance¶

Index Strategy¶

Create indexes for frequently-queried properties:

# Before: O(n) scan
db.find_nodes_by_property("email", "alix@example.com")  # 50ms on 1M nodes

# Create index
db.create_property_index("email")

# After: O(1) lookup
db.find_nodes_by_property("email", "alix@example.com")  # 0.01ms

Batch Operations¶

Use batch APIs for bulk operations:

# Slow: Individual calls
for node_id in node_ids:
    props = db.get_node(node_id).properties  # 1000 calls = 1ms each = 1s total

# Fast: Batch call
results = db.get_nodes_by_label("Person", limit=1000)  # Single call = 10ms

Query Hints¶

Add LIMIT to exploratory queries:

# Potentially slow
db.execute("MATCH (n:Person)-[:KNOWS*1..5]->(m) RETURN n, m")

# Bounded
db.execute("MATCH (n:Person)-[:KNOWS*1..5]->(m) RETURN n, m LIMIT 1000")

Memory Configuration¶

For large graphs, configure memory limits via GQL:

from grafeo import GrafeoDB

db = GrafeoDB()

# Set memory limit via database configuration
db.execute("SET DATABASE OPTION memory_limit = 8589934592")   # 8GB
db.execute("SET DATABASE OPTION spill_path = '/tmp/grafeo_spill'")

Workload Profiling¶

Use built-in statistics:

# Check database stats
stats = db.detailed_stats()
print(f"Memory usage: {stats['memory_bytes'] / 1024**2:.1f} MB")

# Check if indexes exist
print(f"Has email index: {db.has_property_index('email')}")

# Schema overview
schema = db.schema()
for label in schema['labels']:
    print(f"{label['name']}: {label['count']} nodes")

For detailed profiling, use Python's cProfile:

import cProfile
import pstats

with cProfile.Profile() as pr:
    result = db.execute("MATCH (n:Person)-[:KNOWS]->(m) RETURN n, m LIMIT 1000")

stats = pstats.Stats(pr)
stats.sort_stats('cumulative')
stats.print_stats(10)