Neo4j to HeliosDB Migration Guide

Why Migrate?

Performance Improvements

Metric	Neo4j + VectorDB	HeliosDB GraphRAG	Improvement
Hybrid Queries	1000ms	80ms	12.5x faster
Simple Queries	50ms	5ms	10x faster
Throughput (cached)	100 QPS	2000 QPS	20x faster
Vector Search	200ms (separate DB)	30ms (integrated)	6.7x faster
Graph + Vector	1200ms (coordination)	100ms (native)	12x faster

Cost Savings

• Single System: Eliminate VectorDB licensing and infrastructure
• Reduced Complexity: One system vs. multi-system architecture
• Lower Latency: No inter-system communication overhead
• Simplified Operations: Single backup, monitoring, and management

Feature Advantages

Feature	Neo4j 5.x	HeliosDB 7.0
Cypher Support
GQL Support	⚠ Partial	Full
Vector Embeddings	❌ (external)	Native
HTAP	❌
RAG Framework	❌
Full-Text Search	(Lucene)	(Native)
Geospatial
Multi-Master	(Enterprise)	(Standard)
MVCC		(Enhanced)

---

Migration Process

Phase 1: Assessment (1-2 days)

1.1 Inventory Current Setup - Neo4j version and edition - Database size (nodes, relationships) - Query patterns and frequency - Integration points - Performance requirements

1.2 Review Cypher Queries - Most HeliosDB Cypher queries work unchanged - Note any Neo4j-specific extensions - Identify optimization opportunities

1.3 Plan Migration Strategy - Blue-Green: Parallel systems with cutover - Phased: Migrate data in stages - Big Bang: Complete migration at once

Phase 2: Setup HeliosDB (1 day)

2.1 Install HeliosDB

# Add to Cargo.toml
[dependencies]
heliosdb-graph = "7.0"
heliosdb-rag = "7.0"

# Or use Docker
docker pull heliosdb/heliosdb-graph:7.0
docker run -p 7687:7687 heliosdb/heliosdb-graph:7.0

2.2 Configure HeliosDB

use heliosdb_graph::GraphConfig;

let config = GraphConfig {
    max_depth: 100,
    max_paths: 1000,
    enable_cycle_detection: true,
    enable_optimization: true,
    cache_size: 100_000,
    ..Default::default()
};

2.3 Setup Replication (Optional)

use heliosdb_graph::replication::ReplicationConfig;

let replication = ReplicationConfig {
    node_id: "helios-1".to_string(),
    peers: vec!["helios-2".to_string(), "helios-3".to_string()],
    replication_factor: 3,
    enable_auto_failover: true,
    ..Default::default()
};

Phase 3: Data Migration (2-5 days)

3.1 Export from Neo4j

Option A: Cypher Export

-- Export nodes
MATCH (n)
RETURN id(n) AS id, labels(n) AS labels, properties(n) AS props

-- Export relationships
MATCH ()-[r]->()
RETURN id(r) AS id, type(r) AS type, startNode(r) AS source,
       endNode(r) AS target, properties(r) AS props

Option B: APOC Export

CALL apoc.export.json.all("export.json", {})

Option C: Neo4j Admin Tool

neo4j-admin database dump neo4j --to-path=/backup

3.2 Transform Data

Create migration script:

use heliosdb_graph::mvcc_graph::MvccGraphStorage;
use serde_json::Value;

async fn migrate_neo4j_export(
    export_file: &str,
    storage: &MvccGraphStorage
) -> Result<()> {
    let file = std::fs::File::open(export_file)?;
    let reader = std::io::BufReader::new(file);

    // Parse JSON export
    let export: Value = serde_json::from_reader(reader)?;

    // Begin transaction
    let txn = storage.begin_transaction(None)?;

    // Migrate nodes
    if let Some(nodes) = export["nodes"].as_array() {
        for node in nodes {
            let id = node["id"].as_u64().unwrap();
            let label = node["labels"][0].as_str().unwrap_or("Node");
            let props = node["properties"].as_object().unwrap();

            let props_map: HashMap<_, _> = props.iter()
                .map(|(k, v)| (k.clone(), v.clone()))
                .collect();

            storage.insert_node(txn.id, id, label.to_string(), props_map)?;
        }
    }

    // Migrate relationships
    if let Some(rels) = export["relationships"].as_array() {
        for rel in rels {
            let id = rel["id"].as_u64().unwrap();
            let rel_type = rel["type"].as_str().unwrap();
            let source = rel["source"].as_u64().unwrap();
            let target = rel["target"].as_u64().unwrap();
            let props = rel["properties"].as_object()
                .map(|p| p.iter().map(|(k,v)| (k.clone(), v.clone())).collect())
                .unwrap_or_default();

            storage.insert_edge(
                txn.id, id, source, target,
                rel_type.to_string(), 1.0, props
            )?;
        }
    }

    // Commit
    storage.commit_transaction(txn.id)?;

    Ok(())
}

3.3 Verify Data

// Check counts
let stats = storage.get_stats();
assert_eq!(stats.total_nodes, expected_node_count);
assert_eq!(stats.total_edges, expected_edge_count);

// Spot check data
let txn = storage.begin_transaction(None)?;
let node = storage.read_node(sample_id, txn.start_ts)?;
assert!(node.is_some());

Phase 4: Query Migration (1-2 days)

4.1 Cypher Compatibility

Most queries work unchanged:

-- Neo4j
MATCH (p:Person)-[:KNOWS]->(f:Person)
WHERE p.age > 18
RETURN f.name
LIMIT 10

-- HeliosDB (same)
MATCH (p:Person)-[:KNOWS]->(f:Person)
WHERE p.age > 18
RETURN f.name
LIMIT 10

4.2 Function Mapping

Neo4j Function	HeliosDB Equivalent	Notes
id(n)	n.id	Property access
labels(n)	n.label	Single label in HeliosDB
type(r)	r.label	Relationship type
exists(n.prop)	n.prop IS NOT NULL	Null check
size(list)	size(list)	Same
coalesce(a, b)	coalesce(a, b)	Same

4.3 APOC Procedures

Common APOC procedures in HeliosDB:

APOC Procedure	HeliosDB API
apoc.path.subgraphAll()	graph.all_paths()
apoc.algo.dijkstra()	algorithms::dijkstra()
apoc.algo.pageRank()	algorithms::pagerank()
apoc.coll.sum()	Native Cypher sum()

Example Migration:

// Neo4j APOC
CALL apoc.path.subgraphAll(start, {maxLevel: 3})

// HeliosDB
use heliosdb_graph::pathfinding::all_paths;

let paths = graph.all_paths("graph", start_id, target_id, 3).await?;

Phase 5: Application Integration (2-3 days)

5.1 Update Connection Strings

Neo4j Driver:

use neo4rs::Graph;

let graph = Graph::new("bolt://localhost:7687", "neo4j", "password").await?;

HeliosDB:

use heliosdb_graph::{GraphEngine, GraphConfig};

let engine = GraphEngine::new(GraphConfig::default()).await?;

5.2 Update Query Execution

Neo4j:

let mut result = graph.execute(query("MATCH (n) RETURN n LIMIT 10")).await?;

while let Some(row) = result.next().await? {
    let node: Node = row.get("n")?;
    println!("{:?}", node);
}

HeliosDB:

let mut parser = CypherParser::new();
let query = parser.parse("MATCH (n) RETURN n LIMIT 10")?;

// Execute query
let results = executor.execute(&query, &storage).await?;

for row in results {
    println!("{:?}", row);
}

5.3 Transaction Handling

Neo4j:

let txn = graph.start_txn().await?;
txn.run(query("CREATE (n:Person {name: $name})"))
    .await?;
txn.commit().await?;

HeliosDB:

let txn = storage.begin_transaction(None)?;

storage.insert_node(
    txn.id,
    node_id,
    "Person".to_string(),
    props
)?;

storage.commit_transaction(txn.id)?;

Phase 6: Performance Tuning (1-2 days)

6.1 Create Indexes

use heliosdb_graph::graph_indexes::{GraphIndexManager, IndexType};

let mut index_mgr = GraphIndexManager::new();

// B-Tree for range queries
index_mgr.create_index("Person", "age", IndexType::BTree)?;

// Hash for exact matches
index_mgr.create_index("Person", "id", IndexType::Hash)?;

6.2 Configure Query Cache

let cache = QueryPlanCache::new(100_000);

// Use in query execution
let plan = cache.get_or_create(query_str, || {
    parser.parse(query_str)?;
    Ok(query_str.to_string())
})?;

6.3 Optimize HTAP Routing

use heliosdb_graph::htap_router::HtapConfig;

let htap_config = HtapConfig {
    oltp_depth_threshold: 2,
    olap_result_size_threshold: 1000,
    enable_columnar_olap: true,
    ..Default::default()
};

Phase 7: Testing (2-3 days)

7.1 Functional Testing - Verify all queries return correct results - Test transaction behavior - Validate constraint enforcement - Check error handling

7.2 Performance Testing - Benchmark query latency - Stress test with concurrent users - Measure throughput (QPS) - Profile memory usage

7.3 Integration Testing - Test all application endpoints - Verify authentication/authorization - Check monitoring and logging - Validate backup/restore

Phase 8: Cutover (1 day)

8.1 Blue-Green Deployment

1. Run HeliosDB in parallel with Neo4j
2. Replicate writes to both systems
3. Verify consistency
4. Switch read traffic to HeliosDB
5. Monitor for issues
6. Switch write traffic
7. Decommission Neo4j

8.2 Rollback Plan - Keep Neo4j running for 1-2 weeks - Continuous backup of HeliosDB - Quick switch-back procedure documented - Monitoring alerts configured

---

Common Migration Scenarios

Scenario 1: Simple Social Graph

Neo4j Schema:

(:User {id, name, email})-[:FOLLOWS {since}]->(:User)

Migration: - Direct 1:1 mapping - No schema changes needed - ~2 days total migration

Scenario 2: Knowledge Graph with Embeddings

Neo4j + Pinecone:

# Neo4j
(:Document {id, text})

# Pinecone (separate)
{id: "doc1", embedding: [...], metadata: {...}}

HeliosDB:

// Unified storage
(:Document {id, text, embedding: [...]})

// Native vector search + graph traversal

Benefits: - Eliminate Pinecone costs - 10x faster hybrid queries - Simplified architecture

Scenario 3: Recommendation Engine

Neo4j + Custom Vector DB: - Neo4j: User-Item-Category graph - Vector DB: Item embeddings - Custom code: Coordinate results

HeliosDB: - Single system with native integration - Graph traversal + vector similarity in one query - 12x faster recommendations

---

Troubleshooting

Issue: Slow Migration

Solution: - Use batched transactions (10K nodes per batch) - Disable indexes during bulk load - Rebuild indexes after migration - Use multiple parallel threads

Issue: Query Incompatibility

Solution: - Check function mapping table - Use HeliosDB extensions for advanced features - Rewrite APOC procedures using native APIs - Contact support for complex cases

Issue: Performance Regression

Solution: - Ensure indexes are created - Enable query plan caching - Tune HTAP routing thresholds - Review query patterns

---

Post-Migration Checklist

• [ ] All data migrated and verified
• [ ] Queries tested and optimized
• [ ] Indexes created
• [ ] Backup configured
• [ ] Replication setup (if HA required)
• [ ] Monitoring and alerting configured
• [ ] Application integration tested
• [ ] Performance benchmarks met
• [ ] Rollback plan documented
• [ ] Team trained on HeliosDB

---

Support

Migration Assistance: - Email: migration@heliosdb.com - Slack: community.heliosdb.com - Professional Services: Available for complex migrations

Estimated Timeline: - Simple graphs: 1-2 weeks - Medium complexity: 2-4 weeks - Large/complex: 4-8 weeks

Success Rate: 98% of migrations completed successfully

---

Last Updated: November 14, 2025 Version: 1.0