Performance

This document covers GraphQLite's performance characteristics and optimization strategies.

Benchmarks

Benchmarks on Apple M1 Max (10 cores, 64GB RAM).

Insertion Performance

Traversal by Topology

Graph Algorithms

Cypher Query Performance

Optimization Strategies

Use Indexes Effectively

GraphQLite creates indexes on:

• nodes(user_id) - Fast node lookup by ID
• nodes(label) - Fast filtering by label
• edges(source_id), edges(target_id) - Fast traversal
• Property tables on (node_id, key) - Fast property access

Queries that leverage these indexes are fast.

Limit Variable-Length Paths

Variable-length paths can be expensive:

-- Expensive: unlimited depth
MATCH (a)-[*]->(b) RETURN b

-- Better: limit depth
MATCH (a)-[*1..3]->(b) RETURN b

Use Specific Labels

Labels help filter early:

-- Slower: scan all nodes
MATCH (n) WHERE n.type = 'Person' RETURN n

-- Faster: use label
MATCH (n:Person) RETURN n

Batch Operations

For bulk inserts, use batch methods:

# Slow: individual inserts
for person in people:
    g.upsert_node(person["id"], person, label="Person")

# Fast: batch insert
nodes = [(p["id"], p, "Person") for p in people]
g.upsert_nodes_batch(nodes)

Algorithm Caching

Graph algorithms scan the entire graph. If your graph doesn't change frequently, cache results:

import functools

@functools.lru_cache(maxsize=1)
def get_pagerank():
    return g.pagerank()

Memory Usage

GraphQLite uses SQLite's memory management. Key factors:

• Page cache: SQLite caches database pages in memory
• Algorithm scratch space: Algorithms allocate temporary structures
• Result buffers: Query results are buffered before returning

For large graphs, consider:

# Increase SQLite page cache (default: 2MB)
conn.execute("PRAGMA cache_size = -64000")  # 64MB

Running Benchmarks

Run benchmarks on your hardware:

make performance

This runs:

• Insertion benchmarks
• Traversal benchmarks across topologies
• Algorithm benchmarks
• Query benchmarks