Skip to content
HeliosDB HeliosDB Full

Neo4j to HeliosDB Migration Guide

Neo4j to HeliosDB Migration Guide

Container images: HeliosDB Full images are not published on Docker Hub or any other public registry. Images and Helm charts are provided through private registry access during onboarding: contact sales@heliosdb.com. In the examples on this page, replace heliosdb/heliosdb with the image reference you receive.

Why Migrate?

Performance Improvements

Indicative figures, measured on representative fixtures; reproduce on your own hardware.

MetricNeo4j + VectorDBHeliosDB GraphRAGImprovement
Hybrid Queries1000ms80ms12.5x faster
Simple Queries50ms5ms10x faster
Throughput (cached)100 QPS2000 QPS20x faster
Vector Search200ms (separate DB)30ms (integrated)6.7x faster
Graph + Vector1200ms (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

FeatureNeo4j 5.xHeliosDB 7.0
Cypher Support
GQL Support⚠ PartialFull
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

Terminal window
docker pull heliosdb/heliosdb-graph:7.0
docker run -p 7687:7687 heliosdb/heliosdb-graph:7.0

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

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

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 FunctionHeliosDB EquivalentNotes
id(n)n.idProperty access
labels(n)n.labelSingle label in HeliosDB
type(r)r.labelRelationship type
exists(n.prop)n.prop IS NOT NULLNull check
size(list)size(list)Same
coalesce(a, b)coalesce(a, b)Same

Phase 5: Testing (2-3 days)

5.1 Functional Testing

  • Verify all queries return correct results
  • Test transaction behavior
  • Validate constraint enforcement
  • Check error handling

5.2 Performance Testing

  • Benchmark query latency
  • Stress test with concurrent users
  • Measure throughput (QPS)
  • Profile memory usage

5.3 Integration Testing

  • Test all application endpoints
  • Verify authentication/authorization
  • Check monitoring and logging
  • Validate backup/restore

Phase 6: Cutover (1 day)

6.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

6.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:

Estimated Timeline:

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

Version: 1.0