--- title: "HeliosDB Architecture" --- # HeliosDB Architecture :::caution[Planned: clustering] HeliosDB Full runs as a single server; Raft clustering, multi-region replication and sharding are planned. The shard, replication and multi-node parts of this page describe the planned cluster. The Snowflake and Pinecone HTTP APIs in the diagram are planned as well; today their paths answer 501 Not Implemented. ::: ## 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 INSERT Compute 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 client ``` ### Read 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 client ``` ### Analytical Query with Predicate Pushdown ``` Client │ ▼ SQL SELECT * FROM table WHERE col > 100 Compute 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 client ``` ### Vector 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 client ``` ## Sharding 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 Primary ``` ## Storage 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