HeliosDB Architecture
HeliosDB Architecture
System Architecture Diagram
┌─────────────────────────────────────────────────────────────────┐│ Client Applications ││ (Python, Java, Go - PostgreSQL/MySQL wire protocols) │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ Protocol Gateway Layer ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │PostgreSQL│ │ MySQL │ │Snowflake │ │ Pinecone │ ││ │ Handler │ │ Handler │ │ HTTP │ │ Vector │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ Compute Layer ││ ││ ┌────────────────────────────────────────────────────────────┐ ││ │ Query Planner & Optimizer │ ││ │ - SQL Parsing │ ││ │ - Predicate Pushdown Analysis │ ││ │ - Partition Pruning │ ││ │ - Distributed Plan Generation │ ││ └────────────────────────────────────────────────────────────┘ ││ ││ ┌────────────────────────────────────────────────────────────┐ ││ │ Query Executor │ ││ │ - Physical Operators (Scan, Filter, Join, Aggregate) │ ││ │ - Result Merging │ ││ │ - Cache Management │ ││ └────────────────────────────────────────────────────────────┘ ││ ││ Compute Nodes: Stateless, Elastic, Multi-tenant │└─────────────────────────────────────────────────────────────────┘ │ ▼ HIDB Protocol (gRPC over RDMA)┌─────────────────────────────────────────────────────────────────┐│ Storage Layer ││ ││ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ││ │ Shard 1 │ │ Shard 2 │ │ Shard N │ ││ │ │ │ │ │ │ ││ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ ││ │ │ LSM Engine │ │ │ │ LSM Engine │ │ │ │ LSM Engine │ │ ││ │ │ │ │ │ │ │ │ │ │ │ │ ││ │ │ Memtable │ │ │ │ Memtable │ │ │ │ Memtable │ │ ││ │ │ SSTables │ │ │ │ SSTables │ │ │ │ SSTables │ │ ││ │ │ Commit log │ │ │ │ Commit log │ │ │ │ Commit log │ │ ││ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │ ││ │ │ │ │ │ │ ││ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ ││ │ │Predicate │ │ │ │Predicate │ │ │ │Predicate │ │ ││ │ │Filter Engine│ │ │ │Filter Engine│ │ │ │Filter Engine│ │ ││ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │ ││ │ │ │ │ │ │ ││ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ ││ │ │Vector Index │ │ │ │Vector Index │ │ │ │Vector Index │ │ ││ │ │(HNSW/IVF) │ │ │ │(HNSW/IVF) │ │ │ │(HNSW/IVF) │ │ ││ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │ ││ │ │ │ │ │ │ ││ │ Primary: Node A │ │ Primary: Node B │ │ Primary: Node C │ ││ │ Mirror: Node B │ │ Mirror: Node C │ │ Mirror: Node A │ ││ └─────────────────┘ └─────────────────┘ └─────────────────┘ ││ ││ Storage Nodes: Intelligent, Durable, Sharded │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ Metadata & Consensus Layer (Raft) ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││ │ Metadata │ │ Metadata │ │ Metadata │ ││ │ Node 1 │ │ Node 2 │ │ Node 3 │ ││ │ (Leader) │ │ (Follower) │ │ (Follower) │ ││ │ │ │ │ │ │ ││ │ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │ ││ │ │ Raft Log │ │ │ │ Raft Log │ │ │ │ Raft Log │ │ ││ │ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │ ││ │ │ │ │ │ │ ││ │ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │ ││ │ │ Topology │ │ │ │ Topology │ │ │ │ Topology │ │ ││ │ │ Schema │ │ │ │ Schema │ │ │ │ Schema │ │ ││ │ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │ ││ └──────────────┘ └──────────────┘ └──────────────┘ ││ ││ Managed State: Shard Map, Schema, Node Status │└─────────────────────────────────────────────────────────────────┘Data Flow
Write Path
Client │ ▼ SQL INSERTCompute Node (Query Planner) │ ▼ Determine Shard (Consistent Hash)Storage Node (Primary) │ ├─▶ Write to commit log (durability) │ ├─▶ Insert into Memtable (in-memory) │ └─▶ Replicate to Mirror (sync) │ └─▶ Mirror acknowledges │ └─▶ Return success to clientRead Path (Point Query)
Client │ ▼ SQL SELECT WHERE key=?Compute Node (Query Planner) │ ├─▶ Check local cache │ └─▶ HIT: Return │ └─▶ MISS: Route to shard │ ▼Storage Node │ ├─▶ Check Memtable │ └─▶ FOUND: Return │ ├─▶ Check Immutable Memtables │ └─▶ FOUND: Return │ └─▶ Check SSTables (with Bloom filter) │ ├─▶ Bloom MISS: Skip SSTable │ └─▶ Bloom HIT: Read SSTable └─▶ Return to compute └─▶ Return to clientAnalytical Query with Predicate Pushdown
Client │ ▼ SQL SELECT * FROM table WHERE col > 100Compute Node │ ├─▶ Parse & Optimize │ └─▶ Identify pushable predicates │ ├─▶ Build predicate pushdown request │ ├─▶ predicates: [col > 100] │ └─▶ projection: [col1, col2, col3] │ └─▶ Dispatch to all relevant shards (parallel) │ ▼Storage Nodes (parallel execution) │ ├─▶ Apply predicates locally │ ├─▶ Scan SSTables (HCC compressed) │ ├─▶ Decompress only needed columns │ └─▶ Filter rows │ └─▶ Stream filtered result set │ ▼Compute Node │ ├─▶ Merge results from all shards ├─▶ Apply remaining operations │ (joins, aggregates, sort) └─▶ Return to clientVector Similarity Search
Client │ ▼ SQL SELECT * FROM docs WHERE vector_similarity(embedding, ?) < 0.1 AND category = 'tech'Compute Node │ ├─▶ Extract query vector ├─▶ Build vector search request │ ├─▶ query_vector: [0.1, 0.2, ...] │ ├─▶ predicates: [category = 'tech'] │ └─▶ top_k: 10 │ └─▶ Dispatch to shards │ ▼Storage Nodes │ ├─▶ Build allow-list from predicates │ └─▶ Bitmap: category='tech' rows │ ├─▶ Traverse HNSW index │ ├─▶ Check allow-list before distance calc │ └─▶ Multi-hop for filtered islands │ └─▶ Return vector search results │ ▼Compute Node │ ├─▶ Merge top-k from all shards ├─▶ Re-rank globally └─▶ Return to clientSharding Strategy
Consistent Hash Ring
Virtual Node Distribution:─────────────────────────────────────────────────Hash Ring (0 to 2^64)─────────────────────────────────────────────────0% 25% 50% 75% 100%│ │ │ │ │├──────┼──────┼──────┼──────┤│ N1 │ N2 │ N3 │ N1 │ (Physical nodes)│ │ │ │ │├──┬──┬┼──┬──┬┼──┬──┬┼──┬──┬┤│v1│v2││v1│v2││v1│v2││v1│v2││ (Virtual nodes)└──┴──┴┴──┴──┴┴──┴──┴┴──┴──┴┘
Key Routing:hash(key) = 0x3A... → Maps to N2 (primary) → Next node N3 (mirror)Shard Replication
Shard 1:┌─────────────┐ sync ┌─────────────┐│ Primary │ ─────────────▶│ Mirror ││ (Node A) │ ◀──────────── │ (Node B) │└─────────────┘ ack └─────────────┘ │ │ │ │ └──────────┬───────────────────┘ │ ▼ ┌─────────────┐ │ Witness │ │ (Quorum) │ └─────────────┘
Failover:- Mirror loses connection to Primary- Mirror checks Witness- Witness confirms Primary down- 2/3 quorum achieved- Mirror promotes to PrimaryStorage Engine
LSM-tree Structure
┌────────────────────────────────────────┐│ Active Memtable ││ Sorted in-memory structure ││ - Sorted by key ││ - In-memory, fast writes │└────────────────────────────────────────┘ │ (threshold reached) ▼┌────────────────────────────────────────┐│ Immutable Memtables (queue) ││ - Frozen for flushing ││ - Still readable │└────────────────────────────────────────┘ │ (background flush) ▼┌────────────────────────────────────────┐│ SSTables (on-disk) ││ ││ SSTable-0000001.sst (newest) ││ ┌──────────────────────────────────┐ ││ │ Data Block 1 │ ││ │ Data Block 2 │ ││ │ ... │ ││ │ Bloom Filter │ ││ │ Metadata (min/max key) │ ││ └──────────────────────────────────┘ ││ ││ SSTable-0000002.sst ││ SSTable-0000003.sst (oldest) │└────────────────────────────────────────┘ │ (compaction) ▼┌────────────────────────────────────────┐│ Compacted SSTables (merged) ││ - Remove duplicates ││ - Discard tombstones ││ - Larger, fewer files │└────────────────────────────────────────┘Deployment Topology
┌─────────────────────────────────────────────────┐│ Load Balancer ││ (Protocol Router) │└─────────────────────────────────────────────────┘ │ ┌──────────────┼──────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │Compute 1│ │Compute 2│ │Compute N│ └─────────┘ └─────────┘ └─────────┘ │ │ │ └──────────────┼──────────────┘ │ HIDB Protocol ┌──────────────┼──────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │Storage 1│───▶│Storage 2│───▶│Storage 3│ │(Primary)│ │(Mirror) │ │(Primary)│ └─────────┘ └─────────┘ └─────────┘ │ │ │ └──────────────┼──────────────┘ │ ┌──────────────┼──────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │Metadata │ │Metadata │ │Metadata │ │ Node 1 │◀──▶│ Node 2 │◀──▶│ Node 3 │ │(Leader) │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘Scaling Dimensions
Compute Scale-Out
- Add more compute nodes for higher query concurrency
- Stateless, can be spun up/down dynamically
- Shared-nothing architecture
Storage Scale-Out
- Add more storage nodes for capacity
- Consistent hashing automatically rebalances
- Data migration happens in background
Metadata Scale-Up
- Fixed cluster size (3 or 5 nodes)
- Raft leader handles writes
- All nodes handle reads
This architecture provides:
- Separation of concerns: Compute, storage, and metadata independent
- Linear scalability: Add nodes for capacity or throughput
- Fault tolerance: Replication at every layer
- Performance: Intelligent storage with predicate pushdown
- Flexibility: Multi-protocol support for diverse clients