---
title: "HeliosDB GraphRAG HTAP - Complete User Guide"
---

# HeliosDB GraphRAG HTAP - Complete User 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.
:::

---

## Table of Contents

1. [Introduction](#1-introduction)
2. [Core Concepts](#2-core-concepts)
3. [Cypher Query Language](#3-cypher-query-language)
4. [GQL Support](#4-gql-support)
5. [HTAP Architecture](#5-htap-architecture)
6. [Performance Tuning](#6-performance-tuning)

---

## 1. Introduction

### What is GraphRAG HTAP?

HeliosDB GraphRAG HTAP combines:
- **Graph Database**: Native property graph with Cypher and GQL support
- **Vector Database**: Integrated embeddings for semantic search
- **RAG Framework**: Built-in Retrieval-Augmented Generation
- **HTAP Engine**: Hybrid Transactional/Analytical Processing

### Key Benefits

- **10x Faster**: Outperforms Neo4j + VectorDB combinations
- **Unified Platform**: Single system vs. fragmented architecture
- **Operations**: WAL, backup/restore, replication, PITR
- **ACID Compliant**: Full MVCC with multiple isolation levels
- **Scalable**: Tested with 10M+ nodes, 100M+ edges

### Use Cases

1. **Knowledge Graphs with LLM Integration**
   - Build intelligent chatbots with graph-backed knowledge
   - Implement RAG pipelines with relationship-aware retrieval
   - Combine structured and semantic search

2. **Real-Time Analytics**
   - OLTP queries for user interactions
   - OLAP queries for business intelligence
   - Automatic routing based on query complexity

3. **Graph Machine Learning**
   - Node/edge embeddings with graph structure
   - Community detection and influence analysis
   - Recommendation systems with graph context

---

## 2. Core Concepts

### 2.1 Property Graph Model

HeliosDB uses the property graph model:

**Nodes** (vertices):
- Unique ID
- Label(s)
- Properties (key-value pairs)

**Edges** (relationships):
- Unique ID
- Source and target nodes
- Type/label
- Weight (for weighted graphs)
- Properties

**Example**:
```
(:Person {name: "Alice", age: 30})-[:KNOWS {since: 2020}]->(:Person {name: "Bob"})
```

### 2.2 MVCC (Multi-Version Concurrency Control)

Every modification creates a new version.

**Isolation Levels**:
- Read Committed: See committed changes
- Repeatable Read: Consistent snapshot
- Serializable: Full serializability (with conflict detection)

### 2.3 HTAP Query Routing

Queries are automatically routed:

**OLTP** (low latency):
- Point queries (single node/edge lookup)
- Short paths
- Small result sets

**OLAP** (high throughput):
- Aggregations (COUNT, AVG, SUM)
- Long traversals
- Graph algorithms

**Hybrid**:
- Mixed workloads
- Adaptive execution

---

## 3. Cypher Query Language

### 3.1 Basic Queries

**MATCH**: Find patterns

```cypher
-- Find all persons
MATCH (p:Person) RETURN p

-- Find friends
MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a.name, b.name

-- Variable-length paths
MATCH (a:Person)-[:KNOWS*1..3]->(b:Person)
WHERE a.name = 'Alice'
RETURN b.name
```

**CREATE**: Insert data

```cypher
-- Create node
CREATE (p:Person {name: 'Charlie', age: 25})

-- Create relationship
MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
CREATE (a)-[:KNOWS {since: 2020}]->(b)
```

**UPDATE**: Modify data

```cypher
-- Update properties
MATCH (p:Person {name: 'Alice'})
SET p.age = 31, p.city = 'NYC'

-- Add label
MATCH (p:Person {name: 'Alice'})
SET p:Employee
```

**DELETE**: Remove data

```cypher
-- Delete relationship
MATCH (a:Person)-[r:KNOWS]->(b:Person)
WHERE a.name = 'Alice'
DELETE r

-- Delete node (and relationships)
MATCH (p:Person {name: 'Charlie'})
DETACH DELETE p
```

### 3.2 Advanced Cypher

**Aggregations**:
```cypher
-- Count nodes
MATCH (p:Person) RETURN count(p)

-- Average age
MATCH (p:Person) RETURN avg(p.age)

-- Group by
MATCH (p:Person)
RETURN p.city, count(p), avg(p.age)
```

**Ordering and Limiting**:
```cypher
MATCH (p:Person)
RETURN p.name, p.age
ORDER BY p.age DESC
LIMIT 10
SKIP 5
```

**Conditional Logic**:
```cypher
MATCH (p:Person)
RETURN p.name,
       CASE
         WHEN p.age < 18 THEN 'Minor'
         WHEN p.age >= 18 AND p.age < 65 THEN 'Adult'
         ELSE 'Senior'
       END AS ageGroup
```

**Subqueries**:
```cypher
MATCH (p:Person)
WHERE EXISTS {
  MATCH (p)-[:KNOWS]->(:Person {city: 'NYC'})
}
RETURN p.name
```

### 3.3 Performance Tips

1. **Use LIMIT Early**:
```cypher
-- Good
MATCH (p:Person)
WHERE p.age > 18
RETURN p
LIMIT 10

-- Less efficient
MATCH (p:Person)
RETURN p
WHERE p.age > 18
LIMIT 10
```

---

## 4. GQL Support

HeliosDB supports ISO GQL (Graph Query Language), the new standard.

### 4.1 Basic GQL Queries

```gql
-- Select nodes
SELECT *
FROM GRAPH myGraph
MATCH (p:Person)
WHERE p.age > 18

-- Path queries
SELECT p.name, f.name
FROM GRAPH myGraph
MATCH (p:Person)-[:KNOWS]->(f:Person)
WHERE p.name = 'Alice'
```

### 4.2 GQL vs Cypher

| Feature | Cypher | GQL |
|---------|--------|-----|
| Standard | Industry | ISO Standard |
| Syntax | MATCH-based | SELECT-based |
| Learning Curve | Low | Medium |
| Compatibility | Neo4j-like | SQL-like |

**When to use GQL**:
- You prefer SQL-style syntax
- Need ISO standard compliance
- Working with tools expecting GQL

**When to use Cypher**:
- Migrating from Neo4j
- Prefer graph-native syntax
- Shorter, more concise queries

---

## 5. HTAP Architecture

### 5.1 How HTAP Works

```
                    Query
                      |
                      v
              +---------------+
              | Query Router  |
              +---------------+
                 /         \
                /           \
               v             v
        +----------+    +----------+
        |   OLTP   |    |   OLAP   |
        | (Row)    |    | (Column) |
        +----------+    +----------+
              \           /
               \         /
                v       v
            +-------------+
            | MVCC Storage|
            +-------------+
```

---

## 6. Performance Tuning

### 6.1 Performance Targets

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

| Metric | Target | Typical |
|--------|--------|---------|
| Simple query latency | <10ms | 2-5ms |
| Complex query latency | <100ms | 30-80ms |
| Throughput (cached) | 1000 QPS | 2000+ QPS |
| Throughput (uncached) | 500 QPS | 800 QPS |
| Node insertion | <5ms | 1-3ms |
| Transaction commit | <10ms | 3-7ms |

---

## Conclusion

This user guide covers the essentials of HeliosDB GraphRAG HTAP. For more information:

- **API Documentation**: https://www.heliosdb.com/docs/full/
- **Support**: support@heliosdb.com
- Community: [Discord](https://discord.gg/yTykuUrFXc)

**Production Checklist**:
- [ ] Configure appropriate index strategy
- [ ] Enable WAL and configure checkpointing
- [ ] Set up backup schedule
- [ ] Configure replication for HA
- [ ] Implement monitoring and alerting
- [ ] Performance test with production workload
- [ ] Review security configuration