---
title: "Neo4j to HeliosDB Migration Guide"
---

# Neo4j to HeliosDB Migration Guide

:::caution[Planned]
Graph-RAG and Code-Graph for HeliosDB Full are planned. Code-Graph (`hdb_code`),
Graph-RAG (`WITH CONTEXT`) and the native MCP server are available in HeliosDB Nano
as build-from-source features. The Cypher queries and GraphRAG features on this page
are not reachable in the current HeliosDB Full release; this page describes the planned feature.
:::

> **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](mailto:sales@heliosdb.com). The examples on this page use `heliosdb-full:<tag>`, an image built locally from the licensed source distribution (`docker build -t heliosdb-full:<tag> .`); replace it with the image reference you receive if you use the private registry.

## Why Migrate?

### Performance Improvements

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

| 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 Full |
|---------|-----------|--------------|
| Cypher Support | | |
| GQL Support | Partial | Full |
| Vector Embeddings | No (external) | Native |
| HTAP | No | |
| RAG Framework | No | |
| 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**
```bash
docker pull registry.example.com/heliosdb/heliosdb-graph:<tag>
docker run -p 7687:7687 registry.example.com/heliosdb/heliosdb-graph:<tag>
```

### Phase 3: Data Migration (2-5 days)

**3.1 Export from Neo4j**

**Option A: Cypher Export**
```cypher
-- 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**
```cypher
CALL apoc.export.json.all("export.json", {})
```

**Option C: Neo4j Admin Tool**
```bash
neo4j-admin database dump neo4j --to-path=/backup
```

### Phase 4: Query Migration (1-2 days)

**4.1 Cypher Compatibility**

Most queries work unchanged:
```cypher
-- 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 |

### 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**:
```cypher
(: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**:
```cypher
# Neo4j
(:Document {id, text})

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

**HeliosDB**:
```rust
// 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: support@heliosdb.com
- Community: [Discord](https://discord.gg/yTykuUrFXc)
- Professional Services: Available for complex migrations

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

---