Concept
Each Helix Cloud cluster runs one writer and two readers behind a routing gateway. The
writer commits every write, the readers serve reads, and object storage holds the data.
Shared-plan databases share a regional cluster; a dedicated cluster serves only your
databases.
Helix Cloud is a fundamentally different architecture and database compared to the open-source v1
version of HelixDB. That version used LMDB, which was limited to sequential writes and could only handle
a relatively small amount of data. Helix Cloud uses a new LSM-based storage engine backed by object
storage that can handle concurrent writes to the writer node and allows for virtually unlimited data storage.
Gateway
The gateway is the entry point for all client traffic. It authenticates each request’s API key, applies the request rate limit on shared plans, and routes writes to the writer and reads to a reader. A read goes to the writer only when it setsX-Helix-Require-Writer: true. Each cluster runs several gateway
replicas.
Writer
A single writer process handles all mutations. The writer supports concurrent write transactions through MVCC (multi-version concurrency control), allowing multiple writes to execute in parallel without blocking each other. Serializing the commit path through one process keeps the consistency model simple. The writer batches mutations for throughput and persists them durably to object storage before acknowledging. A read sent to the writer withX-Helix-Require-Writer: true sees every committed write
immediately, with no snapshot refresh delay.
Readers
The two readers serve every other read. Each keeps its own memory and SSD cache, filled from object storage, and sees a new write once it refreshes to a snapshot that contains it. See read-after-write. The reader count is fixed; it does not grow with load. The gateway retries transient reader failures, but with no reader available a read fails with503 backend_unavailable rather
than moving to the writer; retry with backoff. Contact
founders@helix-db.com if you need more read capacity.
Writer failover
Helix elects the writer through a lease. If the writer fails, Helix promotes a healthy reader and fences the old writer so it cannot commit after the new one takes over. Meanwhile:- Writes wait up to 90 seconds for the new writer. If none is ready, the gateway returns
503failover_wait_unavailablewithout sending the write; retry after itsRetry-After. - A write already sent when the writer changed returns
503write_outcome_unknown. It may have committed, so reconcile before resubmitting; see Timed-out writes. - Reads continue on the readers.
Object storage
Object storage is the durable system of record. All graph data, vector indexes, text index artifacts, and metadata persist here. No data lives exclusively on local disk. This means the system can recover from a full cache loss by reading from object storage, and storage capacity is effectively unbounded.Cache hierarchy
Each process (writer and readers) caches the data it reads:- In-memory cache. Fastest access. Holds the hottest storage blocks and vector search state. Bounded by available RAM.
- SSD cache. Larger capacity, lower cost per byte. Holds warm storage blocks and object storage files. Reads from SSD are significantly faster than reads from object storage.
X-Helix-Warm: true.
Read path
- The gateway sends the read to a reader, or to the writer when it sets
X-Helix-Require-Writer: true. - The process resolves a consistent snapshot from object storage metadata.
- Data is read from the in-memory cache, SSD cache, or object storage (in that order).
- The query executes against the snapshot and returns results.
Write path
- A write request arrives at the gateway and is routed to the writer.
- The writer executes the mutation within a serializable transaction. Multiple write transactions execute concurrently via MVCC; conflicts are resolved at commit time.
- The mutation is batched and persisted durably to object storage.
- Once durable, the write is acknowledged to the client.
- Readers observe the new data on their next snapshot refresh.
Next steps
Data Model
Nodes, edges, properties, and the labeled multigraph model.
Indexing
Secondary, vector, and text indexes over the property graph.
Reading data
Select and traverse graph data with the SDKs.
Guarantees
Consistency, durability, and isolation under this architecture.